summaryrefslogtreecommitdiff
path: root/PROTOCOL.mux
diff options
context:
space:
mode:
authordjm@openbsd.org <djm@openbsd.org>2018-09-26 07:30:05 +0000
committerDamien Miller <djm@mindrot.org>2018-09-26 17:35:22 +1000
commit92b61a38ee9b765f5049f03cd1143e13f3878905 (patch)
tree9312e88f29e2cc42b40602559b29d3e26208da97 /PROTOCOL.mux
parent9d883a1ce4f89b175fd77405ff32674620703fb2 (diff)
upstream: Document mux proxy mode; added by Markus in openssh-7.4
Also add a little bit of information about the overall packet format OpenBSD-Commit-ID: bdb6f6ea8580ef96792e270cae7857786ad84a95
Diffstat (limited to 'PROTOCOL.mux')
-rw-r--r--PROTOCOL.mux144
1 files changed, 107 insertions, 37 deletions
diff --git a/PROTOCOL.mux b/PROTOCOL.mux
index f042961f1..77a0780a5 100644
--- a/PROTOCOL.mux
+++ b/PROTOCOL.mux
@@ -1,15 +1,52 @@
1This document describes the multiplexing protocol used by ssh(1)'s 1This document describes the multiplexing protocol used by ssh(1)'s
2ControlMaster connection-sharing. 2ControlMaster connection-sharing.
3 3
4Most messages from the client to the server contain a "request id" field. 4Multiplexing starts with a ssh(1) configured to act as a multiplexing
5This field is returned in replies as "client request id" to facilitate 5master. This will cause ssh(1) to listen on a Unix domain socket for
6matching of responses to requests. 6requests from clients. Clients communicate over this socket using a
7simple packetised protocol, where each message is proceeded with
8a length and message type in SSH uint32 wire format:
9
10 uint32 packet length
11 uint32 packet type
12 ... packet body
13
14Most messages from the client to the server contain a "request id"
15field. This field is returned in replies as "client request id" to
16facilitate matching of responses to requests.
17
18Many muliplexing (mux) client requests yield immediate responses from
19the mux process; requesting a forwarding, performing an alive check or
20requesting the master terminate itself fall in to this category.
21
22The most common use of multiplexing however is to maintain multiple
23concurrent sessions. These are supported via two separate modes:
24
25"Passenger" clients start by requesting a new session with a
26MUX_C_NEW_SESSION message and passing stdio file descriptors over the
27Unix domain control socket. The passenger client then waits until it is
28signaled or the mux server closes the session. This mode is so named as
29the client waits around while the mux server does all the driving.
30
31Stdio forwarding (requested using MUX_C_NEW_STDIO_FWD) is another
32example of passenger mode; the client passes the stdio file descriptors
33and passively waits for something to happen.
34
35"Proxy" clients, requested using MUX_C_PROXY, work quite differently. In
36this mode, the mux client/server connection socket will stop speaking
37the multiplexing protocol and start proxying SSH connection protocol
38messages between the client and server. The client therefore must
39speak a significant subset of the SSH protocol, but in return is able
40to access basically the full suite of connection protocol features.
41Moreover, as no file descriptor passing is required, the connection
42supporting a proxy client may iteself be forwarded or relayed to another
43host if necessary.
7 44
81. Connection setup 451. Connection setup
9 46
10When a multiplexing connection is made to a ssh(1) operating as a 47When a multiplexing connection is made to a ssh(1) operating as a
11ControlMaster from a ssh(1) in multiplex slave mode, the first 48ControlMaster from a client ssh(1), the first action of each is send
12action of each is to exchange hello messages: 49a hello messages to its peer:
13 50
14 uint32 MUX_MSG_HELLO 51 uint32 MUX_MSG_HELLO
15 uint32 protocol version 52 uint32 protocol version
@@ -17,16 +54,16 @@ action of each is to exchange hello messages:
17 string extension value [optional] 54 string extension value [optional]
18 ... 55 ...
19 56
20The current version of the mux protocol is 4. A slave should refuse 57The current version of the mux protocol is 4. A client should refuse
21to connect to a master that speaks an unsupported protocol version. 58to connect to a master that speaks an unsupported protocol version.
22Following the version identifier are zero or more extensions
23represented as a name/value pair. No extensions are currently
24defined.
25 59
262. Opening sessions 60Following the version identifier are zero or more extensions represented
61as a name/value pair. No extensions are currently defined.
27 62
28To open a new multiplexed session, a client may send the following 632. Opening a passenger mode session
29request: 64
65To open a new multiplexed session in passenger mode, a client sends the
66following request:
30 67
31 uint32 MUX_C_NEW_SESSION 68 uint32 MUX_C_NEW_SESSION
32 uint32 request id 69 uint32 request id
@@ -80,7 +117,25 @@ return its local tty to "cooked" mode.
80 uint32 MUX_S_TTY_ALLOC_FAIL 117 uint32 MUX_S_TTY_ALLOC_FAIL
81 uint32 session id 118 uint32 session id
82 119
833. Health checks 1203. Requesting passenger-mode stdio forwarding
121
122A client may request the master to establish a stdio forwarding:
123
124 uint32 MUX_C_NEW_STDIO_FWD
125 uint32 request id
126 string reserved
127 string connect host
128 string connect port
129
130The client then sends its standard input and output file descriptors
131(in that order) using Unix domain socket control messages.
132
133The contents of "reserved" are currently ignored.
134
135A server may reply with a MUX_S_SESSION_OPENED, a MUX_S_PERMISSION_DENIED
136or a MUX_S_FAILURE.
137
1384. Health checks
84 139
85The client may request a health check/PID report from a server: 140The client may request a health check/PID report from a server:
86 141
@@ -93,7 +148,7 @@ The server replies with:
93 uint32 client request id 148 uint32 client request id
94 uint32 server pid 149 uint32 server pid
95 150
964. Remotely terminating a master 1515. Remotely terminating a master
97 152
98A client may request that a master terminate immediately: 153A client may request that a master terminate immediately:
99 154
@@ -102,7 +157,7 @@ A client may request that a master terminate immediately:
102 157
103The server will reply with one of MUX_S_OK or MUX_S_PERMISSION_DENIED. 158The server will reply with one of MUX_S_OK or MUX_S_PERMISSION_DENIED.
104 159
1055. Requesting establishment of port forwards 1606. Requesting establishment of port forwards
106 161
107A client may request the master to establish a port forward: 162A client may request the master to establish a port forward:
108 163
@@ -131,7 +186,7 @@ For dynamically allocated listen port the server replies with
131 uint32 client request id 186 uint32 client request id
132 uint32 allocated remote listen port 187 uint32 allocated remote listen port
133 188
1346. Requesting closure of port forwards 1897. Requesting closure of port forwards
135 190
136Note: currently unimplemented (server will always reply with MUX_S_FAILURE). 191Note: currently unimplemented (server will always reply with MUX_S_FAILURE).
137 192
@@ -148,36 +203,45 @@ A client may request the master to close a port forward:
148A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a 203A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
149MUX_S_FAILURE. 204MUX_S_FAILURE.
150 205
1517. Requesting stdio forwarding 2068. Requesting shutdown of mux listener
152 207
153A client may request the master to establish a stdio forwarding: 208A client may request the master to stop accepting new multiplexing requests
209and remove its listener socket.
154 210
155 uint32 MUX_C_NEW_STDIO_FWD 211 uint32 MUX_C_STOP_LISTENING
156 uint32 request id 212 uint32 request id
157 string reserved
158 string connect host
159 string connect port
160 213
161The client then sends its standard input and output file descriptors 214A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
162(in that order) using Unix domain socket control messages. 215MUX_S_FAILURE.
163 216
164The contents of "reserved" are currently ignored. 2179. Requesting proxy mode
165 218
166A server may reply with a MUX_S_SESSION_OPENED, a MUX_S_PERMISSION_DENIED 219A client may request that the the control connection be placed in proxy
167or a MUX_S_FAILURE. 220mode:
168 221
1698. Requesting shutdown of mux listener 222 uint32 MUX_C_PROXY
223 uint32 request id
170 224
171A client may request the master to stop accepting new multiplexing requests 225When a mux master receives this message, it will reply with a
172and remove its listener socket. 226confirmation:
173 227
174 uint32 MUX_C_STOP_LISTENING 228 uint32 MUX_S_PROXY
175 uint32 request id 229 uint32 request id
176 230
177A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a 231And go into proxy mode. All subsequent data over the connection will
178MUX_S_FAILURE. 232be formatted as unencrypted, unpadded, SSH transport messages:
233
234 uint32 packet length
235 byte 0 (padding length)
236 byte packet type
237 byte[packet length - 2] ...
179 238
1809. Status messages 239The mux master will accept most connection messages and global requests,
240and will translate channel identifiers to ensure that the proxy client has
241globally unique channel numbers (i.e. a proxy client need not worry about
242collisions with other clients).
243
24410. Status messages
181 245
182The MUX_S_OK message is empty: 246The MUX_S_OK message is empty:
183 247
@@ -194,7 +258,7 @@ The MUX_S_PERMISSION_DENIED and MUX_S_FAILURE include a reason:
194 uint32 client request id 258 uint32 client request id
195 string reason 259 string reason
196 260
19710. Protocol numbers 26111. Protocol numbers
198 262
199#define MUX_MSG_HELLO 0x00000001 263#define MUX_MSG_HELLO 0x00000001
200#define MUX_C_NEW_SESSION 0x10000002 264#define MUX_C_NEW_SESSION 0x10000002
@@ -224,5 +288,11 @@ XXX watch in/out traffic (pre/post crypto)
224XXX inject packet (what about replies) 288XXX inject packet (what about replies)
225XXX server->client error/warning notifications 289XXX server->client error/warning notifications
226XXX send signals via mux 290XXX send signals via mux
227 291XXX ^Z support in passengers
228$OpenBSD: PROTOCOL.mux,v 1.10 2015/07/17 03:04:27 djm Exp $ 292XXX extensions for multi-agent
293XXX extensions for multi-X11
294XXX session inspection via master
295XXX signals via mux request
296XXX list active connections via mux
297
298$OpenBSD: PROTOCOL.mux,v 1.11 2018/09/26 07:30:05 djm Exp $