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_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 1215. Requesting closure of port forwards 122 123A client may request the master to establish a port forward: 124 125 uint32 MUX_C_OPEN_FORWARD 126 uint32 request id 127 uint32 forwarding type 128 string listen host 129 string listen port 130 string connect host 131 string connect port 132 133forwarding type may be MUX_FWD_LOCAL, MUX_FWD_REMOTE, MUX_FWD_DYNAMIC. 134 135A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a 136MUX_S_FAILURE. 137 1386. Requesting stdio forwarding 139 140A client may request the master to establish a stdio forwarding: 141 142 uint32 MUX_C_NEW_STDIO_FWD 143 uint32 request id 144 string reserved 145 string connect host 146 string connect port 147 148The client then sends its standard input and output file descriptors 149(in that order) using Unix domain socket control messages. 150 151The contents of "reserved" are currently ignored. 152 153A server may reply with a MUX_S_SESSION_OPEED, a MUX_S_PERMISSION_DENIED 154or a MUX_S_FAILURE. 155 1567. Status messages 157 158The MUX_S_OK message is empty: 159 160 uint32 MUX_S_OK 161 uint32 client request id 162 163The MUX_S_PERMISSION_DENIED and MUX_S_FAILURE include a reason: 164 165 uint32 MUX_S_PERMISSION_DENIED 166 uint32 client request id 167 string reason 168 169 uint32 MUX_S_FAILURE 170 uint32 client request id 171 string reason 172 1737. Protocol numbers 174 175#define MUX_MSG_HELLO 0x00000001 176#define MUX_C_NEW_SESSION 0x10000002 177#define MUX_C_ALIVE_CHECK 0x10000004 178#define MUX_C_TERMINATE 0x10000005 179#define MUX_C_OPEN_FORWARD 0x10000006 180#define MUX_C_CLOSE_FORWARD 0x10000007 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.2 2010/05/16 12:55:51 markus Exp $ 204