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_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_FWD
 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_REMOTE_PORT, a
 113 MUX_S_PERMISSION_DENIED or a MUX_S_FAILURE.
 114
 115 For 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
 121 6. Requesting closure of port forwards
 122
 123 Note: currently unimplemented (server will always reply with MUX_S_FAILURE).
 124
 125 A client may request the master to establish a port forward:
 126
 127         uint32  MUX_C_CLOSE_FWD
 128         uint32  request id
 129         string  listen host
 130         string  listen port
 131         string  connect host
 132         string  connect port
 133
 134 A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
 135 MUX_S_FAILURE.
 136
 137 7. Requesting stdio forwarding
 138
 139 A client may request the master to establish a stdio forwarding:
 140
 141         uint32  MUX_C_NEW_STDIO_FWD
 142         uint32  request id
 143         string  reserved
 144         string  connect host
 145         string  connect port
 146
 147 The client then sends its standard input and output file descriptors
 148 (in that order) using Unix domain socket control messages.
 149
 150 The contents of "reserved" are currently ignored.
 151
 152 A server may reply with a MUX_S_SESSION_OPEED, a MUX_S_PERMISSION_DENIED
 153 or a MUX_S_FAILURE.
 154
 155 8. Status messages
 156
 157 The MUX_S_OK message is empty:
 158
 159         uint32  MUX_S_OK
 160         uint32  client request id
 161
 162 The MUX_S_PERMISSION_DENIED and MUX_S_FAILURE include a reason:
 163
 164         uint32  MUX_S_PERMISSION_DENIED
 165         uint32  client request id
 166         string  reason
 167
 168         uint32  MUX_S_FAILURE
 169         uint32  client request id
 170         string  reason
 171
 172 9. Protocol numbers
 173
 174 #define MUX_MSG_HELLO           0x00000001
 175 #define MUX_C_NEW_SESSION       0x10000002
 176 #define MUX_C_ALIVE_CHECK       0x10000004
 177 #define MUX_C_TERMINATE         0x10000005
 178 #define MUX_C_OPEN_FWD          0x10000006
 179 #define MUX_C_CLOSE_FWD         0x10000007
 180 #define MUX_C_NEW_STDIO_FWD     0x10000008
 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
 193 XXX TODO
 194 XXX extended status (e.g. report open channels / forwards)
 195 XXX graceful close (delete listening socket, but keep existing sessions active)
 196 XXX lock (maybe)
 197 XXX watch in/out traffic (pre/post crypto)
 198 XXX inject packet (what about replies)
 199 XXX server->client error/warning notifications
 200 XXX port0 rfwd (need custom response message)
 201 XXX send signals via mux
 202
 203 $OpenBSD: PROTOCOL.mux,v 1.3 2011/01/13 21:55:25 djm Exp $