crypto/openssh/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 A master may also send a MUX_S_TTY_ALLOC_FAIL before MUX_S_EXIT_MESSAGE
  77 if remote TTY allocation was unsuccessful. The client may use this to
  78 return its local tty to "cooked" mode.
  79
  80         uint32  MUX_S_TTY_ALLOC_FAIL
  81         uint32  session id
  82
  83 3. Health checks
  84
  85 The client may request a health check/PID report from a server:
  86
  87         uint32  MUX_C_ALIVE_CHECK
  88         uint32  request id
  89
  90 The server replies with:
  91
  92         uint32  MUX_S_ALIVE
  93         uint32  client request id
  94         uint32  server pid
  95
  96 4. Remotely terminating a master
  97
  98 A client may request that a master terminate immediately:
  99
 100         uint32  MUX_C_TERMINATE
 101         uint32  request id
 102
 103 The server will reply with one of MUX_S_OK or MUX_S_PERMISSION_DENIED.
 104
 105 5. Requesting establishment of port forwards
 106
 107 A 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
 117 forwarding type may be MUX_FWD_LOCAL, MUX_FWD_REMOTE, MUX_FWD_DYNAMIC.
 118
 119 A server may reply with a MUX_S_OK, a MUX_S_REMOTE_PORT, a
 120 MUX_S_PERMISSION_DENIED or a MUX_S_FAILURE.
 121
 122 For 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
 128 6. Requesting closure of port forwards
 129
 130 Note: currently unimplemented (server will always reply with MUX_S_FAILURE).
 131
 132 A 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
 142 A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
 143 MUX_S_FAILURE.
 144
 145 7. Requesting stdio forwarding
 146
 147 A 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
 155 The client then sends its standard input and output file descriptors
 156 (in that order) using Unix domain socket control messages.
 157
 158 The contents of "reserved" are currently ignored.
 159
 160 A server may reply with a MUX_S_SESSION_OPENED, a MUX_S_PERMISSION_DENIED
 161 or a MUX_S_FAILURE.
 162
 163 8. Requesting shutdown of mux listener
 164
 165 A client may request the master to stop accepting new multiplexing requests
 166 and remove its listener socket.
 167
 168         uint32  MUX_C_STOP_LISTENING
 169         uint32  request id
 170
 171 A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
 172 MUX_S_FAILURE.
 173
 174 9. Status messages
 175
 176 The MUX_S_OK message is empty:
 177
 178         uint32  MUX_S_OK
 179         uint32  client request id
 180
 181 The 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
 191 10. 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
 214 XXX TODO
 215 XXX extended status (e.g. report open channels / forwards)
 216 XXX lock (maybe)
 217 XXX watch in/out traffic (pre/post crypto)
 218 XXX inject packet (what about replies)
 219 XXX server->client error/warning notifications
 220 XXX send signals via mux
 221
 222 $OpenBSD: PROTOCOL.mux,v 1.9 2012/06/01 00:49:35 djm Exp $