RepoMirrors/openssh
1
0
Fork 0
mirror of git://anongit.mindrot.org/openssh.git synced 2025-02-04 08:01:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

upstream: Document mux proxy mode; added by Markus in openssh-7.4

Browse Source 
Also add a little bit of information about the overall packet format

OpenBSD-Commit-ID: bdb6f6ea8580ef96792e270cae7857786ad84a95
This commit is contained in:
djm@openbsd.org 2018-09-26 07:30:05 +00:00 committed by Damien Miller
parent 9d883a1ce4
commit 92b61a38ee
1 changed files with 107 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

144
PROTOCOL.mux
View File

@ -1,15 +1,52 @@
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.
Multiplexing starts with a ssh(1) configured to act as a multiplexing
master. This will cause ssh(1) to listen on a Unix domain socket for
requests from clients. Clients communicate over this socket using a
simple packetised protocol, where each message is proceeded with
a length and message type in SSH uint32 wire format:
uint32 packet length
uint32 packet type
... packet body
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.
Many muliplexing (mux) client requests yield immediate responses from
the mux process; requesting a forwarding, performing an alive check or
requesting the master terminate itself fall in to this category.
The most common use of multiplexing however is to maintain multiple
concurrent sessions. These are supported via two separate modes:
"Passenger" clients start by requesting a new session with a
MUX_C_NEW_SESSION message and passing stdio file descriptors over the
Unix domain control socket. The passenger client then waits until it is
signaled or the mux server closes the session. This mode is so named as
the client waits around while the mux server does all the driving.
Stdio forwarding (requested using MUX_C_NEW_STDIO_FWD) is another
example of passenger mode; the client passes the stdio file descriptors
and passively waits for something to happen.
"Proxy" clients, requested using MUX_C_PROXY, work quite differently. In
this mode, the mux client/server connection socket will stop speaking
the multiplexing protocol and start proxying SSH connection protocol
messages between the client and server. The client therefore must
speak a significant subset of the SSH protocol, but in return is able
to access basically the full suite of connection protocol features.
Moreover, as no file descriptor passing is required, the connection
supporting a proxy client may iteself be forwarded or relayed to another
host if necessary.
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:
ControlMaster from a client ssh(1), the first action of each is send
a hello messages to its peer:
uint32 MUX_MSG_HELLO
uint32 protocol version
@ -17,16 +54,16 @@ action of each is to exchange hello messages:
string extension value [optional]
...
The current version of the mux protocol is 4. A slave should refuse
The current version of the mux protocol is 4. A client 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
Following the version identifier are zero or more extensions represented
as a name/value pair. No extensions are currently defined.
To open a new multiplexed session, a client may send the following
request:
2. Opening a passenger mode session
To open a new multiplexed session in passenger mode, a client sends the
following request:
uint32 MUX_C_NEW_SESSION
uint32 request id
@ -80,7 +117,25 @@ return its local tty to "cooked" mode.
uint32 MUX_S_TTY_ALLOC_FAIL
uint32 session id
3. Health checks
3. Requesting passenger-mode 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.
4. Health checks
The client may request a health check/PID report from a server:
@ -93,7 +148,7 @@ The server replies with:
uint32 client request id
uint32 server pid
4. Remotely terminating a master
5. Remotely terminating a master
A client may request that a master terminate immediately:
@ -102,7 +157,7 @@ A client may request that a master terminate immediately:
The server will reply with one of MUX_S_OK or MUX_S_PERMISSION_DENIED.
5. Requesting establishment of port forwards
6. Requesting establishment of port forwards
A client may request the master to establish a port forward:
@ -131,7 +186,7 @@ For dynamically allocated listen port the server replies with
uint32 client request id
uint32 allocated remote listen port
6. Requesting closure of port forwards
7. Requesting closure of port forwards
Note: currently unimplemented (server will always reply with MUX_S_FAILURE).
@ -148,24 +203,6 @@ A client may request the master to close a port forward:
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
@ -177,7 +214,34 @@ and remove its listener socket.
A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
MUX_S_FAILURE.
9. Status messages
9. Requesting proxy mode
A client may request that the the control connection be placed in proxy
mode:
uint32 MUX_C_PROXY
uint32 request id
When a mux master receives this message, it will reply with a
confirmation:
uint32 MUX_S_PROXY
uint32 request id
And go into proxy mode. All subsequent data over the connection will
be formatted as unencrypted, unpadded, SSH transport messages:
uint32 packet length
byte 0 (padding length)
byte packet type
byte[packet length - 2] ...
The mux master will accept most connection messages and global requests,
and will translate channel identifiers to ensure that the proxy client has
globally unique channel numbers (i.e. a proxy client need not worry about
collisions with other clients).
10. Status messages
The MUX_S_OK message is empty:
@ -194,7 +258,7 @@ The MUX_S_PERMISSION_DENIED and MUX_S_FAILURE include a reason:
uint32 client request id
string reason
10. Protocol numbers
11. Protocol numbers
#define MUX_MSG_HELLO 0x00000001
#define MUX_C_NEW_SESSION 0x10000002
@ -224,5 +288,11 @@ 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
XXX ^Z support in passengers
XXX extensions for multi-agent
XXX extensions for multi-X11
XXX session inspection via master
XXX signals via mux request
XXX list active connections via mux
$OpenBSD: PROTOCOL.mux,v 1.10 2015/07/17 03:04:27 djm Exp $
$OpenBSD: PROTOCOL.mux,v 1.11 2018/09/26 07:30:05 djm Exp $