diff options
author | djm@openbsd.org <djm@openbsd.org> | 2018-09-26 07:30:05 +0000 |
---|---|---|
committer | Damien Miller <djm@mindrot.org> | 2018-09-26 17:35:22 +1000 |
commit | 92b61a38ee9b765f5049f03cd1143e13f3878905 (patch) | |
tree | 9312e88f29e2cc42b40602559b29d3e26208da97 /PROTOCOL.mux | |
parent | 9d883a1ce4f89b175fd77405ff32674620703fb2 (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.mux | 144 |
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 @@ | |||
1 | This document describes the multiplexing protocol used by ssh(1)'s | 1 | This document describes the multiplexing protocol used by ssh(1)'s |
2 | ControlMaster connection-sharing. | 2 | ControlMaster connection-sharing. |
3 | 3 | ||
4 | Most messages from the client to the server contain a "request id" field. | 4 | Multiplexing starts with a ssh(1) configured to act as a multiplexing |
5 | This field is returned in replies as "client request id" to facilitate | 5 | master. This will cause ssh(1) to listen on a Unix domain socket for |
6 | matching of responses to requests. | 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: | ||
9 | |||
10 | uint32 packet length | ||
11 | uint32 packet type | ||
12 | ... packet body | ||
13 | |||
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. | ||
17 | |||
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. | ||
21 | |||
22 | The most common use of multiplexing however is to maintain multiple | ||
23 | concurrent sessions. These are supported via two separate modes: | ||
24 | |||
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. | ||
30 | |||
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. | ||
34 | |||
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 | ||
43 | host if necessary. | ||
7 | 44 | ||
8 | 1. Connection setup | 45 | 1. Connection setup |
9 | 46 | ||
10 | When a multiplexing connection is made to a ssh(1) operating as a | 47 | 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 | 48 | ControlMaster from a client ssh(1), the first action of each is send |
12 | action of each is to exchange hello messages: | 49 | a 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 | ||
20 | The current version of the mux protocol is 4. A slave should refuse | 57 | The current version of the mux protocol is 4. A client should refuse |
21 | to connect to a master that speaks an unsupported protocol version. | 58 | 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 | ||
24 | defined. | ||
25 | 59 | ||
26 | 2. Opening sessions | 60 | Following the version identifier are zero or more extensions represented |
61 | as a name/value pair. No extensions are currently defined. | ||
27 | 62 | ||
28 | To open a new multiplexed session, a client may send the following | 63 | 2. Opening a passenger mode session |
29 | request: | 64 | |
65 | To open a new multiplexed session in passenger mode, a client sends the | ||
66 | following 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 | ||
83 | 3. Health checks | 120 | 3. Requesting passenger-mode stdio forwarding |
121 | |||
122 | A 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 | |||
130 | The client then sends its standard input and output file descriptors | ||
131 | (in that order) using Unix domain socket control messages. | ||
132 | |||
133 | The contents of "reserved" are currently ignored. | ||
134 | |||
135 | A server may reply with a MUX_S_SESSION_OPENED, a MUX_S_PERMISSION_DENIED | ||
136 | or a MUX_S_FAILURE. | ||
137 | |||
138 | 4. Health checks | ||
84 | 139 | ||
85 | The client may request a health check/PID report from a server: | 140 | The 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 | ||
96 | 4. Remotely terminating a master | 151 | 5. Remotely terminating a master |
97 | 152 | ||
98 | A client may request that a master terminate immediately: | 153 | A 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 | ||
103 | The server will reply with one of MUX_S_OK or MUX_S_PERMISSION_DENIED. | 158 | The server will reply with one of MUX_S_OK or MUX_S_PERMISSION_DENIED. |
104 | 159 | ||
105 | 5. Requesting establishment of port forwards | 160 | 6. Requesting establishment of port forwards |
106 | 161 | ||
107 | A client may request the master to establish a port forward: | 162 | A 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 | ||
134 | 6. Requesting closure of port forwards | 189 | 7. Requesting closure of port forwards |
135 | 190 | ||
136 | Note: currently unimplemented (server will always reply with MUX_S_FAILURE). | 191 | Note: 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: | |||
148 | A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a | 203 | A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a |
149 | MUX_S_FAILURE. | 204 | MUX_S_FAILURE. |
150 | 205 | ||
151 | 7. Requesting stdio forwarding | 206 | 8. Requesting shutdown of mux listener |
152 | 207 | ||
153 | A client may request the master to establish a stdio forwarding: | 208 | A client may request the master to stop accepting new multiplexing requests |
209 | and 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 | ||
161 | The client then sends its standard input and output file descriptors | 214 | A 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. | 215 | MUX_S_FAILURE. |
163 | 216 | ||
164 | The contents of "reserved" are currently ignored. | 217 | 9. Requesting proxy mode |
165 | 218 | ||
166 | A server may reply with a MUX_S_SESSION_OPENED, a MUX_S_PERMISSION_DENIED | 219 | A client may request that the the control connection be placed in proxy |
167 | or a MUX_S_FAILURE. | 220 | mode: |
168 | 221 | ||
169 | 8. Requesting shutdown of mux listener | 222 | uint32 MUX_C_PROXY |
223 | uint32 request id | ||
170 | 224 | ||
171 | A client may request the master to stop accepting new multiplexing requests | 225 | When a mux master receives this message, it will reply with a |
172 | and remove its listener socket. | 226 | confirmation: |
173 | 227 | ||
174 | uint32 MUX_C_STOP_LISTENING | 228 | uint32 MUX_S_PROXY |
175 | uint32 request id | 229 | uint32 request id |
176 | 230 | ||
177 | A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a | 231 | And go into proxy mode. All subsequent data over the connection will |
178 | MUX_S_FAILURE. | 232 | be 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 | ||
180 | 9. Status messages | 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). | ||
243 | |||
244 | 10. Status messages | ||
181 | 245 | ||
182 | The MUX_S_OK message is empty: | 246 | The 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 | ||
197 | 10. Protocol numbers | 261 | 11. 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) | |||
224 | XXX inject packet (what about replies) | 288 | XXX inject packet (what about replies) |
225 | XXX server->client error/warning notifications | 289 | XXX server->client error/warning notifications |
226 | XXX send signals via mux | 290 | XXX send signals via mux |
227 | 291 | XXX ^Z support in passengers | |
228 | $OpenBSD: PROTOCOL.mux,v 1.10 2015/07/17 03:04:27 djm Exp $ | 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 | ||
297 | |||
298 | $OpenBSD: PROTOCOL.mux,v 1.11 2018/09/26 07:30:05 djm Exp $ | ||