Annotation of src/usr.bin/ssh/PROTOCOL.mux, Revision 1.2
1.1 djm 1: This document describes the multiplexing protocol used by ssh(1)'s
2: ControlMaster connection-sharing.
3:
4: Most messages from the client to the server contain a "request id" field.
5: This field is returned in replies as "client request id" to facilitate
6: matching of responses to requests.
7:
8: 1. Connection setup
9:
10: 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
12: action 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:
20: The current version of the mux protocol is 4. A slave should refuse
21: 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:
26: 2. Opening sessions
27:
28: To open a new multiplexed session, a client may send the following
29: request:
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:
44: To disable the use of an escape character, "escape char" may be set
45: to 0xffffffff. "terminal type" is generally set to the value of
46: $TERM. zero or more environment strings may follow the command.
47:
48: The client then sends its standard input, output and error file
49: descriptors (in that order) using Unix domain socket control messages.
50:
51: The contents of "reserved" are currently ignored.
52:
53: If 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:
59: Otherwise it will reply with an error: MUX_S_PERMISSION_DENIED or
60: MUX_S_FAILURE.
61:
62: Once the server has received the fds, it will respond with MUX_S_OK
63: indicating that the session is up. The client now waits for the
64: session to end. When it does, the server will send an exit status
65: message:
66:
67: uint32 MUX_S_EXIT_MESSAGE
68: uint32 session id
69: uint32 exit value
70:
71: The client should exit with this value to mimic the behaviour of a
72: non-multiplexed ssh(1) connection. Two additional cases that the
73: client must cope with are it receiving a signal itself and the
74: server disconnecting without sending an exit message.
75:
76: 3. Health checks
77:
78: The client may request a health check/PID report from a server:
79:
80: uint32 MUX_C_ALIVE_CHECK
81: uint32 request id
82:
83: The server replies with:
84:
85: uint32 MUX_S_ALIVE
86: uint32 client request id
87: uint32 server pid
88:
89: 4. Remotely terminating a master
90:
91: A client may request that a master terminate immediately:
92:
93: uint32 MUX_C_TERMINATE
94: uint32 request id
95:
96: The server will reply with one of MUX_S_OK or MUX_S_PERMISSION_DENIED.
97:
98: 5. Requesting establishment of port forwards
99:
100: A 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:
110: forwarding type may be MUX_FWD_LOCAL, MUX_FWD_REMOTE, MUX_FWD_DYNAMIC.
111:
1.2 ! markus 112: A server may reply with a MUX_S_OK, a MUX_S_REMOTE_PORT, a
! 113: MUX_S_PERMISSION_DENIED or a MUX_S_FAILURE.
! 114:
! 115: For dynamically allocated listen port the server replies with
! 116:
! 117: uint32 MUX_S_REMOTE_PORT
! 118: uint32 client request id
! 119: uint32 allocated remote listen port
1.1 djm 120:
121: 5. Requesting closure of port forwards
122:
123: A client may request the master to establish a port forward:
124:
125: uint32 MUX_C_OPEN_FORWARD
126: uint32 request id
127: uint32 forwarding type
128: string listen host
129: string listen port
130: string connect host
131: string connect port
132:
133: forwarding type may be MUX_FWD_LOCAL, MUX_FWD_REMOTE, MUX_FWD_DYNAMIC.
134:
135: A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
136: MUX_S_FAILURE.
137:
138: 6. Requesting stdio forwarding
139:
140: A client may request the master to establish a stdio forwarding:
141:
142: uint32 MUX_C_NEW_STDIO_FWD
143: uint32 request id
144: string reserved
145: string connect host
146: string connect port
147:
148: The client then sends its standard input and output file descriptors
149: (in that order) using Unix domain socket control messages.
150:
151: The contents of "reserved" are currently ignored.
152:
153: A server may reply with a MUX_S_SESSION_OPEED, a MUX_S_PERMISSION_DENIED
154: or a MUX_S_FAILURE.
155:
156: 7. Status messages
157:
158: The MUX_S_OK message is empty:
159:
160: uint32 MUX_S_OK
161: uint32 client request id
162:
163: The MUX_S_PERMISSION_DENIED and MUX_S_FAILURE include a reason:
164:
165: uint32 MUX_S_PERMISSION_DENIED
166: uint32 client request id
167: string reason
168:
169: uint32 MUX_S_FAILURE
170: uint32 client request id
171: string reason
172:
173: 7. Protocol numbers
174:
175: #define MUX_MSG_HELLO 0x00000001
176: #define MUX_C_NEW_SESSION 0x10000002
177: #define MUX_C_ALIVE_CHECK 0x10000004
178: #define MUX_C_TERMINATE 0x10000005
179: #define MUX_C_OPEN_FORWARD 0x10000006
180: #define MUX_C_CLOSE_FORWARD 0x10000007
181: #define MUX_S_OK 0x80000001
182: #define MUX_S_PERMISSION_DENIED 0x80000002
183: #define MUX_S_FAILURE 0x80000003
184: #define MUX_S_EXIT_MESSAGE 0x80000004
185: #define MUX_S_ALIVE 0x80000005
186: #define MUX_S_SESSION_OPENED 0x80000006
1.2 ! markus 187: #define MUX_S_REMOTE_PORT 0x80000007
1.1 djm 188:
189: #define MUX_FWD_LOCAL 1
190: #define MUX_FWD_REMOTE 2
191: #define MUX_FWD_DYNAMIC 3
192:
193: XXX TODO
194: XXX extended status (e.g. report open channels / forwards)
195: XXX graceful close (delete listening socket, but keep existing sessions active)
196: XXX lock (maybe)
197: XXX watch in/out traffic (pre/post crypto)
198: XXX inject packet (what about replies)
199: XXX server->client error/warning notifications
200: XXX port0 rfwd (need custom response message)
201: XXX send signals via mux
202:
1.2 ! markus 203: $OpenBSD: PROTOCOL.mux,v 1.1 2010/01/26 01:28:35 djm Exp $
![[BACK]](/icons/back.gif){kind=icon}
Return to PROTOCOL.mux CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / ssh