blob: b5832561c0e80464af811aea5bc9fb50c797807a [file] [log] [blame]
Damien Millerb401f922010-02-10 10:17:49 +11001This document describes the multiplexing protocol used by ssh(1)'s
2ControlMaster connection-sharing.
3
4Most messages from the client to the server contain a "request id" field.
5This field is returned in replies as "client request id" to facilitate
6matching of responses to requests.
7
81. Connection setup
9
10When a multiplexing connection is made to a ssh(1) operating as a
11ControlMaster from a ssh(1) in multiplex slave mode, the first
12action of each is to exchange hello messages:
13
14 uint32 MUX_MSG_HELLO
15 uint32 protocol version
16 string extension name [optional]
17 string extension value [optional]
18 ...
19
20The current version of the mux protocol is 4. A slave should refuse
21to 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
262. Opening sessions
27
28To open a new multiplexed session, a client may send the following
29request:
30
Damien Miller42747df2011-01-14 12:01:50 +110031 uint32 MUX_C_NEW_SESSION
Damien Millerb401f922010-02-10 10:17:49 +110032 uint32 request id
33 string reserved
34 bool want tty flag
35 bool want X11 forwarding flag
36 bool want agent flag
37 bool subsystem flag
38 uint32 escape char
39 string terminal type
40 string command
41 string environment string 0 [optional]
42 ...
43
44To disable the use of an escape character, "escape char" may be set
45to 0xffffffff. "terminal type" is generally set to the value of
46$TERM. zero or more environment strings may follow the command.
47
48The client then sends its standard input, output and error file
49descriptors (in that order) using Unix domain socket control messages.
50
51The contents of "reserved" are currently ignored.
52
53If successful, the server will reply with MUX_S_SESSION_OPENED
54
55 uint32 MUX_S_SESSION_OPENED
56 uint32 client request id
57 uint32 session id
58
59Otherwise it will reply with an error: MUX_S_PERMISSION_DENIED or
60MUX_S_FAILURE.
61
62Once the server has received the fds, it will respond with MUX_S_OK
63indicating that the session is up. The client now waits for the
64session to end. When it does, the server will send an exit status
65message:
66
67 uint32 MUX_S_EXIT_MESSAGE
68 uint32 session id
69 uint32 exit value
70
71The client should exit with this value to mimic the behaviour of a
72non-multiplexed ssh(1) connection. Two additional cases that the
73client must cope with are it receiving a signal itself and the
74server disconnecting without sending an exit message.
75
Damien Miller555f3b82011-05-15 08:48:05 +100076A master may also send a MUX_S_TTY_ALLOC_FAIL before MUX_S_EXIT_MESSAGE
77if remote TTY allocation was unsuccessful. The client may use this to
78return its local tty to "cooked" mode.
79
80 uint32 MUX_S_TTY_ALLOC_FAIL
81 uint32 session id
82
Damien Millerb401f922010-02-10 10:17:49 +1100833. Health checks
84
85The client may request a health check/PID report from a server:
86
87 uint32 MUX_C_ALIVE_CHECK
88 uint32 request id
89
90The server replies with:
91
92 uint32 MUX_S_ALIVE
93 uint32 client request id
94 uint32 server pid
95
964. Remotely terminating a master
97
98A client may request that a master terminate immediately:
99
100 uint32 MUX_C_TERMINATE
101 uint32 request id
102
103The server will reply with one of MUX_S_OK or MUX_S_PERMISSION_DENIED.
104
1055. Requesting establishment of port forwards
106
107A client may request the master to establish a port forward:
108
Damien Miller42747df2011-01-14 12:01:50 +1100109 uint32 MUX_C_OPEN_FWD
Damien Millerb401f922010-02-10 10:17:49 +1100110 uint32 request id
111 uint32 forwarding type
112 string listen host
Damien Miller7f121572012-06-20 21:51:29 +1000113 uint32 listen port
Damien Millerb401f922010-02-10 10:17:49 +1100114 string connect host
Damien Miller7f121572012-06-20 21:51:29 +1000115 uint32 connect port
Damien Millerb401f922010-02-10 10:17:49 +1100116
117forwarding type may be MUX_FWD_LOCAL, MUX_FWD_REMOTE, MUX_FWD_DYNAMIC.
118
Damien Miller388f6fc2010-05-21 14:57:35 +1000119A server may reply with a MUX_S_OK, a MUX_S_REMOTE_PORT, a
120MUX_S_PERMISSION_DENIED or a MUX_S_FAILURE.
121
122For dynamically allocated listen port the server replies with
123
124 uint32 MUX_S_REMOTE_PORT
125 uint32 client request id
126 uint32 allocated remote listen port
Damien Millerb401f922010-02-10 10:17:49 +1100127
Damien Miller42747df2011-01-14 12:01:50 +11001286. Requesting closure of port forwards
129
130Note: currently unimplemented (server will always reply with MUX_S_FAILURE).
Damien Millerb401f922010-02-10 10:17:49 +1100131
Damien Millerb407dd82011-02-04 11:46:39 +1100132A client may request the master to close a port forward:
Damien Millerb401f922010-02-10 10:17:49 +1100133
Damien Miller42747df2011-01-14 12:01:50 +1100134 uint32 MUX_C_CLOSE_FWD
Damien Millerb401f922010-02-10 10:17:49 +1100135 uint32 request id
Damien Miller4cb855b2011-09-22 21:37:38 +1000136 uint32 forwarding type
Damien Millerb401f922010-02-10 10:17:49 +1100137 string listen host
Damien Miller7f121572012-06-20 21:51:29 +1000138 uint32 listen port
Damien Millerb401f922010-02-10 10:17:49 +1100139 string connect host
Damien Miller7f121572012-06-20 21:51:29 +1000140 uint32 connect port
Damien Millerb401f922010-02-10 10:17:49 +1100141
Damien Millerb401f922010-02-10 10:17:49 +1100142A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
143MUX_S_FAILURE.
144
Damien Miller42747df2011-01-14 12:01:50 +11001457. Requesting stdio forwarding
Damien Millerb401f922010-02-10 10:17:49 +1100146
147A client may request the master to establish a stdio forwarding:
148
149 uint32 MUX_C_NEW_STDIO_FWD
150 uint32 request id
151 string reserved
152 string connect host
153 string connect port
154
155The client then sends its standard input and output file descriptors
156(in that order) using Unix domain socket control messages.
157
158The contents of "reserved" are currently ignored.
159
Damien Miller6c3eec72011-05-05 14:16:22 +1000160A server may reply with a MUX_S_SESSION_OPENED, a MUX_S_PERMISSION_DENIED
Damien Millerb401f922010-02-10 10:17:49 +1100161or a MUX_S_FAILURE.
162
Damien Miller6c3eec72011-05-05 14:16:22 +10001638. Requesting shutdown of mux listener
164
165A client may request the master to stop accepting new multiplexing requests
166and remove its listener socket.
167
168 uint32 MUX_C_STOP_LISTENING
169 uint32 request id
170
171A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
172MUX_S_FAILURE.
173
1749. Status messages
Damien Millerb401f922010-02-10 10:17:49 +1100175
176The MUX_S_OK message is empty:
177
178 uint32 MUX_S_OK
179 uint32 client request id
180
181The MUX_S_PERMISSION_DENIED and MUX_S_FAILURE include a reason:
182
183 uint32 MUX_S_PERMISSION_DENIED
184 uint32 client request id
185 string reason
186
187 uint32 MUX_S_FAILURE
188 uint32 client request id
189 string reason
190
Damien Millerc067f622011-05-15 08:46:54 +100019110. Protocol numbers
Damien Millerb401f922010-02-10 10:17:49 +1100192
193#define MUX_MSG_HELLO 0x00000001
194#define MUX_C_NEW_SESSION 0x10000002
195#define MUX_C_ALIVE_CHECK 0x10000004
196#define MUX_C_TERMINATE 0x10000005
Damien Miller42747df2011-01-14 12:01:50 +1100197#define MUX_C_OPEN_FWD 0x10000006
198#define MUX_C_CLOSE_FWD 0x10000007
199#define MUX_C_NEW_STDIO_FWD 0x10000008
Damien Miller6c3eec72011-05-05 14:16:22 +1000200#define MUX_C_STOP_LISTENING 0x10000009
Damien Millerb401f922010-02-10 10:17:49 +1100201#define MUX_S_OK 0x80000001
202#define MUX_S_PERMISSION_DENIED 0x80000002
203#define MUX_S_FAILURE 0x80000003
204#define MUX_S_EXIT_MESSAGE 0x80000004
205#define MUX_S_ALIVE 0x80000005
206#define MUX_S_SESSION_OPENED 0x80000006
Damien Miller388f6fc2010-05-21 14:57:35 +1000207#define MUX_S_REMOTE_PORT 0x80000007
Damien Miller555f3b82011-05-15 08:48:05 +1000208#define MUX_S_TTY_ALLOC_FAIL 0x80000008
Damien Millerb401f922010-02-10 10:17:49 +1100209
210#define MUX_FWD_LOCAL 1
211#define MUX_FWD_REMOTE 2
212#define MUX_FWD_DYNAMIC 3
213
214XXX TODO
215XXX extended status (e.g. report open channels / forwards)
Damien Millerb401f922010-02-10 10:17:49 +1100216XXX lock (maybe)
217XXX watch in/out traffic (pre/post crypto)
218XXX inject packet (what about replies)
219XXX server->client error/warning notifications
Damien Millerb401f922010-02-10 10:17:49 +1100220XXX send signals via mux
221
Damien Miller7f121572012-06-20 21:51:29 +1000222$OpenBSD: PROTOCOL.mux,v 1.9 2012/06/01 00:49:35 djm Exp $