1204861SdesThis document describes the multiplexing protocol used by ssh(1)'s 2204861SdesControlMaster connection-sharing. 3204861Sdes 4204861SdesMost messages from the client to the server contain a "request id" field. 5204861SdesThis field is returned in replies as "client request id" to facilitate 6204861Sdesmatching of responses to requests. 7204861Sdes 8204861Sdes1. Connection setup 9204861Sdes 10204861SdesWhen a multiplexing connection is made to a ssh(1) operating as a 11204861SdesControlMaster from a ssh(1) in multiplex slave mode, the first 12204861Sdesaction of each is to exchange hello messages: 13204861Sdes 14204861Sdes uint32 MUX_MSG_HELLO 15204861Sdes uint32 protocol version 16204861Sdes string extension name [optional] 17204861Sdes string extension value [optional] 18204861Sdes ... 19204861Sdes 20204861SdesThe current version of the mux protocol is 4. A slave should refuse 21204861Sdesto connect to a master that speaks an unsupported protocol version. 22204861SdesFollowing the version identifier are zero or more extensions 23204861Sdesrepresented as a name/value pair. No extensions are currently 24204861Sdesdefined. 25204861Sdes 26204861Sdes2. Opening sessions 27204861Sdes 28204861SdesTo open a new multiplexed session, a client may send the following 29204861Sdesrequest: 30204861Sdes 31221420Sdes uint32 MUX_C_NEW_SESSION 32204861Sdes uint32 request id 33204861Sdes string reserved 34204861Sdes bool want tty flag 35204861Sdes bool want X11 forwarding flag 36204861Sdes bool want agent flag 37204861Sdes bool subsystem flag 38204861Sdes uint32 escape char 39204861Sdes string terminal type 40204861Sdes string command 41204861Sdes string environment string 0 [optional] 42204861Sdes ... 43204861Sdes 44204861SdesTo disable the use of an escape character, "escape char" may be set 45204861Sdesto 0xffffffff. "terminal type" is generally set to the value of 46204861Sdes$TERM. zero or more environment strings may follow the command. 47204861Sdes 48204861SdesThe client then sends its standard input, output and error file 49204861Sdesdescriptors (in that order) using Unix domain socket control messages. 50204861Sdes 51204861SdesThe contents of "reserved" are currently ignored. 52204861Sdes 53204861SdesIf successful, the server will reply with MUX_S_SESSION_OPENED 54204861Sdes 55204861Sdes uint32 MUX_S_SESSION_OPENED 56204861Sdes uint32 client request id 57204861Sdes uint32 session id 58204861Sdes 59204861SdesOtherwise it will reply with an error: MUX_S_PERMISSION_DENIED or 60204861SdesMUX_S_FAILURE. 61204861Sdes 62204861SdesOnce the server has received the fds, it will respond with MUX_S_OK 63204861Sdesindicating that the session is up. The client now waits for the 64204861Sdessession to end. When it does, the server will send an exit status 65204861Sdesmessage: 66204861Sdes 67204861Sdes uint32 MUX_S_EXIT_MESSAGE 68204861Sdes uint32 session id 69204861Sdes uint32 exit value 70204861Sdes 71204861SdesThe client should exit with this value to mimic the behaviour of a 72204861Sdesnon-multiplexed ssh(1) connection. Two additional cases that the 73204861Sdesclient must cope with are it receiving a signal itself and the 74204861Sdesserver disconnecting without sending an exit message. 75204861Sdes 76226046SdesA master may also send a MUX_S_TTY_ALLOC_FAIL before MUX_S_EXIT_MESSAGE 77226046Sdesif remote TTY allocation was unsuccessful. The client may use this to 78226046Sdesreturn its local tty to "cooked" mode. 79226046Sdes 80226046Sdes uint32 MUX_S_TTY_ALLOC_FAIL 81226046Sdes uint32 session id 82226046Sdes 83204861Sdes3. Health checks 84204861Sdes 85204861SdesThe client may request a health check/PID report from a server: 86204861Sdes 87204861Sdes uint32 MUX_C_ALIVE_CHECK 88204861Sdes uint32 request id 89204861Sdes 90204861SdesThe server replies with: 91204861Sdes 92204861Sdes uint32 MUX_S_ALIVE 93204861Sdes uint32 client request id 94204861Sdes uint32 server pid 95204861Sdes 96204861Sdes4. Remotely terminating a master 97204861Sdes 98204861SdesA client may request that a master terminate immediately: 99204861Sdes 100204861Sdes uint32 MUX_C_TERMINATE 101204861Sdes uint32 request id 102204861Sdes 103204861SdesThe server will reply with one of MUX_S_OK or MUX_S_PERMISSION_DENIED. 104204861Sdes 105204861Sdes5. Requesting establishment of port forwards 106204861Sdes 107204861SdesA client may request the master to establish a port forward: 108204861Sdes 109221420Sdes uint32 MUX_C_OPEN_FWD 110204861Sdes uint32 request id 111204861Sdes uint32 forwarding type 112204861Sdes string listen host 113240075Sdes uint32 listen port 114204861Sdes string connect host 115240075Sdes uint32 connect port 116204861Sdes 117204861Sdesforwarding type may be MUX_FWD_LOCAL, MUX_FWD_REMOTE, MUX_FWD_DYNAMIC. 118204861Sdes 119295367SdesIf listen port is (unsigned int) -2, then the listen host is treated as 120295367Sdesa unix socket path name. 121295367Sdes 122295367SdesIf connect port is (unsigned int) -2, then the connect host is treated 123295367Sdesas a unix socket path name. 124295367Sdes 125215116SdesA server may reply with a MUX_S_OK, a MUX_S_REMOTE_PORT, a 126215116SdesMUX_S_PERMISSION_DENIED or a MUX_S_FAILURE. 127204861Sdes 128215116SdesFor dynamically allocated listen port the server replies with 129215116Sdes 130215116Sdes uint32 MUX_S_REMOTE_PORT 131215116Sdes uint32 client request id 132215116Sdes uint32 allocated remote listen port 133215116Sdes 134221420Sdes6. Requesting closure of port forwards 135204861Sdes 136221420SdesNote: currently unimplemented (server will always reply with MUX_S_FAILURE). 137204861Sdes 138221420SdesA client may request the master to close a port forward: 139221420Sdes 140221420Sdes uint32 MUX_C_CLOSE_FWD 141204861Sdes uint32 request id 142240075Sdes uint32 forwarding type 143204861Sdes string listen host 144240075Sdes uint32 listen port 145204861Sdes string connect host 146240075Sdes uint32 connect port 147204861Sdes 148204861SdesA server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a 149204861SdesMUX_S_FAILURE. 150204861Sdes 151221420Sdes7. Requesting stdio forwarding 152204861Sdes 153204861SdesA client may request the master to establish a stdio forwarding: 154204861Sdes 155204861Sdes uint32 MUX_C_NEW_STDIO_FWD 156204861Sdes uint32 request id 157204861Sdes string reserved 158204861Sdes string connect host 159204861Sdes string connect port 160204861Sdes 161204861SdesThe client then sends its standard input and output file descriptors 162204861Sdes(in that order) using Unix domain socket control messages. 163204861Sdes 164204861SdesThe contents of "reserved" are currently ignored. 165204861Sdes 166226046SdesA server may reply with a MUX_S_SESSION_OPENED, a MUX_S_PERMISSION_DENIED 167204861Sdesor a MUX_S_FAILURE. 168204861Sdes 169226046Sdes8. Requesting shutdown of mux listener 170204861Sdes 171226046SdesA client may request the master to stop accepting new multiplexing requests 172226046Sdesand remove its listener socket. 173226046Sdes 174226046Sdes uint32 MUX_C_STOP_LISTENING 175226046Sdes uint32 request id 176226046Sdes 177226046SdesA server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a 178226046SdesMUX_S_FAILURE. 179226046Sdes 180226046Sdes9. Status messages 181226046Sdes 182204861SdesThe MUX_S_OK message is empty: 183204861Sdes 184204861Sdes uint32 MUX_S_OK 185204861Sdes uint32 client request id 186204861Sdes 187204861SdesThe MUX_S_PERMISSION_DENIED and MUX_S_FAILURE include a reason: 188204861Sdes 189204861Sdes uint32 MUX_S_PERMISSION_DENIED 190204861Sdes uint32 client request id 191204861Sdes string reason 192204861Sdes 193204861Sdes uint32 MUX_S_FAILURE 194204861Sdes uint32 client request id 195204861Sdes string reason 196204861Sdes 197226046Sdes10. Protocol numbers 198204861Sdes 199204861Sdes#define MUX_MSG_HELLO 0x00000001 200204861Sdes#define MUX_C_NEW_SESSION 0x10000002 201204861Sdes#define MUX_C_ALIVE_CHECK 0x10000004 202204861Sdes#define MUX_C_TERMINATE 0x10000005 203221420Sdes#define MUX_C_OPEN_FWD 0x10000006 204221420Sdes#define MUX_C_CLOSE_FWD 0x10000007 205221420Sdes#define MUX_C_NEW_STDIO_FWD 0x10000008 206226046Sdes#define MUX_C_STOP_LISTENING 0x10000009 207204861Sdes#define MUX_S_OK 0x80000001 208204861Sdes#define MUX_S_PERMISSION_DENIED 0x80000002 209204861Sdes#define MUX_S_FAILURE 0x80000003 210204861Sdes#define MUX_S_EXIT_MESSAGE 0x80000004 211204861Sdes#define MUX_S_ALIVE 0x80000005 212204861Sdes#define MUX_S_SESSION_OPENED 0x80000006 213215116Sdes#define MUX_S_REMOTE_PORT 0x80000007 214226046Sdes#define MUX_S_TTY_ALLOC_FAIL 0x80000008 215204861Sdes 216204861Sdes#define MUX_FWD_LOCAL 1 217204861Sdes#define MUX_FWD_REMOTE 2 218204861Sdes#define MUX_FWD_DYNAMIC 3 219204861Sdes 220204861SdesXXX TODO 221204861SdesXXX extended status (e.g. report open channels / forwards) 222204861SdesXXX lock (maybe) 223204861SdesXXX watch in/out traffic (pre/post crypto) 224204861SdesXXX inject packet (what about replies) 225204861SdesXXX server->client error/warning notifications 226204861SdesXXX send signals via mux 227204861Sdes 228295367Sdes$OpenBSD: PROTOCOL.mux,v 1.10 2015/07/17 03:04:27 djm Exp $ 229