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         string  listen port
 114         string  connect host
 115         string  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         string  listen host
 137         string  listen port
 138         string  connect host
 139         string  connect port
 140
 141 A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
 142 MUX_S_FAILURE.
 143
 144 7. Requesting stdio forwarding
 145
 146 A client may request the master to establish a stdio forwarding:
 147
 148         uint32  MUX_C_NEW_STDIO_FWD
 149         uint32  request id
 150         string  reserved
 151         string  connect host
 152         string  connect port
 153
 154 The client then sends its standard input and output file descriptors
 155 (in that order) using Unix domain socket control messages.
 156
 157 The contents of "reserved" are currently ignored.
 158
 159 A server may reply with a MUX_S_SESSION_OPENED, a MUX_S_PERMISSION_DENIED
 160 or a MUX_S_FAILURE.
 161
 162 8. Requesting shutdown of mux listener
 163
 164 A client may request the master to stop accepting new multiplexing requests
 165 and remove its listener socket.
 166
 167         uint32  MUX_C_STOP_LISTENING
 168         uint32  request id
 169
 170 A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
 171 MUX_S_FAILURE.
 172
 173 9. Status messages
 174
 175 The MUX_S_OK message is empty:
 176
 177         uint32  MUX_S_OK
 178         uint32  client request id
 179
 180 The MUX_S_PERMISSION_DENIED and MUX_S_FAILURE include a reason:
 181
 182         uint32  MUX_S_PERMISSION_DENIED
 183         uint32  client request id
 184         string  reason
 185
 186         uint32  MUX_S_FAILURE
 187         uint32  client request id
 188         string  reason
 189
 190 10. Protocol numbers
 191
 192 #define MUX_MSG_HELLO           0x00000001
 193 #define MUX_C_NEW_SESSION       0x10000002
 194 #define MUX_C_ALIVE_CHECK       0x10000004
 195 #define MUX_C_TERMINATE         0x10000005
 196 #define MUX_C_OPEN_FWD          0x10000006
 197 #define MUX_C_CLOSE_FWD         0x10000007
 198 #define MUX_C_NEW_STDIO_FWD     0x10000008
 199 #define MUX_C_STOP_LISTENING    0x10000009
 200 #define MUX_S_OK                0x80000001
 201 #define MUX_S_PERMISSION_DENIED 0x80000002
 202 #define MUX_S_FAILURE           0x80000003
 203 #define MUX_S_EXIT_MESSAGE      0x80000004
 204 #define MUX_S_ALIVE             0x80000005
 205 #define MUX_S_SESSION_OPENED    0x80000006
 206 #define MUX_S_REMOTE_PORT       0x80000007
 207 #define MUX_S_TTY_ALLOC_FAIL    0x80000008
 208
 209 #define MUX_FWD_LOCAL   1
 210 #define MUX_FWD_REMOTE  2
 211 #define MUX_FWD_DYNAMIC 3
 212
 213 XXX TODO
 214 XXX extended status (e.g. report open channels / forwards)
 215 XXX lock (maybe)
 216 XXX watch in/out traffic (pre/post crypto)
 217 XXX inject packet (what about replies)
 218 XXX server->client error/warning notifications
 219 XXX send signals via mux
 220
 221 $OpenBSD: PROTOCOL.mux,v 1.7 2011/05/08 12:52:01 djm Exp $