1 This document describes the multiplexing protocol used by ssh(1)'s
2 ControlMaster connection-sharing.
4 Most messages from the client to the server contain a "request id" field.
5 This field is returned in replies as "client request id" to facilitate
6 matching of responses to requests.
10 When a multiplexing connection is made to a ssh(1) operating as a
11 ControlMaster from a ssh(1) in multiplex slave mode, the first
12 action of each is to exchange hello messages:
15 uint32 protocol version
16 string extension name [optional]
17 string extension value [optional]
20 The current version of the mux protocol is 4. A slave should refuse
21 to connect to a master that speaks an unsupported protocol version.
22 Following the version identifier are zero or more extensions
23 represented as a name/value pair. No extensions are currently
28 To open a new multiplexed session, a client may send the following
31 uint32 MUX_C_NEW_SESSION
35 bool want X11 forwarding flag
41 string environment string 0 [optional]
44 To disable the use of an escape character, "escape char" may be set
45 to 0xffffffff. "terminal type" is generally set to the value of
46 $TERM. zero or more environment strings may follow the command.
48 The client then sends its standard input, output and error file
49 descriptors (in that order) using Unix domain socket control messages.
51 The contents of "reserved" are currently ignored.
53 If successful, the server will reply with MUX_S_SESSION_OPENED
55 uint32 MUX_S_SESSION_OPENED
56 uint32 client request id
59 Otherwise it will reply with an error: MUX_S_PERMISSION_DENIED or
62 Once the server has received the fds, it will respond with MUX_S_OK
63 indicating that the session is up. The client now waits for the
64 session to end. When it does, the server will send an exit status
67 uint32 MUX_S_EXIT_MESSAGE
71 The client should exit with this value to mimic the behaviour of a
72 non-multiplexed ssh(1) connection. Two additional cases that the
73 client must cope with are it receiving a signal itself and the
74 server disconnecting without sending an exit message.
76 A master may also send a MUX_S_TTY_ALLOC_FAIL before MUX_S_EXIT_MESSAGE
77 if remote TTY allocation was unsuccessful. The client may use this to
78 return its local tty to "cooked" mode.
80 uint32 MUX_S_TTY_ALLOC_FAIL
85 The client may request a health check/PID report from a server:
87 uint32 MUX_C_ALIVE_CHECK
90 The server replies with:
93 uint32 client request id
96 4. Remotely terminating a master
98 A client may request that a master terminate immediately:
100 uint32 MUX_C_TERMINATE
103 The server will reply with one of MUX_S_OK or MUX_S_PERMISSION_DENIED.
105 5. Requesting establishment of port forwards
107 A client may request the master to establish a port forward:
109 uint32 MUX_C_OPEN_FWD
111 uint32 forwarding type
117 forwarding type may be MUX_FWD_LOCAL, MUX_FWD_REMOTE, MUX_FWD_DYNAMIC.
119 A server may reply with a MUX_S_OK, a MUX_S_REMOTE_PORT, a
120 MUX_S_PERMISSION_DENIED or a MUX_S_FAILURE.
122 For dynamically allocated listen port the server replies with
124 uint32 MUX_S_REMOTE_PORT
125 uint32 client request id
126 uint32 allocated remote listen port
128 6. Requesting closure of port forwards
130 Note: currently unimplemented (server will always reply with MUX_S_FAILURE).
132 A client may request the master to close a port forward:
134 uint32 MUX_C_CLOSE_FWD
141 A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
144 7. Requesting stdio forwarding
146 A client may request the master to establish a stdio forwarding:
148 uint32 MUX_C_NEW_STDIO_FWD
154 The client then sends its standard input and output file descriptors
155 (in that order) using Unix domain socket control messages.
157 The contents of "reserved" are currently ignored.
159 A server may reply with a MUX_S_SESSION_OPENED, a MUX_S_PERMISSION_DENIED
162 8. Requesting shutdown of mux listener
164 A client may request the master to stop accepting new multiplexing requests
165 and remove its listener socket.
167 uint32 MUX_C_STOP_LISTENING
170 A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
175 The MUX_S_OK message is empty:
178 uint32 client request id
180 The MUX_S_PERMISSION_DENIED and MUX_S_FAILURE include a reason:
182 uint32 MUX_S_PERMISSION_DENIED
183 uint32 client request id
187 uint32 client request id
192 #define MUX_MSG_HELLO 0x00000001
193 #define MUX_C_NEW_SESSION 0x10000002
194 #define MUX_C_ALIVE_CHECK 0x10000004
195 #define MUX_C_TERMINATE 0x10000005
196 #define MUX_C_OPEN_FWD 0x10000006
197 #define MUX_C_CLOSE_FWD 0x10000007
198 #define MUX_C_NEW_STDIO_FWD 0x10000008
199 #define MUX_C_STOP_LISTENING 0x10000009
200 #define MUX_S_OK 0x80000001
201 #define MUX_S_PERMISSION_DENIED 0x80000002
202 #define MUX_S_FAILURE 0x80000003
203 #define MUX_S_EXIT_MESSAGE 0x80000004
204 #define MUX_S_ALIVE 0x80000005
205 #define MUX_S_SESSION_OPENED 0x80000006
206 #define MUX_S_REMOTE_PORT 0x80000007
207 #define MUX_S_TTY_ALLOC_FAIL 0x80000008
209 #define MUX_FWD_LOCAL 1
210 #define MUX_FWD_REMOTE 2
211 #define MUX_FWD_DYNAMIC 3
214 XXX extended status (e.g. report open channels / forwards)
216 XXX watch in/out traffic (pre/post crypto)
217 XXX inject packet (what about replies)
218 XXX server->client error/warning notifications
219 XXX send signals via mux
221 $OpenBSD: PROTOCOL.mux,v 1.7 2011/05/08 12:52:01 djm Exp $