Edit File: PROTOCOL.mux
This document describes the multiplexing protocol used by ssh(1)'s ControlMaster connection-sharing. Most messages from the client to the server contain a "request id" field. This field is returned in replies as "client request id" to facilitate matching of responses to requests. 1. Connection setup When a multiplexing connection is made to a ssh(1) operating as a ControlMaster from a ssh(1) in multiplex slave mode, the first action of each is to exchange hello messages: uint32 MUX_MSG_HELLO uint32 protocol version string extension name [optional] string extension value [optional] ... The current version of the mux protocol is 4. A slave should refuse to connect to a master that speaks an unsupported protocol version. Following the version identifier are zero or more extensions represented as a name/value pair. No extensions are currently defined. 2. Opening sessions To open a new multiplexed session, a client may send the following request: uint32 MUX_C_NEW_SESSION uint32 request id string reserved bool want tty flag bool want X11 forwarding flag bool want agent flag bool subsystem flag uint32 escape char string terminal type string command string environment string 0 [optional] ... To disable the use of an escape character, "escape char" may be set to 0xffffffff. "terminal type" is generally set to the value of $TERM. zero or more environment strings may follow the command. The client then sends its standard input, output and error file descriptors (in that order) using Unix domain socket control messages. The contents of "reserved" are currently ignored. If successful, the server will reply with MUX_S_SESSION_OPENED uint32 MUX_S_SESSION_OPENED uint32 client request id uint32 session id Otherwise it will reply with an error: MUX_S_PERMISSION_DENIED or MUX_S_FAILURE. Once the server has received the fds, it will respond with MUX_S_OK indicating that the session is up. The client now waits for the session to end. When it does, the server will send an exit status message: uint32 MUX_S_EXIT_MESSAGE uint32 session id uint32 exit value The client should exit with this value to mimic the behaviour of a non-multiplexed ssh(1) connection. Two additional cases that the client must cope with are it receiving a signal itself and the server disconnecting without sending an exit message. A master may also send a MUX_S_TTY_ALLOC_FAIL before MUX_S_EXIT_MESSAGE if remote TTY allocation was unsuccessful. The client may use this to return its local tty to "cooked" mode. uint32 MUX_S_TTY_ALLOC_FAIL uint32 session id 3. Health checks The client may request a health check/PID report from a server: uint32 MUX_C_ALIVE_CHECK uint32 request id The server replies with: uint32 MUX_S_ALIVE uint32 client request id uint32 server pid 4. Remotely terminating a master A client may request that a master terminate immediately: uint32 MUX_C_TERMINATE uint32 request id The server will reply with one of MUX_S_OK or MUX_S_PERMISSION_DENIED. 5. Requesting establishment of port forwards A client may request the master to establish a port forward: uint32 MUX_C_OPEN_FWD uint32 request id uint32 forwarding type string listen host uint32 listen port string connect host uint32 connect port forwarding type may be MUX_FWD_LOCAL, MUX_FWD_REMOTE, MUX_FWD_DYNAMIC. If listen port is (unsigned int) -2, then the listen host is treated as a unix socket path name. If connect port is (unsigned int) -2, then the connect host is treated as a unix socket path name. A server may reply with a MUX_S_OK, a MUX_S_REMOTE_PORT, a MUX_S_PERMISSION_DENIED or a MUX_S_FAILURE. For dynamically allocated listen port the server replies with uint32 MUX_S_REMOTE_PORT uint32 client request id uint32 allocated remote listen port 6. Requesting closure of port forwards Note: currently unimplemented (server will always reply with MUX_S_FAILURE). A client may request the master to close a port forward: uint32 MUX_C_CLOSE_FWD uint32 request id uint32 forwarding type string listen host uint32 listen port string connect host uint32 connect port A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a MUX_S_FAILURE. 7. Requesting stdio forwarding A client may request the master to establish a stdio forwarding: uint32 MUX_C_NEW_STDIO_FWD uint32 request id string reserved string connect host string connect port The client then sends its standard input and output file descriptors (in that order) using Unix domain socket control messages. The contents of "reserved" are currently ignored. A server may reply with a MUX_S_SESSION_OPENED, a MUX_S_PERMISSION_DENIED or a MUX_S_FAILURE. 8. Requesting shutdown of mux listener A client may request the master to stop accepting new multiplexing requests and remove its listener socket. uint32 MUX_C_STOP_LISTENING uint32 request id A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a MUX_S_FAILURE. 9. Status messages The MUX_S_OK message is empty: uint32 MUX_S_OK uint32 client request id The MUX_S_PERMISSION_DENIED and MUX_S_FAILURE include a reason: uint32 MUX_S_PERMISSION_DENIED uint32 client request id string reason uint32 MUX_S_FAILURE uint32 client request id string reason 10. Protocol numbers #define MUX_MSG_HELLO 0x00000001 #define MUX_C_NEW_SESSION 0x10000002 #define MUX_C_ALIVE_CHECK 0x10000004 #define MUX_C_TERMINATE 0x10000005 #define MUX_C_OPEN_FWD 0x10000006 #define MUX_C_CLOSE_FWD 0x10000007 #define MUX_C_NEW_STDIO_FWD 0x10000008 #define MUX_C_STOP_LISTENING 0x10000009 #define MUX_S_OK 0x80000001 #define MUX_S_PERMISSION_DENIED 0x80000002 #define MUX_S_FAILURE 0x80000003 #define MUX_S_EXIT_MESSAGE 0x80000004 #define MUX_S_ALIVE 0x80000005 #define MUX_S_SESSION_OPENED 0x80000006 #define MUX_S_REMOTE_PORT 0x80000007 #define MUX_S_TTY_ALLOC_FAIL 0x80000008 #define MUX_FWD_LOCAL 1 #define MUX_FWD_REMOTE 2 #define MUX_FWD_DYNAMIC 3 XXX TODO XXX extended status (e.g. report open channels / forwards) XXX lock (maybe) XXX watch in/out traffic (pre/post crypto) XXX inject packet (what about replies) XXX server->client error/warning notifications XXX send signals via mux $OpenBSD: PROTOCOL.mux,v 1.10 2015/07/17 03:04:27 djm Exp $