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 "SIG@xyz.config.guess",
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].
7. TCP/IP Port Forwarding
7.1. Requesting Port Forwarding
A party need not explicitly request forwardings from its own end to
the other direction. However, if it wishes that connections to a
port on the other side be forwarded to the local side, it must
explicitly request this.
byte SSH_MSG_GLOBAL_REQUEST
string "tcpip-forward"
boolean want reply
string address to bind (e.g., "0.0.0.0")
uint32 port number to bind
The ’address to bind’ and ’port number to bind’ specify the IP
address (or domain name) and port on which connections for forwarding
are to be accepted. Some strings used for ’address to bind’ have
special-case semantics.
o "" means that connections are to be accepted on all protocol
families supported by the SSH implementation.
o "0.0.0.0" means to listen on all IPv4 addresses.
o "::" means to listen on all IPv6 addresses.
o "localhost" means to listen on all protocol families supported by
the SSH implementation on loopback addresses only ([RFC3330] and
[RFC3513]).
o "127.0.0.1" and "::1" indicate listening on the loopback
interfaces for IPv4 and IPv6, respectively.
Note that the client can still filter connections based on
information passed in the open request.
Implementations should only allow forwarding privileged ports if the
user has been authenticated as a privileged user.
Client implementations SHOULD reject these messages; they are
normally only sent by the client.
If a client passes 0 as port number to bind and has ’want reply’ as
TRUE, then the server allocates the next available unprivileged port
number and replies with the following message; otherwise, there is no
response-specific data.
byte SSH_MSG_REQUEST_SUCCESS
uint32 port that was bound on the server
A port forwarding can be canceled with the following message. Note
that channel open requests may be received until a reply to this
message is received.
byte SSH_MSG_GLOBAL_REQUEST
string "cancel-tcpip-forward"
boolean want reply
string address_to_bind (e.g., "127.0.0.1")
uint32 port number to bind
Client implementations SHOULD reject these messages; they are
normally only sent by the client.
7.2. TCP/IP Forwarding Channels
When a connection comes to a port for which remote forwarding has
been requested, a channel is opened to forward the port to the other
side.
byte SSH_MSG_CHANNEL_OPEN
string "forwarded-tcpip"
uint32 sender channel
uint32 initial window size
uint32 maximum packet size
string address that was connected
uint32 port that was connected
string originator IP address
uint32 originator port
Implementations MUST reject these messages unless they have
previously requested a remote TCP/IP port forwarding with the given
port number.
When a connection comes to a locally forwarded TCP/IP port, the
following packet is sent to the other side. Note that these messages
MAY also be sent for ports for which no forwarding has been
explicitly requested. The receiving side must decide whether to
allow the forwarding.
byte SSH_MSG_CHANNEL_OPEN
string "direct-tcpip"
uint32 sender channel
uint32 initial window size
uint32 maximum packet size
string host to connect
uint32 port to connect
string originator IP address
uint32 originator port
The ’host to connect’ and ’port to connect’ specify the TCP/IP host
and port where the recipient should connect the channel. The ’host
to connect’ may be either a domain name or a numeric IP address.
The ’originator IP address’ is the numeric IP address of the machine
from where the connection request originates, and the ’originator
port’ is the port on the host from where the connection originated.
Forwarded TCP/IP channels are independent of any sessions, and
closing a session channel does not in any way imply that forwarded
connections should be closed.
Client implementations SHOULD reject direct TCP/IP open requests for
security reasons.
8. Encoding of Terminal Modes
All ’encoded terminal modes’ (as passed in a pty request) are encoded
into a byte stream. It is intended that the coding be portable
across different environments. The stream consists of opcode-
argument pairs wherein the opcode is a byte value. Opcodes 1 to 159
have a single uint32 argument. Opcodes 160 to 255 are not yet
defined, and cause parsing to stop (they should only be used after
any other data). The stream is terminated by opcode TTY_OP_END
(0x00).
The client SHOULD put any modes it knows about in the stream, and the
server MAY ignore any modes it does not know about. This allows some
degree of machine-independence, at least between systems that use a
POSIX-like tty interface. The protocol can support other systems as
well, but the client may need to fill reasonable values for a number
of parameters so the server pty gets set to a reasonable mode (the
server leaves all unspecified mode bits in their default values, and
only some combinations make sense).
The naming of opcode values mostly follows the POSIX terminal mode
flags. The following opcode values have been defined. Note that the
values given below are in decimal format for readability, but they
are actually byte values.
opcode mnemonic description
------ -------- -----------
0 TTY_OP_END Indicates end of options.
1 VINTR Interrupt character; 255 if none. Similarly
for the other characters. Not all of these
characters are supported on all systems.
2 VQUIT The quit character (sends SIGQUIT signal on
POSIX systems).
3 VERASE Erase the character to left of the cursor.
4 VKILL Kill the current input line.
5 VEOF End-of-file character (sends EOF from the
terminal).
6 VEOL End-of-line character in addition to
carriage return and/or linefeed.
7 VEOL2 Additional end-of-line character.
8 VSTART Continues paused output (normally
control-Q).
9 VSTOP Pauses output (normally control-S).
10 VSUSP Suspends the current program.
11 VDSUSP Another suspend character.
12 VREPRINT Reprints the current input line.
13 VWERASE Erases a word left of cursor.
14 VLNEXT Enter the next character typed literally,
even if it is a special character
15 VFLUSH Character to flush output.
16 VSWTCH Switch to a different shell layer.
17 VSTATUS Prints system status line (load, command,
pid, etc).
18 VDISCARD Toggles the flushing of terminal output.
30 IGNPAR The ignore parity flag. The parameter
SHOULD be 0 if this flag is FALSE,
and 1 if it is TRUE.
31 PARMRK Mark parity and framing errors.
32 INPCK Enable checking of parity errors.
33 ISTRIP Strip 8th bit off characters.
34 INLCR Map NL into CR on input.
35 IGNCR Ignore CR on input.
36 ICRNL Map CR to NL on input.
37 IUCLC Translate uppercase characters to
lowercase.
38 IXON Enable output flow control.
39 IXANY Any char will restart after stop.
40 IXOFF Enable input flow control.
41 IMAXBEL Ring bell on input queue full.
50 ISIG Enable signals INTR, QUIT, [D]SUSP.
51 ICANON Canonicalize input lines.
52 XCASE Enable input and output of uppercase
characters by preceding their lowercase
equivalents with "\".
53 ECHO Enable echoing.
54 ECHOE Visually erase chars.
55 ECHOK Kill character discards current line.
56 ECHONL Echo NL even if ECHO is off.
57 NOFLSH Don’t flush after interrupt.
58 TOSTOP Stop background jobs from output.
59 IEXTEN Enable extensions.
60 ECHOCTL Echo control characters as ^(Char).
61 ECHOKE Visual erase for line kill.
62 PENDIN Retype pending input.
70 OPOST Enable output processing.
71 OLCUC Convert lowercase to uppercase.
72 ONLCR Map NL to CR-NL.
73 OCRNL Translate carriage return to newline
(output).
74 ONOCR Translate newline to carriage
return-newline (output).
75 ONLRET Newline performs a carriage return
(output).
90 CS7 7 bit mode.
91 CS8 8 bit mode.
92 PARENB Parity enable.
93 PARODD Odd parity, else even.
128 TTY_OP_ISPEED Specifies the input baud rate in
bits per second.
129 TTY_OP_OSPEED Specifies the output baud rate in
bits per second.
9. Summary of Message Numbers
The following is a summary of messages and their associated message
number.
SSH_MSG_GLOBAL_REQUEST 80
SSH_MSG_REQUEST_SUCCESS 81
SSH_MSG_REQUEST_FAILURE 82
SSH_MSG_CHANNEL_OPEN 90
SSH_MSG_CHANNEL_OPEN_CONFIRMATION 91
SSH_MSG_CHANNEL_OPEN_FAILURE 92
SSH_MSG_CHANNEL_WINDOW_ADJUST 93
SSH_MSG_CHANNEL_DATA 94
SSH_MSG_CHANNEL_EXTENDED_DATA 95
SSH_MSG_CHANNEL_EOF 96
SSH_MSG_CHANNEL_CLOSE 97
SSH_MSG_CHANNEL_REQUEST 98
SSH_MSG_CHANNEL_SUCCESS 99
SSH_MSG_CHANNEL_FAILURE 100
10. IANA Considerations
This document is part of a set. The IANA considerations for the SSH
protocol as defined in [SSH-ARCH], [SSH-TRANS], [SSH-USERAUTH], and
this document, are detailed in [SSH-NUMBERS].
11. Security Considerations
This protocol is assumed to run on top of a secure, authenticated
transport. User authentication and protection against network-level
attacks are assumed to be provided by the underlying protocols.
Full security considerations for this protocol are provided in
[SSH-ARCH]. Specific to this document, it is RECOMMENDED that
implementations disable all the potentially dangerous features (e.g.,
agent forwarding, X11 forwarding, and TCP/IP forwarding) if the host
key has changed without notice or explanation.
12. References
12.1. Normative References
[SSH-ARCH] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell
(SSH) Protocol Architecture", RFC 4251, January 2006.
[SSH-TRANS] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell
(SSH) Transport Layer Protocol", RFC 4253, January
2006.
[SSH-USERAUTH] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell
(SSH) Authentication Protocol", RFC 4252, January
2006.
[SSH-NUMBERS] Lehtinen, S. and C. Lonvick, Ed., "The Secure Shell
(SSH) Protocol Assigned Numbers", RFC 4250, January
2006.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing
an IANA Considerations Section in RFCs", BCP 26, RFC
2434, October 1998.
[RFC3066] Alvestrand, H., "Tags for the Identification of
Languages", BCP 47, RFC 3066, January 2001.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003.
12.2. Informative References
[RFC3330] IANA, "Special-Use IPv4 Addresses", RFC 3330,
September 2002.
[RFC3513] Hinden, R. and S. Deering, "Internet Protocol Version
6 (IPv6) Addressing Architecture", RFC 3513, April
2003.
[SCHEIFLER] Scheifler, R., "X Window System : The Complete
Reference to Xlib, X Protocol, Icccm, Xlfd, 3rd