The SERCON module allows a user to communicate with a remote node's serial console. The remote node must support some form of serial based console. In this section, we will cover the SERCON module features, how to setup serial console on a variety of different nodes, and how to use the SERCON module.
The SERCON module provides more than just the ability to manage a remote node via it's console. Multiple administrators may be connected to the same console simultaneously, although only one is able to write. An alert mechanism is also supported to trap critical events that may wish to be logged. By specifying an alert string, along with the number of lines to capture, critical messages or events can be saved in the modules alert log for later review.
The CONFIGURATION command is used to configure the device/address, and baudrate parameters for a remote console. To disable VACM SERCON management for a node, set the DEVICE/ADDRESS to 'NONE'
FORMAT:
SERCON:CONFIGURATION:<NODE_ID>:<DEVICE/ADDRESS>:<BPS>
RESPONSES:
JOB_STARTED
JOB_ERROR:(errno string)
JOB_COMPLETED
FIELDS:
<DEVICE/ADDRESS> - either a /dev/device entry, or a network
address and port to connect to. Network
addresses should be specified as
xxx.xxx.xxx-yyy, where x is the network
address portion, and y is the target
port portion. If <DEVICE/ADDRESS>
is set to 'NONE', then SERCON management
and monitoring is disabled for the
specified node. |
The device and baudrate settings for a node are obtained with the 'INQUIRY' command.
FORMAT: SERCON:INQUIRY:<NODE_ID> RESPONSES: JOB_STARTED INQUIRY:<NODE_ID>:<DEVICE_ADDRESS>:<BAUDRATE> JOB_ERROR:(errno string) JOB_COMPLETED |
The 'CONNECT' command is used to request a console connection between the client and the node. If a RO (read only) request is made, it will always be granted as long as the node is configured with a proper device/address. If a RW (read/write) request is made, the request will only be granted if no other clients have requested a RW connection. The 'LIST_CONNECTIONS' and 'FORCE_DISCONNECT' commands may be used to terminate an existing RW connection to allow a new writer. If a connection is granted, the module will return a TCP/IP address, port number, and ASCII one time use password for the client to connect to for console access. The one time password is used to ensure authorized access to the console. This connection will remain open unless the following events occur:
The client -> TCP console connection is closed
The requesting client issues a 'DISCONNECT' command
Any client issues a 'FORCE_DISCONNECT' command
The requesting client -> Nexxus connection is closed
FORMAT: SERCON:CONNECT:<NODE_ID>:<RO/RW> RESPONSES: JOB_STARTED CONNECT:<FD>:<IP_ADDRESS>:<PORT>:<PASSWORD> JOB_ERROR:(errno string) JOB_COMPLETED |
A client may disconnect it's console connection cleanly by issuing the 'DISCONNECT' command. This command instructs the SERCON module to close it's TCP connection to the client. The 'DISCONNECT' command can only be used to disconnect sessions that were 'CONNECT'ed from the same client. To disconnect an arbitrary session, use the 'FORCE_DISCONNECT' command.
FORMAT: SERCON:DISCONNECT:<NODE_ID>:<FD> RESPONSES: JOB_STARTED JOB_ERROR:(errno string) JOB_COMPLETED |
A list of connections to a current node's console is obtained with the 'LIST_CONNECTIONS' command. This command returns the client FD handle, IP address, connection time, and access mode for each client connected. The FD handle can be used for future 'FORCE_DISCONNECTION' command. The IP_ADDRESS field may be 0.0.0.0 if the connection has not yet been established with the client. The connection time is specified in HH MM SS.
FORMAT: SERCON:LIST_CONNECTIONS:<NODE_ID> RESPONSES: JOB_STARTED CONNECTION:<FD>:<IP_ADDRESS>:<CONNECT TIME>:<RO/RW> JOB_ERROR:(errno string) JOB_COMPLETED |
A connection can be force disconnected with the 'FORCE_DISCONNECT' command.
FORMAT: SERCON:FORCE_DISCONNECT:<NODE_ID>:<FD> RESPONSES: JOB_STARTED JOB_ERROR:(errno string) JOB_COMPLETED |
Write mode may be 'stolen' from another console in read/write mode if the target console has been idle for more than five minutes.
FORMAT: SERCON:STEAL_CONNECTION:<NODE_ID>:<FD_RO>:<FD_RW> RESPONSES: JOB_STARTED JOB_ERROR:(errno string) JOB_COMPLETED |
Console alerts are background monitors which the sercon module uses to identify events which the user wishes to keep track of. To add a console alert, use the 'ALERT_ADD' command, passing in the number of lines to capture and a trigger string. The trigger string may contain any printable character.
FORMAT: SERCON:ALERT_ADD:<NODE_ID>:<NUM_LINES_TO_CAPTURE>:<TRIGGER_STRING> RESPONSES: JOB_STARTED JOB_ERROR:(errno string) JOB_COMPLETED |
To delete a previously configured console aert, use the 'ALERT_DEL' command. This command requires the alert ID, which can be obtained with the 'ALERT_LIST' command.
FORMAT: SERCON:ALERT_DEL:<NODE_ID>:<ALERT_ID> RESPONSES: JOB_STARTED JOB_ERROR:(errno string) JOB_COMPLETED |
A list of all currently configured console alerts for a node is obtained with the 'ALERT_LIST' command.
FORMAT: SERCON:ALERT_LIST:<NODE_ID> RESPONSES: JOB_STARTED ALERT:<ALERT_ID>:<NUM_LINES_TO_CAPTURE>:<TRIGGER_STRING> JOB_ERROR:(errno string) JOB_COMPLETED |
Console alert logs containing any triggered alerts are downloaded from the module with the 'ALERT_DUMP' command
FORMAT: SERCON:ALERT_DUMP:<NODE_ID> RESPONSES: JOB_STARTED ALERT:<TRIGGER_STRING>:<CAPTURE_LINE>:<MAX_LINES>:<CAPTURED_LINE> JOB_ERROR:(errno string) JOB_COMPLETED |
The console alert log is cleared for a node with the 'ALERT_CLEAR' command.
FORMAT: SERCON:ALERT_CLEAR:<NODE_ID> RESPONSES: JOB_STARTED JOB_ERROR:(errno string) JOB_COMPLETED |
The SERCON module has no node global variable requirements.