Skip to main content

6. Interactive Sessions

6. Interactive Sessions​

A session is a remote execution of a program. The program may be a shell, an application, a system command, or some built-in subsystem. It may or may not have a tty, and may or may not involve X11 forwarding. Multiple sessions can be active simultaneously.

6.1. Opening a Session​

A session is started by sending the following message.

byte      SSH_MSG_CHANNEL_OPEN
string    "session"
uint32    sender channel
uint32    initial window size
uint32    maximum packet size

Client implementations SHOULD reject any session channel open requests to make it more difficult for a corrupt server to attack the client.

6.2. Requesting a Pseudo-Terminal​

A pseudo-terminal can be allocated for the session by sending the following message.

byte      SSH_MSG_CHANNEL_REQUEST
uint32    recipient channel
string    "pty-req"
boolean   want_reply
string    TERM environment variable value (e.g., vt100)
uint32    terminal width, characters (e.g., 80)
uint32    terminal height, rows (e.g., 24)
uint32    terminal width, pixels (e.g., 640)
uint32    terminal height, pixels (e.g., 480)
string    encoded terminal modes

The encoded terminal modes are described in Section 8. Zero dimension parameters MUST be ignored. The character/row dimensions override the pixel dimensions (when nonzero). Pixel dimensions refer to the drawable area of the window.

The dimension parameters are only informational.

The client SHOULD ignore pty requests.

6.3. X11 Forwarding​

6.3.1. Requesting X11 Forwarding​

X11 forwarding may be requested for a session by sending a SSH_MSG_CHANNEL_REQUEST message.

byte      SSH_MSG_CHANNEL_REQUEST
uint32    recipient channel
string    "x11-req"
boolean   want reply
boolean   single connection
string    x11 authentication protocol
string    x11 authentication cookie
uint32    x11 screen number

It is RECOMMENDED that the x11 authentication cookie that is sent be a fake, random cookie, and that the cookie be checked and replaced by the real cookie when a connection request is received.

X11 connection forwarding should stop when the session channel is closed. However, already opened forwardings should not be automatically closed when the session channel is closed.

If single connection is TRUE, only a single connection should be forwarded. No more connections will be forwarded after the first, or after the session channel has been closed.

The x11 authentication protocol is the name of the X11 authentication method used, e.g., "MIT-MAGIC-COOKIE-1".

The x11 authentication cookie MUST be hexadecimal encoded.

The X Protocol is documented in [SCHEIFLER].

6.3.2. X11 Channels​

X11 channels are opened with a channel open request. The resulting channels are independent of the session, and closing the session channel does not close the forwarded X11 channels.

byte      SSH_MSG_CHANNEL_OPEN
string    "x11"
uint32    sender channel
uint32    initial window size
uint32    maximum packet size
string    originator address (e.g., "192.168.7.38")
uint32    originator port

The recipient should respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION or SSH_MSG_CHANNEL_OPEN_FAILURE.

Implementations MUST reject any X11 channel open requests if they have not requested X11 forwarding.

6.4. Environment Variable Passing​

Environment variables may be passed to the shell/command to be started later. Uncontrolled setting of environment variables in a privileged process can be a security hazard. It is recommended that implementations either maintain a list of allowable variable names or only set environment variables after the server process has dropped sufficient privileges.

byte      SSH_MSG_CHANNEL_REQUEST
uint32    recipient channel
string    "env"
boolean   want reply
string    variable name
string    variable value

6.5. Starting a Shell or a Command​

Once the session has been set up, a program is started at the remote end. The program can be a shell, an application program, or a subsystem with a host-independent name. Only one of these requests can succeed per channel.

byte      SSH_MSG_CHANNEL_REQUEST
uint32    recipient channel
string    "shell"
boolean   want reply

This message will request that the user's default shell (typically defined in /etc/passwd in UNIX systems) be started at the other end.

byte      SSH_MSG_CHANNEL_REQUEST
uint32    recipient channel
string    "exec"
boolean   want reply
string    command

This message will request that the server start the execution of the given command. The command string may contain a path. Normal precautions MUST be taken to prevent the execution of unauthorized commands.

byte      SSH_MSG_CHANNEL_REQUEST
uint32    recipient channel
string    "subsystem"
boolean   want reply
string    subsystem name

This last form executes a predefined subsystem. It is expected that these will include a general file transfer mechanism, and possibly other features. Implementations may also allow configuring more such mechanisms. As the user's shell is usually used to execute the subsystem, it is advisable for the subsystem protocol to have a "magic cookie" at the beginning of the protocol transaction to distinguish it from arbitrary output generated by shell initialization scripts, etc. This spurious output from the shell may be filtered out either at the server or at the client.

The server SHOULD NOT halt the execution of the protocol stack when starting a shell or a program. All input and output from these SHOULD be redirected to the channel or to the encrypted tunnel.

It is RECOMMENDED that the reply to these messages be requested and checked. The client SHOULD ignore these messages.

Subsystem names follow the DNS extensibility naming convention outlined in [SSH-NUMBERS].

6.6. Session Data Transfer​

Data transfer for a session is done using SSH_MSG_CHANNEL_DATA and SSH_MSG_CHANNEL_EXTENDED_DATA packets and the window mechanism. The extended data type SSH_EXTENDED_DATA_STDERR has been defined for stderr data.

6.7. Window Dimension Change Message​

When the window (terminal) size changes on the client side, it MAY send a message to the other side to inform it of the new dimensions.

byte      SSH_MSG_CHANNEL_REQUEST
uint32    recipient channel
string    "window-change"
boolean   FALSE
uint32    terminal width, columns
uint32    terminal height, rows
uint32    terminal width, pixels
uint32    terminal height, pixels

A response SHOULD NOT be sent to this message.

6.8. Local Flow Control​

On many systems, it is possible to determine if a pseudo-terminal is using control-S/control-Q flow control. When flow control is allowed, it is often desirable to do the flow control at the client end to speed up responses to user requests. This is facilitated by the following notification. Initially, the server is responsible for flow control. (Here, again, client means the side originating the session, and server means the other side.)

The message below is used by the server to inform the client when it can or cannot perform flow control (control-S/control-Q processing). If client can do is TRUE, the client is allowed to do flow control using control-S and control-Q. The client MAY ignore this message.

byte      SSH_MSG_CHANNEL_REQUEST
uint32    recipient channel
string    "xon-xoff"
boolean   FALSE
boolean   client can do

No response is sent to this message.

6.9. Signals​

A signal can be delivered to the remote process/service using the following message. Some systems may not implement signals, in which case they SHOULD ignore this message.

byte      SSH_MSG_CHANNEL_REQUEST
uint32    recipient channel
string    "signal"
boolean   FALSE
string    signal name (without the "SIG" prefix)

signal name values will be encoded as discussed in the passage describing SSH_MSG_CHANNEL_REQUEST messages using "exit-signal" in this section.

6.10. Returning Exit Status​

When the command running at the other end terminates, the following message can be sent to return the exit status of the command. Returning the status is RECOMMENDED. No acknowledgement is sent for this message. The channel needs to be closed with SSH_MSG_CHANNEL_CLOSE after this message.

The client MAY ignore these messages.

byte      SSH_MSG_CHANNEL_REQUEST
uint32    recipient channel
string    "exit-status"
boolean   FALSE
uint32    exit_status

The remote command may also terminate violently due to a signal. Such a condition can be indicated by the following message. A zero exit_status usually means that the command terminated successfully.

byte      SSH_MSG_CHANNEL_REQUEST
uint32    recipient channel
string    "exit-signal"
boolean   FALSE
string    signal name (without the "SIG" prefix)
boolean   core dumped
string    error message in ISO-10646 UTF-8 encoding
string    language tag [RFC3066]

The signal name is one of the following (these are from [POSIX]).

ABRT
ALRM
FPE
HUP
ILL
INT
KILL
PIPE
QUIT
SEGV
TERM
USR1
USR2

Additional signal name values MAY be sent in the format "sig-name@xyz", where "sig-name" and "xyz" may be anything a particular implementer wants (except the "@" sign). However, it is suggested that if a configure script is used, any non-standard signal name values it finds be encoded as "[email protected]", where "SIG" is the signal name without the "SIG" prefix, and "xyz" is the host type, as determined by "config.guess".

The error message contains an additional textual explanation of the error message. The message may consist of multiple lines separated by CRLF (Carriage Return - Line Feed) pairs. The client software MAY display this message to the user. If this is done, the client software should take the precautions discussed in [SSH-ARCH].

Last updated on