This appendix provides information about terminal mode commands. Terminal mode allows you to directly connect to the system's Baseboard Management Controller (BMC) using a serial port connection and execute text-based commands. Two types of text commands are supported:
A limited selection of text commands
Standard binary IPMI 1.5 hex-ASCII commands
Use the Terminal Mode feature to perform the following tasks:
Power the server on or off.
Reset the server.
Retrieve the server's health status.
Configure and retrieve the server management subsystems boot options.
Configure and retrieve the BMC's terminal mode configuration.
Execute any platform supported binary command specified in the Intelligent Platform Management Interface (IPMI) version 1.5 specification using the hex-ASCII format.
NOTE: Many of the Terminal Mode features described in this section require an extensive knowledge of
IPMI. It is strongly recommended that Terminal Mode users have an advanced understanding of IPMI
before using the commands documented in this section.
Security Information
Access to the BMC using terminal mode is governed by the proper setup of user names and password. See "Configuring Your Managed System" for more information. A session must be established with the BMC prior to accepting any terminal mode commands. A limited selection of text commands and binary hex-ASCII commands that are assigned the lowest IPMI privilege level are available prior to session establishment with the BMC.
Since the terminal mode password is sent using clear text, it is highly desirable that the terminal mode session takes place in a secure location over a secure link by using a direct connection.
Syntax
Terminal mode messages follow the general syntax below:
[<message data>]<newline sequence>
Each terminal mode message must be preceded with the left bracket "start" character and must be ended with a right bracket "stop" character and the appropriate input new-line sequence.
No input characters are accepted until the start character has been received.
NOTE: Hex-ASCII commands can either use upper or lower-case letters for ASCII representations of
hex digits.
Command Length
Terminal mode messages are limited to a maximum length of 122 characters. This includes the left- and right-brackets, but not control characters.
Character Support
Terminal mode messages are composed of standard printable ASCII characters. All other characters are treated as illegal characters.
Special Character Handling — <ESC> character
The <ESC> character deletes an entire message prior to submission to the BMC for processing. If line editing is enabled, and the <ESC> key is followed by an input newline sequence, the BMC responds by outputting an output newline sequence. Otherwise, the BMC looks for the next start character.
Special Character Handling — <DEL> or <BKSP> character
The <BKSP> or <DEL> key deletes the last character entered if the message has not been submitted to the BMC yet.
Special Character Handling — Line Continuation character
Long IPMI messages can be split across multiple lines by using the line continuation <BACKSLASH> character followed immediately by an input newline sequence. Line continuation character usage is supported for both text and hex-ASCII commands.
Special Character Handling — Illegal characters
Any illegal characters received by the BMC clear the message in progress and the BMC looks for the next start character.
Hex-ASCII Command Format
Binary IPMI commands are sent and received as a series of case-insensitive hex-ASCII pairs, where each is separated from the preceding pair by a single <space> character. Table B-1 lists the terminal mode requests to BMC and Table B-2 lists the terminal mode responses from BMC. The following is an example of a binary IPMI request message:
[18 00 22]<newline sequence>
Table B-1. Terminal Mode Request to BMC
Byte
Explanation
1
[7:2] – Net Function (even) [1:0] – Responder's LUN
2
[7:2] – Requester's Sequence Number [1:0] – Bridge field
3
Command Number
4:N
Data
Table B-2. Terminal Mode Response from BMC
Byte
Explanation
1
[7:2] – Net Function (odd) [1:0] – Responder's LUN
2
[7:2] – Requester's Sequence Number [1:0] – Bridge field
3
Command Number
4
Completion Code
5:N
Data
Text Command Format
Text commands do not support the bridging and sequence number fields present in the hex-ASCII commands. In addition, text commands are preceded by a prefix consisting of the string SYS. Table B-3 lists the terminal mode text commands and Table B-4 lists the terminal mode configuration.
Examples
Hex-ASCII command example (IPMI Reset Watchdog Cmd):
[18 00 22]<CR>
[1C 00 22 00]<CR-LF>
Text command example:
[SYS TMODE]<CR>
[OK TMODE]<CR-LF>
Table B-3. Terminal Mode Text Commands
Command
Switches
Description
SYS PWD
-U USERNAME <password>
-U activates a terminal mode session. USERNAME corresponds to the ASCII text for the username. <password> represents a printable password (up to 16 characters). If <password> is not provided, then a Null password (all binary 0's) is submitted. Passwords are case sensitive.
Either the SYS PWD command or the Activate Session IPMI message must be successfully executed before any command or IPMI messages are accepted.
NOTE: A modem connection may be automatically dropped if
multiple bad passwords are entered.
-N <password>
-N represents a Null username and <password> represents a printable password (up to 16 characters). If <password> is not provided, then a Null password (all binary 0's) is submitted. Passwords are case sensitive.
Either the SYS PWD command or the Activate Session IPMI message must be successfully executed before any command or IPMI messages are accepted.
NOTE: A modem connection may be automatically dropped if
multiple bad passwords are entered.
-X
-X immediately logs out any presently active session.
NOTE: Entering an invalid password with -U or -N does not allow you
to log on.
SYS TMODE
Used as a no-op confirm that Terminal Mode is active. The BMC returns an OK response followed by TMODE.
SYS SET BOOT XX YY ZZ AA BB
Sets the boot flags to direct a boot to the specified device following the next IPMI command or action initiated reset or power-on. XX...BB represent five hex-ASCII encoded bytes, which are the boot flags parameter in the Boot Option Parameters.
Upon receiving this command, the BMC automatically sets the valid bit in the boot options and sets all the Boot Initiator Acknowledge data bits to 1b.
SYS SET BOOTOPT XX YY...NN
This is a text version of the IPMI Set System Boot Options command. It allows any of the boot option parameters to be set, not just the boot flags. XX YY...NN represent the hex-ASCII encoding for the data bytes that are passed in the Set System Boot Options request.
XX — Parameter valid.
[7] — 1b = Mark parameter invalid / locked.
0b = Mark parameter valid / unlocked.
[6:0] — Boot option parameter selector .
YY...NN — Boot Option Parameter Data.
Passing 0-bytes of parameter data allows the parameter valid bit to be changed without affecting the present parameter setting.
SYS GET BOOTOPT XX YY ZZ
This is a text version of the IPMI Get System Boot Options command. It allows any of the boot option parameters to be retrieved.
XX YY ZZ represents the hex-ASCII for the data bytes that are passed in the Get System Boot Options request.
The BMC returns the data from the command in hex-ASCII format.
XX—Parameter selector.
[7]—Reserved.
[6:0]—Boot option parameter selector.
YY—Set Selector.
[7:0]—Selects a particular block or set of parameters under the given parameter selector.
Write as 00h if the parameter does not use a Set Selector.
ZZ—Block Selector.
Selects a particular block within a set of parameters
Write as 00h if the parameter does not use a Block Selector.
NOTE: There are no IPMI-specified Boot Options parameters that
use the block selector. However, this field is provided for consistency
with other configuration commands and as a placeholder for future
extension of the IPMI specification.
SYS SET TCFG
Returns the Terminal Mode Configuration bytes where XX and YY represent hex-ASCII encoding for the volatile version of data bytes 1 and 2 as specified in Table B-4, and AA BB represent hex-ASCII encoding of the non-volatile version.
V:XX <output termination sequence>
N:AA BB <output termination sequence>
-V XX YY
Sets the volatile Terminal Mode Configuration. XX and YY represent hex-ASCII encoding for data bytes 1 and 2 as specified in Table B-4. The BMC returns the same output as for SYS SET TCFG, above.
-N XX YY
Sets the non-volatile Terminal Mode Configuration. XX and YY represent hex-ASCII encoding for data bytes 1 and 2 as specified in Table B-4. The BMC returns the same output as for SYS SET TCFG, above.
SYS RESET
Directs the BMC to perform an immediate system hard reset.
SYS POWER OFF
Directs the BMC to perform an immediate system power off.
SYS POWER ON
Causes the BMC to initiate an immediate system power on.
SYS HEALTH QUERY
Causes the BMC to return a high level version of the system health status in "terse" format. The BMC returns a string with the following format if the command is accepted.
PWR:zzz H:xx T:xx V:xx PS:xx C:xx D:xx S:xx O:xx
Where:
PWR is system POWER state.
H is overall Health.
T is Temperature.
V is Voltage.
PS is Power Supply subsystem.
C is cooling subsystem (Fans).
D is Hard Drive / RAID Subsystem.
S is physical Security.
O is Other (OEM).
zzz is: ON, OFF (soft-off or mechanical off), SLP (sleep - used when sleep level cannot be distinguished), S4, S3, S2, S1, ?? (unknown).
and xx is: ok, nc, cr, nr, uf, or ?? where:
ok = OK (monitored parameters within normal operating ranges).
nc = non-critical ("warning": hardware outside normal operating range).
nr = non-recoverable ("potential damage": system hardware in jeopardy or damaged).
uf = unspecified fault (fault detected, but severity unspecified).
?? = status not available/unknown (typically because system power is OFF).
SYS HEALTH QUERY
-V
Causes the BMC to return a high level version of the system health status in multi-line "verbose" format. The BMC returns a string of the following format:
SYS Health:xx<output termination sequence>.
Power: ON, OFF (soft-off or mechanical off), SLEEP (sleep - used when can't distinguish sleep level), S4, S3, S2, S1, Unknown.
Temperature:xx<output termination sequence>.
Voltage:xx<output termination sequence>.
PowerSystem:xx<output termination sequence>.
Cooling:xx<output termination sequence>.
Drives:xx<output termination sequence>.
Security:xx<output termination sequence>.
Other:xx<output termination sequence>.
Where xx is:
OK (monitored parameters within normal operating ranges).
Non-critical ("warning": hardware outside normal operating range).
Non-recoverable ("potential damage": system hardware in jeopardy or damaged).
Unspecified fault (fault detected, but severity unspecified).
Unknown (status not available/unknown (typically because system power is OFF).
Table B-4. Terminal Mode Configuration
Byte
Explanation
1
[7:6]—Reserved.
[5]—Line Editing.
0b = Disable.
1b = Enable (Factory default).
[4]—Reserved.
[3:2]—Delete control (only applies when line editing is enabled).
00b = BMC outputs a <DEL> character when <BKSP> or < DEL > is received.
01b = BMC outputs a < BKSP >< SP >< BKSP > sequence when < BKSP > or < DEL > is received (Factory default).
[1]—Echo control0b = No echo 1b = Echo (BMC echoes characters it receives) (Factory default).
[0]—Handshaking—BMC outputs a [SYS]<newline> after receiving each terminal mode IPMI message and is ready to accept the next message.
0b = Disable.
1b = Enable (Factory default).
2
[7:4] - Output newline sequence (BMC to console). Selects what characters the BMC uses as the <newline> sequence when the BMC writes a line to the console in Terminal Mode.
0h = no termination sequence.
1h = <CR-LF> (Factory default)
2h = <NULL>
3h = <CR>
4h = <LF-CR>
5h = <LF>
All other = reserved
[3:0] - Input newline sequence (Console to BMC). Selects what characters the console uses as the <newline> sequence when writing to the BMC in Terminal Mode.
