1 This document describes the multiplexing protocol used by ssh(1)'s
2 ControlMaster connection-sharing.
4 Multiplexing starts with a ssh(1) configured to act as a multiplexing
5 master. This will cause ssh(1) to listen on a Unix domain socket for
6 requests from clients. Clients communicate over this socket using a
7 simple packetised protocol, where each message is proceeded with
8 a length and message type in SSH uint32 wire format:
14 Most messages from the client to the server contain a "request id"
15 field. This field is returned in replies as "client request id" to
16 facilitate matching of responses to requests.
18 Many muliplexing (mux) client requests yield immediate responses from
19 the mux process; requesting a forwarding, performing an alive check or
20 requesting the master terminate itself fall in to this category.
22 The most common use of multiplexing however is to maintain multiple
23 concurrent sessions. These are supported via two separate modes:
25 "Passenger" clients start by requesting a new session with a
26 MUX_C_NEW_SESSION message and passing stdio file descriptors over the
27 Unix domain control socket. The passenger client then waits until it is
28 signaled or the mux server closes the session. This mode is so named as
29 the client waits around while the mux server does all the driving.
31 Stdio forwarding (requested using MUX_C_NEW_STDIO_FWD) is another
32 example of passenger mode; the client passes the stdio file descriptors
33 and passively waits for something to happen.
35 "Proxy" clients, requested using MUX_C_PROXY, work quite differently. In
36 this mode, the mux client/server connection socket will stop speaking
37 the multiplexing protocol and start proxying SSH connection protocol
38 messages between the client and server. The client therefore must
39 speak a significant subset of the SSH protocol, but in return is able
40 to access basically the full suite of connection protocol features.
41 Moreover, as no file descriptor passing is required, the connection
42 supporting a proxy client may iteself be forwarded or relayed to another
47 When a multiplexing connection is made to a ssh(1) operating as a
48 ControlMaster from a client ssh(1), the first action of each is send
49 a hello messages to its peer:
52 uint32 protocol version
53 string extension name [optional]
54 string extension value [optional]
57 The current version of the mux protocol is 4. A client should refuse
58 to connect to a master that speaks an unsupported protocol version.
60 Following the version identifier are zero or more extensions represented
61 as a name/value pair. No extensions are currently defined.
63 2. Opening a passenger mode session
65 To open a new multiplexed session in passenger mode, a client sends the
68 uint32 MUX_C_NEW_SESSION
72 bool want X11 forwarding flag
78 string environment string 0 [optional]
81 To disable the use of an escape character, "escape char" may be set
82 to 0xffffffff. "terminal type" is generally set to the value of
83 $TERM. zero or more environment strings may follow the command.
85 The client then sends its standard input, output and error file
86 descriptors (in that order) using Unix domain socket control messages.
88 The contents of "reserved" are currently ignored.
90 If successful, the server will reply with MUX_S_SESSION_OPENED
92 uint32 MUX_S_SESSION_OPENED
93 uint32 client request id
96 Otherwise it will reply with an error: MUX_S_PERMISSION_DENIED or
99 Once the server has received the fds, it will respond with MUX_S_OK
100 indicating that the session is up. The client now waits for the
101 session to end. When it does, the server will send an exit status
104 uint32 MUX_S_EXIT_MESSAGE
108 The client should exit with this value to mimic the behaviour of a
109 non-multiplexed ssh(1) connection. Two additional cases that the
110 client must cope with are it receiving a signal itself and the
111 server disconnecting without sending an exit message.
113 A master may also send a MUX_S_TTY_ALLOC_FAIL before MUX_S_EXIT_MESSAGE
114 if remote TTY allocation was unsuccessful. The client may use this to
115 return its local tty to "cooked" mode.
117 uint32 MUX_S_TTY_ALLOC_FAIL
120 3. Requesting passenger-mode stdio forwarding
122 A client may request the master to establish a stdio forwarding:
124 uint32 MUX_C_NEW_STDIO_FWD
130 The client then sends its standard input and output file descriptors
131 (in that order) using Unix domain socket control messages.
133 The contents of "reserved" are currently ignored.
135 A server may reply with a MUX_S_SESSION_OPENED, a MUX_S_PERMISSION_DENIED
140 The client may request a health check/PID report from a server:
142 uint32 MUX_C_ALIVE_CHECK
145 The server replies with:
148 uint32 client request id
151 5. Remotely terminating a master
153 A client may request that a master terminate immediately:
155 uint32 MUX_C_TERMINATE
158 The server will reply with one of MUX_S_OK or MUX_S_PERMISSION_DENIED.
160 6. Requesting establishment of port forwards
162 A client may request the master to establish a port forward:
164 uint32 MUX_C_OPEN_FWD
166 uint32 forwarding type
172 forwarding type may be MUX_FWD_LOCAL, MUX_FWD_REMOTE, MUX_FWD_DYNAMIC.
174 If listen port is (unsigned int) -2, then the listen host is treated as
175 a unix socket path name.
177 If connect port is (unsigned int) -2, then the connect host is treated
178 as a unix socket path name.
180 A server may reply with a MUX_S_OK, a MUX_S_REMOTE_PORT, a
181 MUX_S_PERMISSION_DENIED or a MUX_S_FAILURE.
183 For dynamically allocated listen port the server replies with
185 uint32 MUX_S_REMOTE_PORT
186 uint32 client request id
187 uint32 allocated remote listen port
189 7. Requesting closure of port forwards
191 Note: currently unimplemented (server will always reply with MUX_S_FAILURE).
193 A client may request the master to close a port forward:
195 uint32 MUX_C_CLOSE_FWD
197 uint32 forwarding type
203 A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
206 8. Requesting shutdown of mux listener
208 A client may request the master to stop accepting new multiplexing requests
209 and remove its listener socket.
211 uint32 MUX_C_STOP_LISTENING
214 A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
217 9. Requesting proxy mode
219 A client may request that the the control connection be placed in proxy
225 When a mux master receives this message, it will reply with a
231 And go into proxy mode. All subsequent data over the connection will
232 be formatted as unencrypted, unpadded, SSH transport messages:
235 byte 0 (padding length)
237 byte[packet length - 2] ...
239 The mux master will accept most connection messages and global requests,
240 and will translate channel identifiers to ensure that the proxy client has
241 globally unique channel numbers (i.e. a proxy client need not worry about
242 collisions with other clients).
246 The MUX_S_OK message is empty:
249 uint32 client request id
251 The MUX_S_PERMISSION_DENIED and MUX_S_FAILURE include a reason:
253 uint32 MUX_S_PERMISSION_DENIED
254 uint32 client request id
258 uint32 client request id
263 #define MUX_MSG_HELLO 0x00000001
264 #define MUX_C_NEW_SESSION 0x10000002
265 #define MUX_C_ALIVE_CHECK 0x10000004
266 #define MUX_C_TERMINATE 0x10000005
267 #define MUX_C_OPEN_FWD 0x10000006
268 #define MUX_C_CLOSE_FWD 0x10000007
269 #define MUX_C_NEW_STDIO_FWD 0x10000008
270 #define MUX_C_STOP_LISTENING 0x10000009
271 #define MUX_S_OK 0x80000001
272 #define MUX_S_PERMISSION_DENIED 0x80000002
273 #define MUX_S_FAILURE 0x80000003
274 #define MUX_S_EXIT_MESSAGE 0x80000004
275 #define MUX_S_ALIVE 0x80000005
276 #define MUX_S_SESSION_OPENED 0x80000006
277 #define MUX_S_REMOTE_PORT 0x80000007
278 #define MUX_S_TTY_ALLOC_FAIL 0x80000008
280 #define MUX_FWD_LOCAL 1
281 #define MUX_FWD_REMOTE 2
282 #define MUX_FWD_DYNAMIC 3
285 XXX extended status (e.g. report open channels / forwards)
287 XXX watch in/out traffic (pre/post crypto)
288 XXX inject packet (what about replies)
289 XXX server->client error/warning notifications
290 XXX send signals via mux
291 XXX ^Z support in passengers
292 XXX extensions for multi-agent
293 XXX extensions for multi-X11
294 XXX session inspection via master
295 XXX signals via mux request
296 XXX list active connections via mux
298 $OpenBSD: PROTOCOL.mux,v 1.11 2018/09/26 07:30:05 djm Exp $