1# SysRq Support in SOL 2 3Author: Lei Yu <LeiYU!> 4 5Other contributors: Chen Tingting, Xie Xinnan 6 7Created: Aug 02, 2023 8 9## Problem Description 10 11[SysRq][1] is a special key combination used by Linux to perform various 12low-level commands. BMC usually provides SysRq support in KVM and SOL functions, 13but this is not available in OpenBMC. This doc is to provide the SysRq support 14in OpenBMC's SOL. 15 16## Background and References 17 18The key combination consists of Alt+SysRq (usually the `PrintScreen` key) and 19another key, which controls the command issued. This is not typical key code and 20requires special handling. A serial console usually invokes SysRq feature by 21sending a serial break signal, followed by the desired key. The "break signal" 22is usually generated by `ctrl+break` key combination.[2] 23 24In ipmitool, the "break signal" is implemented in [ipmi_sol.c][3] by handling 25the special `\n~B` keys. 26 27## Requirements 28 29OpenBMC SOL involves several ways: 30 31- The ipmitool SOL. 32- The SOL in WebUI. 33- The console with SSH (default) 2200 port. 34 35## Proposed Design 36 37In OpenBMC, the service `obmc-console-server` provides the host console and 38could be connected by multiple clients, using unix domain socket. 39 40To implement the SysRq in OpenBMC SOL for ipmi and WebUI, the special key code 41sequence `\n~B` is used to send the "break signal" between clients and 42console-server. In `obmc-console`, a state machine shall handle the sequence. 43Once the sequence is detected, it could invoke `tcsendbreak()` to send the 44"break signal" to the Host. 45 46### netipmid 47 48In `phosphor-ipmi-net`, the code in `processInboundPayload()` shall handle the 49break signal from ipmitool, and send the sequence `\n~B` to the server. 50 51Then in ipmitool SOL session, user could enter `\n~B` keys to trigger the break, 52and then enter a keycode as the SysRq command. 53 54### WebUI 55 56There are no changes required in WebUI, like netipmid, the user could enter the 57key code sequence `\n~B` to trigger the break, and then user could enter a 58keycode as the SysRq command. 59 60### obmc-console 61 62As the obmc-console server, in `console-server.h`, a simple state machine is 63used to detect the sequence `\n~B`: 64 65```mermaid 66--- 67title: SysRq escape state machine 68--- 69stateDiagram-v2 70 [*] --> Empty 71 Empty --> Emit: [^#92;n] 72 Emit --> [*] 73 Empty --> Newline: [#92;n] 74 Newline --> Escape: [~] 75 Newline --> EmitNewline: [^#92;n] 76 Escape --> EmitEscapeCode: [B] 77 EmitEscapeCode --> [*] 78 EmitNewline --> [*] 79 Escape --> EmitNewlineTilde: [^B] 80 EmitNewlineTilde --> [*] 81``` 82 83If `EmitEscapeCode` state is reached, it shall call `tcsendbreak()` to send the 84"break message" to the Host. 85 86## Alternatives Considered 87 88An alternative way to send the "break signal" between clients and console-server 89is use `MSG_OOB` as the indicator of sysrq. The `MSG_OOB` was already introduced 90to [netipmid][4] as the indicator of sysrq. In this solution, bmcweb shall be 91modified to send `MSG_OOB` to obmc-console when the user enter the key code 92sequence `\n~B`. When obmc-console receive `MSG_OOB`, it shall send the "break 93message" to the Host. 94 95However, in this solution, in some scenarios, obmc-console can not handle the 96input sequence correctly, as `MSG_OOB` can be anywhere in the input sequence. It 97is possible to synchronise the `MSG_OOB` with the stream with 98[sockatmark(3)][5]. But it requires signalling the `MSG_OOB` in all obmc-console 99clients, which is more work than the state machine solution. 100 101## Impacts 102 103Below services need minor changes to add the SysRq support: 104 105- netipmid 106- obmc-console 107 108## Testing 109 110The SysRq in SOL could be verified in both ipmitool SOL and WebUI SOL. In SOL 111with SSH, we need enter the key code sequence with more than one tilde. Like 112sequence `\n~~B`, the first tilde will be processed by obmc-console-client, the 113second tilde will reach obmc-console-server. 114 115[1]: https://en.wikipedia.org/wiki/Magic_SysRq_key 116[2]: https://www.kernel.org/doc/html/latest/admin-guide/sysrq.html 117[3]: https://github.com/ipmitool/ipmitool/blob/master/lib/ipmi_sol.c#L1398-L1401 118[4]: 119 https://github.com/openbmc/phosphor-net-ipmid/commit/ec4374146147e339132243725d345eb30ec2da1d 120[5]: https://man7.org/linux/man-pages/man3/sockatmark.3.html 121