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 76A master may also send a MUX_S_TTY_ALLOC_FAIL before MUX_S_EXIT_MESSAGE 77if remote TTY allocation was unsuccessful. The client may use this to 78return its local tty to "cooked" mode. 79 80 uint32 MUX_S_TTY_ALLOC_FAIL 81 uint32 session id 82 833. Health checks 84 85The client may request a health check/PID report from a server: 86 87 uint32 MUX_C_ALIVE_CHECK 88 uint32 request id 89 90The server replies with: 91 92 uint32 MUX_S_ALIVE 93 uint32 client request id 94 uint32 server pid 95 964. Remotely terminating a master 97 98A client may request that a master terminate immediately: 99 100 uint32 MUX_C_TERMINATE 101 uint32 request id 102 103The server will reply with one of MUX_S_OK or MUX_S_PERMISSION_DENIED. 104 1055. Requesting establishment of port forwards 106 107A client may request the master to establish a port forward: 108 109 uint32 MUX_C_OPEN_FWD 110 uint32 request id 111 uint32 forwarding type 112 string listen host 113 uint32 listen port 114 string connect host 115 uint32 connect port 116 117forwarding type may be MUX_FWD_LOCAL, MUX_FWD_REMOTE, MUX_FWD_DYNAMIC. 118 119A server may reply with a MUX_S_OK, a MUX_S_REMOTE_PORT, a 120MUX_S_PERMISSION_DENIED or a MUX_S_FAILURE. 121 122For dynamically allocated listen port the server replies with 123 124 uint32 MUX_S_REMOTE_PORT 125 uint32 client request id 126 uint32 allocated remote listen port 127 1286. Requesting closure of port forwards 129 130Note: currently unimplemented (server will always reply with MUX_S_FAILURE). 131 132A client may request the master to close a port forward: 133 134 uint32 MUX_C_CLOSE_FWD 135 uint32 request id 136 uint32 forwarding type 137 string listen host 138 uint32 listen port 139 string connect host 140 uint32 connect port 141 142A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a 143MUX_S_FAILURE. 144 1457. Requesting stdio forwarding 146 147A client may request the master to establish a stdio forwarding: 148 149 uint32 MUX_C_NEW_STDIO_FWD 150 uint32 request id 151 string reserved 152 string connect host 153 string connect port 154 155The client then sends its standard input and output file descriptors 156(in that order) using Unix domain socket control messages. 157 158The contents of "reserved" are currently ignored. 159 160A server may reply with a MUX_S_SESSION_OPENED, a MUX_S_PERMISSION_DENIED 161or a MUX_S_FAILURE. 162 1638. Requesting shutdown of mux listener 164 165A client may request the master to stop accepting new multiplexing requests 166and remove its listener socket. 167 168 uint32 MUX_C_STOP_LISTENING 169 uint32 request id 170 171A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a 172MUX_S_FAILURE. 173 1749. Status messages 175 176The MUX_S_OK message is empty: 177 178 uint32 MUX_S_OK 179 uint32 client request id 180 181The MUX_S_PERMISSION_DENIED and MUX_S_FAILURE include a reason: 182 183 uint32 MUX_S_PERMISSION_DENIED 184 uint32 client request id 185 string reason 186 187 uint32 MUX_S_FAILURE 188 uint32 client request id 189 string reason 190 19110. Protocol numbers 192 193#define MUX_MSG_HELLO 0x00000001 194#define MUX_C_NEW_SESSION 0x10000002 195#define MUX_C_ALIVE_CHECK 0x10000004 196#define MUX_C_TERMINATE 0x10000005 197#define MUX_C_OPEN_FWD 0x10000006 198#define MUX_C_CLOSE_FWD 0x10000007 199#define MUX_C_NEW_STDIO_FWD 0x10000008 200#define MUX_C_STOP_LISTENING 0x10000009 201#define MUX_S_OK 0x80000001 202#define MUX_S_PERMISSION_DENIED 0x80000002 203#define MUX_S_FAILURE 0x80000003 204#define MUX_S_EXIT_MESSAGE 0x80000004 205#define MUX_S_ALIVE 0x80000005 206#define MUX_S_SESSION_OPENED 0x80000006 207#define MUX_S_REMOTE_PORT 0x80000007 208#define MUX_S_TTY_ALLOC_FAIL 0x80000008 209 210#define MUX_FWD_LOCAL 1 211#define MUX_FWD_REMOTE 2 212#define MUX_FWD_DYNAMIC 3 213 214XXX TODO 215XXX extended status (e.g. report open channels / forwards) 216XXX lock (maybe) 217XXX watch in/out traffic (pre/post crypto) 218XXX inject packet (what about replies) 219XXX server->client error/warning notifications 220XXX send signals via mux 221 222$OpenBSD: PROTOCOL.mux,v 1.9 2012/06/01 00:49:35 djm Exp $ 223