sysrq.rst 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292
  1. Linux Magic System Request Key Hacks
  2. ====================================
  3. Documentation for sysrq.c
  4. What is the magic SysRq key?
  5. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  6. It is a 'magical' key combo you can hit which the kernel will respond to
  7. regardless of whatever else it is doing, unless it is completely locked up.
  8. How do I enable the magic SysRq key?
  9. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  10. You need to say "yes" to 'Magic SysRq key (CONFIG_MAGIC_SYSRQ)' when
  11. configuring the kernel. When running a kernel with SysRq compiled in,
  12. /proc/sys/kernel/sysrq controls the functions allowed to be invoked via
  13. the SysRq key. The default value in this file is set by the
  14. CONFIG_MAGIC_SYSRQ_DEFAULT_ENABLE config symbol, which itself defaults
  15. to 1. Here is the list of possible values in /proc/sys/kernel/sysrq:
  16. - 0 - disable sysrq completely
  17. - 1 - enable all functions of sysrq
  18. - >1 - bitmask of allowed sysrq functions (see below for detailed function
  19. description)::
  20. 2 = 0x2 - enable control of console logging level
  21. 4 = 0x4 - enable control of keyboard (SAK, unraw)
  22. 8 = 0x8 - enable debugging dumps of processes etc.
  23. 16 = 0x10 - enable sync command
  24. 32 = 0x20 - enable remount read-only
  25. 64 = 0x40 - enable signalling of processes (term, kill, oom-kill)
  26. 128 = 0x80 - allow reboot/poweroff
  27. 256 = 0x100 - allow nicing of all RT tasks
  28. You can set the value in the file by the following command::
  29. echo "number" >/proc/sys/kernel/sysrq
  30. The number may be written here either as decimal or as hexadecimal
  31. with the 0x prefix. CONFIG_MAGIC_SYSRQ_DEFAULT_ENABLE must always be
  32. written in hexadecimal.
  33. Note that the value of ``/proc/sys/kernel/sysrq`` influences only the invocation
  34. via a keyboard. Invocation of any operation via ``/proc/sysrq-trigger`` is
  35. always allowed (by a user with admin privileges).
  36. How do I use the magic SysRq key?
  37. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  38. On x86
  39. You press the key combo :kbd:`ALT-SysRq-<command key>`.
  40. .. note::
  41. Some
  42. keyboards may not have a key labeled 'SysRq'. The 'SysRq' key is
  43. also known as the 'Print Screen' key. Also some keyboards cannot
  44. handle so many keys being pressed at the same time, so you might
  45. have better luck with press :kbd:`Alt`, press :kbd:`SysRq`,
  46. release :kbd:`SysRq`, press :kbd:`<command key>`, release everything.
  47. On SPARC
  48. You press :kbd:`ALT-STOP-<command key>`, I believe.
  49. On the serial console (PC style standard serial ports only)
  50. You send a ``BREAK``, then within 5 seconds a command key. Sending
  51. ``BREAK`` twice is interpreted as a normal BREAK.
  52. On PowerPC
  53. Press :kbd:`ALT - Print Screen` (or :kbd:`F13`) - :kbd:`<command key>`.
  54. :kbd:`Print Screen` (or :kbd:`F13`) - :kbd:`<command key>` may suffice.
  55. On other
  56. If you know of the key combos for other architectures, please
  57. let me know so I can add them to this section.
  58. On all
  59. Write a character to /proc/sysrq-trigger. e.g.::
  60. echo t > /proc/sysrq-trigger
  61. The :kbd:`<command key>` is case sensitive.
  62. What are the 'command' keys?
  63. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  64. =========== ===================================================================
  65. Command Function
  66. =========== ===================================================================
  67. ``b`` Will immediately reboot the system without syncing or unmounting
  68. your disks.
  69. ``c`` Will perform a system crash by a NULL pointer dereference.
  70. A crashdump will be taken if configured.
  71. ``d`` Shows all locks that are held.
  72. ``e`` Send a SIGTERM to all processes, except for init.
  73. ``f`` Will call the oom killer to kill a memory hog process, but do not
  74. panic if nothing can be killed.
  75. ``g`` Used by kgdb (kernel debugger)
  76. ``h`` Will display help (actually any other key than those listed
  77. here will display help. but ``h`` is easy to remember :-)
  78. ``i`` Send a SIGKILL to all processes, except for init.
  79. ``j`` Forcibly "Just thaw it" - filesystems frozen by the FIFREEZE ioctl.
  80. ``k`` Secure Access Key (SAK) Kills all programs on the current virtual
  81. console. NOTE: See important comments below in SAK section.
  82. ``l`` Shows a stack backtrace for all active CPUs.
  83. ``m`` Will dump current memory info to your console.
  84. ``n`` Used to make RT tasks nice-able
  85. ``o`` Will shut your system off (if configured and supported).
  86. ``p`` Will dump the current registers and flags to your console.
  87. ``q`` Will dump per CPU lists of all armed hrtimers (but NOT regular
  88. timer_list timers) and detailed information about all
  89. clockevent devices.
  90. ``r`` Turns off keyboard raw mode and sets it to XLATE.
  91. ``s`` Will attempt to sync all mounted filesystems.
  92. ``t`` Will dump a list of current tasks and their information to your
  93. console.
  94. ``u`` Will attempt to remount all mounted filesystems read-only.
  95. ``v`` Forcefully restores framebuffer console
  96. ``v`` Causes ETM buffer dump [ARM-specific]
  97. ``w`` Dumps tasks that are in uninterruptable (blocked) state.
  98. ``x`` Used by xmon interface on ppc/powerpc platforms.
  99. Show global PMU Registers on sparc64.
  100. Dump all TLB entries on MIPS.
  101. ``y`` Show global CPU Registers [SPARC-64 specific]
  102. ``z`` Dump the ftrace buffer
  103. ``0``-``9`` Sets the console log level, controlling which kernel messages
  104. will be printed to your console. (``0``, for example would make
  105. it so that only emergency messages like PANICs or OOPSes would
  106. make it to your console.)
  107. =========== ===================================================================
  108. Okay, so what can I use them for?
  109. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  110. Well, unraw(r) is very handy when your X server or a svgalib program crashes.
  111. sak(k) (Secure Access Key) is useful when you want to be sure there is no
  112. trojan program running at console which could grab your password
  113. when you would try to login. It will kill all programs on given console,
  114. thus letting you make sure that the login prompt you see is actually
  115. the one from init, not some trojan program.
  116. .. important::
  117. In its true form it is not a true SAK like the one in a
  118. c2 compliant system, and it should not be mistaken as
  119. such.
  120. It seems others find it useful as (System Attention Key) which is
  121. useful when you want to exit a program that will not let you switch consoles.
  122. (For example, X or a svgalib program.)
  123. ``reboot(b)`` is good when you're unable to shut down, it is an equivalent
  124. of pressing the "reset" button.
  125. ``crash(c)`` can be used to manually trigger a crashdump when the system is hung.
  126. Note that this just triggers a crash if there is no dump mechanism available.
  127. ``sync(s)`` is handy before yanking removable medium or after using a rescue
  128. shell that provides no graceful shutdown -- it will ensure your data is
  129. safely written to the disk. Note that the sync hasn't taken place until you see
  130. the "OK" and "Done" appear on the screen.
  131. ``umount(u)`` can be used to mark filesystems as properly unmounted. From the
  132. running system's point of view, they will be remounted read-only. The remount
  133. isn't complete until you see the "OK" and "Done" message appear on the screen.
  134. The loglevels ``0``-``9`` are useful when your console is being flooded with
  135. kernel messages you do not want to see. Selecting ``0`` will prevent all but
  136. the most urgent kernel messages from reaching your console. (They will
  137. still be logged if syslogd/klogd are alive, though.)
  138. ``term(e)`` and ``kill(i)`` are useful if you have some sort of runaway process
  139. you are unable to kill any other way, especially if it's spawning other
  140. processes.
  141. "just thaw ``it(j)``" is useful if your system becomes unresponsive due to a
  142. frozen (probably root) filesystem via the FIFREEZE ioctl.
  143. Sometimes SysRq seems to get 'stuck' after using it, what can I do?
  144. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  145. That happens to me, also. I've found that tapping shift, alt, and control
  146. on both sides of the keyboard, and hitting an invalid sysrq sequence again
  147. will fix the problem. (i.e., something like :kbd:`alt-sysrq-z`). Switching to
  148. another virtual console (:kbd:`ALT+Fn`) and then back again should also help.
  149. I hit SysRq, but nothing seems to happen, what's wrong?
  150. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  151. There are some keyboards that produce a different keycode for SysRq than the
  152. pre-defined value of 99
  153. (see ``KEY_SYSRQ`` in ``include/uapi/linux/input-event-codes.h``), or
  154. which don't have a SysRq key at all. In these cases, run ``showkey -s`` to find
  155. an appropriate scancode sequence, and use ``setkeycodes <sequence> 99`` to map
  156. this sequence to the usual SysRq code (e.g., ``setkeycodes e05b 99``). It's
  157. probably best to put this command in a boot script. Oh, and by the way, you
  158. exit ``showkey`` by not typing anything for ten seconds.
  159. I want to add SysRQ key events to a module, how does it work?
  160. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  161. In order to register a basic function with the table, you must first include
  162. the header ``include/linux/sysrq.h``, this will define everything else you need.
  163. Next, you must create a ``sysrq_key_op`` struct, and populate it with A) the key
  164. handler function you will use, B) a help_msg string, that will print when SysRQ
  165. prints help, and C) an action_msg string, that will print right before your
  166. handler is called. Your handler must conform to the prototype in 'sysrq.h'.
  167. After the ``sysrq_key_op`` is created, you can call the kernel function
  168. ``register_sysrq_key(int key, const struct sysrq_key_op *op_p);`` this will
  169. register the operation pointed to by ``op_p`` at table key 'key',
  170. if that slot in the table is blank. At module unload time, you must call
  171. the function ``unregister_sysrq_key(int key, const struct sysrq_key_op *op_p)``,
  172. which will remove the key op pointed to by 'op_p' from the key 'key', if and
  173. only if it is currently registered in that slot. This is in case the slot has
  174. been overwritten since you registered it.
  175. The Magic SysRQ system works by registering key operations against a key op
  176. lookup table, which is defined in 'drivers/tty/sysrq.c'. This key table has
  177. a number of operations registered into it at compile time, but is mutable,
  178. and 2 functions are exported for interface to it::
  179. register_sysrq_key and unregister_sysrq_key.
  180. Of course, never ever leave an invalid pointer in the table. I.e., when
  181. your module that called register_sysrq_key() exits, it must call
  182. unregister_sysrq_key() to clean up the sysrq key table entry that it used.
  183. Null pointers in the table are always safe. :)
  184. If for some reason you feel the need to call the handle_sysrq function from
  185. within a function called by handle_sysrq, you must be aware that you are in
  186. a lock (you are also in an interrupt handler, which means don't sleep!), so
  187. you must call ``__handle_sysrq_nolock`` instead.
  188. When I hit a SysRq key combination only the header appears on the console?
  189. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  190. Sysrq output is subject to the same console loglevel control as all
  191. other console output. This means that if the kernel was booted 'quiet'
  192. as is common on distro kernels the output may not appear on the actual
  193. console, even though it will appear in the dmesg buffer, and be accessible
  194. via the dmesg command and to the consumers of ``/proc/kmsg``. As a specific
  195. exception the header line from the sysrq command is passed to all console
  196. consumers as if the current loglevel was maximum. If only the header
  197. is emitted it is almost certain that the kernel loglevel is too low.
  198. Should you require the output on the console channel then you will need
  199. to temporarily up the console loglevel using :kbd:`alt-sysrq-8` or::
  200. echo 8 > /proc/sysrq-trigger
  201. Remember to return the loglevel to normal after triggering the sysrq
  202. command you are interested in.
  203. I have more questions, who can I ask?
  204. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  205. Just ask them on the linux-kernel mailing list:
  206. linux-kernel@vger.kernel.org
  207. Credits
  208. ~~~~~~~
  209. - Written by Mydraal <vulpyne@vulpyne.net>
  210. - Updated by Adam Sulmicki <adam@cfar.umd.edu>
  211. - Updated by Jeremy M. Dolan <jmd@turbogeek.org> 2001/01/28 10:15:59
  212. - Added to by Crutcher Dunnavant <crutcher+kernel@datastacks.com>