blob: d22f7379c85c1f10db636dcfbb734553fbed9b91 [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
31 uint32 MUX_C_MSG_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
763. Health checks
77
78The client may request a health check/PID report from a server:
79
80 uint32 MUX_C_ALIVE_CHECK
81 uint32 request id
82
83The server replies with:
84
85 uint32 MUX_S_ALIVE
86 uint32 client request id
87 uint32 server pid
88
894. Remotely terminating a master
90
91A client may request that a master terminate immediately:
92
93 uint32 MUX_C_TERMINATE
94 uint32 request id
95
96The server will reply with one of MUX_S_OK or MUX_S_PERMISSION_DENIED.
97
985. Requesting establishment of port forwards
99
100A client may request the master to establish a port forward:
101
102 uint32 MUX_C_OPEN_FORWARD
103 uint32 request id
104 uint32 forwarding type
105 string listen host
106 string listen port
107 string connect host
108 string connect port
109
110forwarding type may be MUX_FWD_LOCAL, MUX_FWD_REMOTE, MUX_FWD_DYNAMIC.
111
112A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
113MUX_S_FAILURE.
114
1155. Requesting closure of port forwards
116
117A client may request the master to establish a port forward:
118
119 uint32 MUX_C_OPEN_FORWARD
120 uint32 request id
121 uint32 forwarding type
122 string listen host
123 string listen port
124 string connect host
125 string connect port
126
127forwarding type may be MUX_FWD_LOCAL, MUX_FWD_REMOTE, MUX_FWD_DYNAMIC.
128
129A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
130MUX_S_FAILURE.
131
1326. Requesting stdio forwarding
133
134A client may request the master to establish a stdio forwarding:
135
136 uint32 MUX_C_NEW_STDIO_FWD
137 uint32 request id
138 string reserved
139 string connect host
140 string connect port
141
142The client then sends its standard input and output file descriptors
143(in that order) using Unix domain socket control messages.
144
145The contents of "reserved" are currently ignored.
146
147A server may reply with a MUX_S_SESSION_OPEED, a MUX_S_PERMISSION_DENIED
148or a MUX_S_FAILURE.
149
1507. Status messages
151
152The MUX_S_OK message is empty:
153
154 uint32 MUX_S_OK
155 uint32 client request id
156
157The MUX_S_PERMISSION_DENIED and MUX_S_FAILURE include a reason:
158
159 uint32 MUX_S_PERMISSION_DENIED
160 uint32 client request id
161 string reason
162
163 uint32 MUX_S_FAILURE
164 uint32 client request id
165 string reason
166
1677. Protocol numbers
168
169#define MUX_MSG_HELLO 0x00000001
170#define MUX_C_NEW_SESSION 0x10000002
171#define MUX_C_ALIVE_CHECK 0x10000004
172#define MUX_C_TERMINATE 0x10000005
173#define MUX_C_OPEN_FORWARD 0x10000006
174#define MUX_C_CLOSE_FORWARD 0x10000007
175#define MUX_S_OK 0x80000001
176#define MUX_S_PERMISSION_DENIED 0x80000002
177#define MUX_S_FAILURE 0x80000003
178#define MUX_S_EXIT_MESSAGE 0x80000004
179#define MUX_S_ALIVE 0x80000005
180#define MUX_S_SESSION_OPENED 0x80000006
181
182#define MUX_FWD_LOCAL 1
183#define MUX_FWD_REMOTE 2
184#define MUX_FWD_DYNAMIC 3
185
186XXX TODO
187XXX extended status (e.g. report open channels / forwards)
188XXX graceful close (delete listening socket, but keep existing sessions active)
189XXX lock (maybe)
190XXX watch in/out traffic (pre/post crypto)
191XXX inject packet (what about replies)
192XXX server->client error/warning notifications
193XXX port0 rfwd (need custom response message)
194XXX send signals via mux
195
196$OpenBSD: PROTOCOL.mux,v 1.1 2010/01/26 01:28:35 djm Exp $