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