PROTOCOL.mux revision 204861
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_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 $ 197