PROTOCOL.mux revision 226046
160789SpsThis document describes the multiplexing protocol used by ssh(1)'s 2170260SdelphijControlMaster connection-sharing. 3128349Stjr 4128349StjrMost messages from the client to the server contain a "request id" field. 5128349StjrThis field is returned in replies as "client request id" to facilitate 660789Spsmatching of responses to requests. 760789Sps 860789Sps1. Connection setup 960789Sps 1060789SpsWhen a multiplexing connection is made to a ssh(1) operating as a 1160789SpsControlMaster from a ssh(1) in multiplex slave mode, the first 1260789Spsaction of each is to exchange hello messages: 1360789Sps 1460789Sps uint32 MUX_MSG_HELLO 1560789Sps uint32 protocol version 1660789Sps string extension name [optional] 17128349Stjr string extension value [optional] 1860789Sps ... 1960789Sps 2060789SpsThe current version of the mux protocol is 4. A slave should refuse 2160789Spsto connect to a master that speaks an unsupported protocol version. 2260789SpsFollowing the version identifier are zero or more extensions 23161479Sdelphijrepresented as a name/value pair. No extensions are currently 2460789Spsdefined. 25161479Sdelphij 2660789Sps2. Opening sessions 2760789Sps 2860789SpsTo open a new multiplexed session, a client may send the following 2960789Spsrequest: 3060789Sps 3160789Sps uint32 MUX_C_NEW_SESSION 3260789Sps uint32 request id 3360789Sps string reserved 3460789Sps bool want tty flag 3560789Sps bool want X11 forwarding flag 3660789Sps bool want agent flag 3760789Sps bool subsystem flag 3860789Sps uint32 escape char 3960789Sps string terminal type 4060789Sps string command 4160789Sps string environment string 0 [optional] 4260789Sps ... 4360789Sps 4460789SpsTo disable the use of an escape character, "escape char" may be set 4560789Spsto 0xffffffff. "terminal type" is generally set to the value of 4660789Sps$TERM. zero or more environment strings may follow the command. 4760789Sps 4860789SpsThe client then sends its standard input, output and error file 4960789Spsdescriptors (in that order) using Unix domain socket control messages. 5060789Sps 51170260SdelphijThe contents of "reserved" are currently ignored. 5260789Sps 5360789SpsIf successful, the server will reply with MUX_S_SESSION_OPENED 5460789Sps 5560789Sps uint32 MUX_S_SESSION_OPENED 5660789Sps uint32 client request id 5760789Sps uint32 session id 5860789Sps 5960789SpsOtherwise it will reply with an error: MUX_S_PERMISSION_DENIED or 6060789SpsMUX_S_FAILURE. 6160789Sps 6260789SpsOnce the server has received the fds, it will respond with MUX_S_OK 6360789Spsindicating that the session is up. The client now waits for the 6460789Spssession to end. When it does, the server will send an exit status 6560789Spsmessage: 6660789Sps 6760789Sps uint32 MUX_S_EXIT_MESSAGE 6860789Sps uint32 session id 69170260Sdelphij uint32 exit value 7060789Sps 7160789SpsThe client should exit with this value to mimic the behaviour of a 7260789Spsnon-multiplexed ssh(1) connection. Two additional cases that the 7360789Spsclient must cope with are it receiving a signal itself and the 7460789Spsserver disconnecting without sending an exit message. 7560789Sps 7660789SpsA master may also send a MUX_S_TTY_ALLOC_FAIL before MUX_S_EXIT_MESSAGE 7760789Spsif remote TTY allocation was unsuccessful. The client may use this to 7860789Spsreturn its local tty to "cooked" mode. 7960789Sps 8060789Sps uint32 MUX_S_TTY_ALLOC_FAIL 8160789Sps uint32 session id 8260789Sps 8360789Sps3. Health checks 8460789Sps 8560789SpsThe client may request a health check/PID report from a server: 8660789Sps 8760789Sps uint32 MUX_C_ALIVE_CHECK 8860789Sps uint32 request id 8960789Sps 9060789SpsThe server replies with: 9160789Sps 9260789Sps uint32 MUX_S_ALIVE 9360789Sps uint32 client request id 9460789Sps uint32 server pid 9560789Sps 9660789Sps4. Remotely terminating a master 9760789Sps 9860789SpsA client may request that a master terminate immediately: 9960789Sps 10060789Sps uint32 MUX_C_TERMINATE 10160789Sps uint32 request id 10260789Sps 10360789SpsThe server will reply with one of MUX_S_OK or MUX_S_PERMISSION_DENIED. 10460789Sps 10560789Sps5. Requesting establishment of port forwards 106170260Sdelphij 10760789SpsA client may request the master to establish a port forward: 10860789Sps 109170260Sdelphij uint32 MUX_C_OPEN_FWD 11060789Sps uint32 request id 111161479Sdelphij uint32 forwarding type 112161479Sdelphij string listen host 11360789Sps string listen port 11460789Sps string connect host 115128350Stjr string connect port 11660789Sps 117161479Sdelphijforwarding type may be MUX_FWD_LOCAL, MUX_FWD_REMOTE, MUX_FWD_DYNAMIC. 11860789Sps 119128349StjrA server may reply with a MUX_S_OK, a MUX_S_REMOTE_PORT, a 12060789SpsMUX_S_PERMISSION_DENIED or a MUX_S_FAILURE. 12160789Sps 12260789SpsFor dynamically allocated listen port the server replies with 12360789Sps 12460789Sps uint32 MUX_S_REMOTE_PORT 12560789Sps uint32 client request id 12660789Sps uint32 allocated remote listen port 12760789Sps 12860789Sps6. Requesting closure of port forwards 12960789Sps 13060789SpsNote: currently unimplemented (server will always reply with MUX_S_FAILURE). 13160789Sps 13260789SpsA client may request the master to close a port forward: 133170260Sdelphij 134170260Sdelphij uint32 MUX_C_CLOSE_FWD 135170260Sdelphij uint32 request id 136170260Sdelphij string listen host 137170260Sdelphij string listen port 138170260Sdelphij string connect host 13960789Sps string connect port 14060789Sps 141128349StjrA server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a 14260789SpsMUX_S_FAILURE. 14360789Sps 14460789Sps7. Requesting stdio forwarding 14560789Sps 14660789SpsA client may request the master to establish a stdio forwarding: 14760789Sps 14860789Sps uint32 MUX_C_NEW_STDIO_FWD 14960789Sps uint32 request id 15060789Sps string reserved 15160789Sps string connect host 15260789Sps string connect port 15360789Sps 15460789SpsThe client then sends its standard input and output file descriptors 15560789Sps(in that order) using Unix domain socket control messages. 15660789Sps 15760789SpsThe contents of "reserved" are currently ignored. 15860789Sps 15960789SpsA server may reply with a MUX_S_SESSION_OPENED, a MUX_S_PERMISSION_DENIED 16060789Spsor a MUX_S_FAILURE. 16160789Sps 16260789Sps8. Requesting shutdown of mux listener 16360789Sps 16460789SpsA client may request the master to stop accepting new multiplexing requests 16560789Spsand remove its listener socket. 16660789Sps 167170260Sdelphij uint32 MUX_C_STOP_LISTENING 16860789Sps uint32 request id 16960789Sps 170170260SdelphijA server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a 17160789SpsMUX_S_FAILURE. 17260789Sps 17360789Sps9. Status messages 17460789Sps 175170260SdelphijThe MUX_S_OK message is empty: 176170260Sdelphij 177170260Sdelphij uint32 MUX_S_OK 178170260Sdelphij uint32 client request id 179170260Sdelphij 180170260SdelphijThe MUX_S_PERMISSION_DENIED and MUX_S_FAILURE include a reason: 181170260Sdelphij 182170260Sdelphij uint32 MUX_S_PERMISSION_DENIED 183170260Sdelphij uint32 client request id 18460789Sps string reason 18560789Sps 18660789Sps uint32 MUX_S_FAILURE 187242618Sdelphij uint32 client request id 18860789Sps string reason 18960789Sps 19060789Sps10. Protocol numbers 19160789Sps 19260789Sps#define MUX_MSG_HELLO 0x00000001 19360789Sps#define MUX_C_NEW_SESSION 0x10000002 19460789Sps#define MUX_C_ALIVE_CHECK 0x10000004 19560789Sps#define MUX_C_TERMINATE 0x10000005 19689023Sps#define MUX_C_OPEN_FWD 0x10000006 197242584Sdelphij#define MUX_C_CLOSE_FWD 0x10000007 198242584Sdelphij#define MUX_C_NEW_STDIO_FWD 0x10000008 199242584Sdelphij#define MUX_C_STOP_LISTENING 0x10000009 200242584Sdelphij#define MUX_S_OK 0x80000001 201242584Sdelphij#define MUX_S_PERMISSION_DENIED 0x80000002 202242584Sdelphij#define MUX_S_FAILURE 0x80000003 203242584Sdelphij#define MUX_S_EXIT_MESSAGE 0x80000004 204242584Sdelphij#define MUX_S_ALIVE 0x80000005 205242584Sdelphij#define MUX_S_SESSION_OPENED 0x80000006 206242584Sdelphij#define MUX_S_REMOTE_PORT 0x80000007 207242584Sdelphij#define MUX_S_TTY_ALLOC_FAIL 0x80000008 208128349Stjr 20960789Sps#define MUX_FWD_LOCAL 1 21060789Sps#define MUX_FWD_REMOTE 2 21160789Sps#define MUX_FWD_DYNAMIC 3 212128349Stjr 213128349StjrXXX TODO 21460789SpsXXX extended status (e.g. report open channels / forwards) 215128349StjrXXX lock (maybe) 216128349StjrXXX watch in/out traffic (pre/post crypto) 21760789SpsXXX inject packet (what about replies) 218128349StjrXXX server->client error/warning notifications 219128349StjrXXX send signals via mux 22060789Sps 221128349Stjr$OpenBSD: PROTOCOL.mux,v 1.7 2011/05/08 12:52:01 djm Exp $ 222128349Stjr