PROTOCOL.mux

   1 This document describes the multiplexing protocol used by ssh(1)'s
   2 ControlMaster connection-sharing.
   3
   4 Most messages from the client to the server contain a "request id" field.
   5 This field is returned in replies as "client request id" to facilitate
   6 matching of responses to requests.
   7
   8 1. Connection setup
   9
  10 When a multiplexing connection is made to a ssh(1) operating as a
  11 ControlMaster from a ssh(1) in multiplex slave mode, the first
  12 action 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
  20 The current version of the mux protocol is 4. A slave should refuse
  21 to connect to a master that speaks an unsupported protocol version.
  22 Following the version identifier are zero or more extensions
  23 represented as a name/value pair. No extensions are currently
  24 defined.
  25
  26 2. Opening sessions
  27
  28 To open a new multiplexed session, a client may send the following
  29 request:
  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
  44 To disable the use of an escape character, "escape char" may be set
  45 to 0xffffffff. "terminal type" is generally set to the value of
  46 $TERM. zero or more environment strings may follow the command.
  47
  48 The client then sends its standard input, output and error file
  49 descriptors (in that order) using Unix domain socket control messages.
  50
  51 The contents of "reserved" are currently ignored.
  52
  53 If 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
  59 Otherwise it will reply with an error: MUX_S_PERMISSION_DENIED or
  60 MUX_S_FAILURE.
  61
  62 Once the server has received the fds, it will respond with MUX_S_OK
  63 indicating that the session is up. The client now waits for the
  64 session to end. When it does, the server will send an exit status
  65 message:
  66
  67         uint32  MUX_S_EXIT_MESSAGE
  68         uint32  session id
  69         uint32  exit value
  70
  71 The client should exit with this value to mimic the behaviour of a
  72 non-multiplexed ssh(1) connection. Two additional cases that the
  73 client must cope with are it receiving a signal itself and the
  74 server disconnecting without sending an exit message.
  75
  76 3. Health checks
  77
  78 The client may request a health check/PID report from a server:
  79
  80         uint32  MUX_C_ALIVE_CHECK
  81         uint32  request id
  82
  83 The server replies with:
  84
  85         uint32  MUX_S_ALIVE
  86         uint32  client request id
  87         uint32  server pid
  88
  89 4. Remotely terminating a master
  90
  91 A client may request that a master terminate immediately:
  92
  93         uint32  MUX_C_TERMINATE
  94         uint32  request id
  95
  96 The server will reply with one of MUX_S_OK or MUX_S_PERMISSION_DENIED.
  97
  98 5. Requesting establishment of port forwards
  99
 100 A 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
 110 forwarding type may be MUX_FWD_LOCAL, MUX_FWD_REMOTE, MUX_FWD_DYNAMIC.
 111
 112 A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
 113 MUX_S_FAILURE.
 114
 115 5. Requesting closure of port forwards
 116
 117 A client may request the master to establish a port forward:
 118
 119         uint32  MUX_C_OPEN_FORWARD
 120         uint32  request id
 121         uint32  forwarding type
 122         string  listen host
 123         string  listen port
 124         string  connect host
 125         string  connect port
 126
 127 forwarding type may be MUX_FWD_LOCAL, MUX_FWD_REMOTE, MUX_FWD_DYNAMIC.
 128
 129 A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
 130 MUX_S_FAILURE.
 131
 132 6. Requesting stdio forwarding
 133
 134 A client may request the master to establish a stdio forwarding:
 135
 136         uint32  MUX_C_NEW_STDIO_FWD
 137         uint32  request id
 138         string  reserved
 139         string  connect host
 140         string  connect port
 141
 142 The client then sends its standard input and output file descriptors
 143 (in that order) using Unix domain socket control messages.
 144
 145 The contents of "reserved" are currently ignored.
 146
 147 A server may reply with a MUX_S_SESSION_OPEED, a MUX_S_PERMISSION_DENIED
 148 or a MUX_S_FAILURE.
 149
 150 7. Status messages
 151
 152 The MUX_S_OK message is empty:
 153
 154         uint32  MUX_S_OK
 155         uint32  client request id
 156
 157 The MUX_S_PERMISSION_DENIED and MUX_S_FAILURE include a reason:
 158
 159         uint32  MUX_S_PERMISSION_DENIED
 160         uint32  client request id
 161         string  reason
 162
 163         uint32  MUX_S_FAILURE
 164         uint32  client request id
 165         string  reason
 166
 167 7. Protocol numbers
 168
 169 #define MUX_MSG_HELLO           0x00000001
 170 #define MUX_C_NEW_SESSION       0x10000002
 171 #define MUX_C_ALIVE_CHECK       0x10000004
 172 #define MUX_C_TERMINATE         0x10000005
 173 #define MUX_C_OPEN_FORWARD      0x10000006
 174 #define MUX_C_CLOSE_FORWARD     0x10000007
 175 #define MUX_S_OK                0x80000001
 176 #define MUX_S_PERMISSION_DENIED 0x80000002
 177 #define MUX_S_FAILURE           0x80000003
 178 #define MUX_S_EXIT_MESSAGE      0x80000004
 179 #define MUX_S_ALIVE             0x80000005
 180 #define MUX_S_SESSION_OPENED    0x80000006
 181
 182 #define MUX_FWD_LOCAL   1
 183 #define MUX_FWD_REMOTE  2
 184 #define MUX_FWD_DYNAMIC 3
 185
 186 XXX TODO
 187 XXX extended status (e.g. report open channels / forwards)
 188 XXX graceful close (delete listening socket, but keep existing sessions active)
 189 XXX lock (maybe)
 190 XXX watch in/out traffic (pre/post crypto)
 191 XXX inject packet (what about replies)
 192 XXX server->client error/warning notifications
 193 XXX port0 rfwd (need custom response message)
 194 XXX send signals via mux
 195
 196 $OpenBSD: PROTOCOL.mux,v 1.1 2010/01/26 01:28:35 djm Exp $