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 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_FWD 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_REMOTE_PORT, a 113MUX_S_PERMISSION_DENIED or a MUX_S_FAILURE. 114 115For 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 120 1216. Requesting closure of port forwards 122 123Note: currently unimplemented (server will always reply with MUX_S_FAILURE). 124 125A client may request the master to close a port forward: 126 127 uint32 MUX_C_CLOSE_FWD 128 uint32 request id 129 string listen host 130 string listen port 131 string connect host 132 string connect port 133 134A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a 135MUX_S_FAILURE. 136 1377. Requesting stdio forwarding 138 139A 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 147The client then sends its standard input and output file descriptors 148(in that order) using Unix domain socket control messages. 149 150The contents of "reserved" are currently ignored. 151 152A server may reply with a MUX_S_SESSION_OPEED, a MUX_S_PERMISSION_DENIED 153or a MUX_S_FAILURE. 154 1558. Status messages 156 157The MUX_S_OK message is empty: 158 159 uint32 MUX_S_OK 160 uint32 client request id 161 162The 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 1729. Protocol numbers 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 178#define MUX_C_OPEN_FWD 0x10000006 179#define MUX_C_CLOSE_FWD 0x10000007 180#define MUX_C_NEW_STDIO_FWD 0x10000008 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 187#define MUX_S_REMOTE_PORT 0x80000007 188 189#define MUX_FWD_LOCAL 1 190#define MUX_FWD_REMOTE 2 191#define MUX_FWD_DYNAMIC 3 192 193XXX TODO 194XXX extended status (e.g. report open channels / forwards) 195XXX graceful close (delete listening socket, but keep existing sessions active) 196XXX lock (maybe) 197XXX watch in/out traffic (pre/post crypto) 198XXX inject packet (what about replies) 199XXX server->client error/warning notifications 200XXX port0 rfwd (need custom response message) 201XXX send signals via mux 202 203$OpenBSD: PROTOCOL.mux,v 1.4 2011/01/31 21:42:15 djm Exp $ 204