xref: /openssh-portable/PROTOCOL.mux (revision 356b61f3)
1This 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
31	uint32	MUX_C_NEW_SESSION
32	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
76A 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
833. 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
109	uint32	MUX_C_OPEN_FWD
110	uint32	request id
111	uint32	forwarding type
112	string	listen host
113	uint32	listen port
114	string	connect host
115	uint32	connect port
116
117forwarding type may be MUX_FWD_LOCAL, MUX_FWD_REMOTE, MUX_FWD_DYNAMIC.
118
119If listen port is (unsigned int) -2, then the listen host is treated as
120a unix socket path name.
121
122If connect port is (unsigned int) -2, then the connect host is treated
123as a unix socket path name.
124
125A server may reply with a MUX_S_OK, a MUX_S_REMOTE_PORT, a
126MUX_S_PERMISSION_DENIED or a MUX_S_FAILURE.
127
128For dynamically allocated listen port the server replies with
129
130	uint32	MUX_S_REMOTE_PORT
131	uint32	client request id
132	uint32	allocated remote listen port
133
1346. Requesting closure of port forwards
135
136Note: currently unimplemented (server will always reply with MUX_S_FAILURE).
137
138A client may request the master to close a port forward:
139
140	uint32	MUX_C_CLOSE_FWD
141	uint32	request id
142	uint32	forwarding type
143	string	listen host
144	uint32	listen port
145	string	connect host
146	uint32	connect port
147
148A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
149MUX_S_FAILURE.
150
1517. Requesting stdio forwarding
152
153A client may request the master to establish a stdio forwarding:
154
155	uint32	MUX_C_NEW_STDIO_FWD
156	uint32	request id
157	string	reserved
158	string	connect host
159	string	connect port
160
161The client then sends its standard input and output file descriptors
162(in that order) using Unix domain socket control messages.
163
164The contents of "reserved" are currently ignored.
165
166A server may reply with a MUX_S_SESSION_OPENED, a MUX_S_PERMISSION_DENIED
167or a MUX_S_FAILURE.
168
1698. Requesting shutdown of mux listener
170
171A client may request the master to stop accepting new multiplexing requests
172and remove its listener socket.
173
174	uint32	MUX_C_STOP_LISTENING
175	uint32	request id
176
177A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
178MUX_S_FAILURE.
179
1809. Status messages
181
182The MUX_S_OK message is empty:
183
184	uint32	MUX_S_OK
185	uint32	client request id
186
187The MUX_S_PERMISSION_DENIED and MUX_S_FAILURE include a reason:
188
189	uint32	MUX_S_PERMISSION_DENIED
190	uint32	client request id
191	string	reason
192
193	uint32	MUX_S_FAILURE
194	uint32	client request id
195	string	reason
196
19710. Protocol numbers
198
199#define MUX_MSG_HELLO		0x00000001
200#define MUX_C_NEW_SESSION	0x10000002
201#define MUX_C_ALIVE_CHECK	0x10000004
202#define MUX_C_TERMINATE		0x10000005
203#define MUX_C_OPEN_FWD		0x10000006
204#define MUX_C_CLOSE_FWD		0x10000007
205#define MUX_C_NEW_STDIO_FWD	0x10000008
206#define MUX_C_STOP_LISTENING	0x10000009
207#define MUX_S_OK		0x80000001
208#define MUX_S_PERMISSION_DENIED	0x80000002
209#define MUX_S_FAILURE		0x80000003
210#define MUX_S_EXIT_MESSAGE	0x80000004
211#define MUX_S_ALIVE		0x80000005
212#define MUX_S_SESSION_OPENED	0x80000006
213#define MUX_S_REMOTE_PORT	0x80000007
214#define MUX_S_TTY_ALLOC_FAIL	0x80000008
215
216#define MUX_FWD_LOCAL	1
217#define MUX_FWD_REMOTE	2
218#define MUX_FWD_DYNAMIC	3
219
220XXX TODO
221XXX extended status (e.g. report open channels / forwards)
222XXX lock (maybe)
223XXX watch in/out traffic (pre/post crypto)
224XXX inject packet (what about replies)
225XXX server->client error/warning notifications
226XXX send signals via mux
227
228$OpenBSD: PROTOCOL.mux,v 1.10 2015/07/17 03:04:27 djm Exp $
229