Annotation of src/usr.bin/ssh/PROTOCOL.mux, Revision 1.3
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:
1.3 ! djm 31: uint32 MUX_C_NEW_SESSION
1.1 djm 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:
1.3 ! djm 102: uint32 MUX_C_OPEN_FWD
1.1 djm 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:
1.3 ! djm 121: 6. Requesting closure of port forwards
! 122:
! 123: Note: currently unimplemented (server will always reply with MUX_S_FAILURE).
1.1 djm 124:
125: A client may request the master to establish a port forward:
126:
1.3 ! djm 127: uint32 MUX_C_CLOSE_FWD
1.1 djm 128: uint32 request id
129: string listen host
130: string listen port
131: string connect host
132: string connect port
133:
134: A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
135: MUX_S_FAILURE.
136:
1.3 ! djm 137: 7. Requesting stdio forwarding
1.1 djm 138:
139: A client may request the master to establish a stdio forwarding:
140:
141: uint32 MUX_C_NEW_STDIO_FWD
142: uint32 request id
143: string reserved
144: string connect host
145: string connect port
146:
147: The client then sends its standard input and output file descriptors
148: (in that order) using Unix domain socket control messages.
149:
150: The contents of "reserved" are currently ignored.
151:
152: A server may reply with a MUX_S_SESSION_OPEED, a MUX_S_PERMISSION_DENIED
153: or a MUX_S_FAILURE.
154:
1.3 ! djm 155: 8. Status messages
1.1 djm 156:
157: The MUX_S_OK message is empty:
158:
159: uint32 MUX_S_OK
160: uint32 client request id
161:
162: The MUX_S_PERMISSION_DENIED and MUX_S_FAILURE include a reason:
163:
164: uint32 MUX_S_PERMISSION_DENIED
165: uint32 client request id
166: string reason
167:
168: uint32 MUX_S_FAILURE
169: uint32 client request id
170: string reason
171:
1.3 ! djm 172: 9. Protocol numbers
1.1 djm 173:
174: #define MUX_MSG_HELLO 0x00000001
175: #define MUX_C_NEW_SESSION 0x10000002
176: #define MUX_C_ALIVE_CHECK 0x10000004
177: #define MUX_C_TERMINATE 0x10000005
1.3 ! djm 178: #define MUX_C_OPEN_FWD 0x10000006
! 179: #define MUX_C_CLOSE_FWD 0x10000007
! 180: #define MUX_C_NEW_STDIO_FWD 0x10000008
1.1 djm 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.3 ! djm 203: $OpenBSD: PROTOCOL.mux,v 1.2 2010/05/16 12:55:51 markus 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