mirror of
https://github.com/PowerShell/openssh-portable.git
synced 2025-07-30 17:25:09 +02:00
upstream: Document mux proxy mode; added by Markus in openssh-7.4
Also add a little bit of information about the overall packet format OpenBSD-Commit-ID: bdb6f6ea8580ef96792e270cae7857786ad84a95
This commit is contained in:
parent
9d883a1ce4
commit
92b61a38ee
144
PROTOCOL.mux
144
PROTOCOL.mux
@ -1,15 +1,52 @@
|
|||||||
This document describes the multiplexing protocol used by ssh(1)'s
|
This document describes the multiplexing protocol used by ssh(1)'s
|
||||||
ControlMaster connection-sharing.
|
ControlMaster connection-sharing.
|
||||||
|
|
||||||
Most messages from the client to the server contain a "request id" field.
|
Multiplexing starts with a ssh(1) configured to act as a multiplexing
|
||||||
This field is returned in replies as "client request id" to facilitate
|
master. This will cause ssh(1) to listen on a Unix domain socket for
|
||||||
matching of responses to requests.
|
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
|
1. Connection setup
|
||||||
|
|
||||||
When a multiplexing connection is made to a ssh(1) operating as a
|
When a multiplexing connection is made to a ssh(1) operating as a
|
||||||
ControlMaster from a ssh(1) in multiplex slave mode, the first
|
ControlMaster from a client ssh(1), the first action of each is send
|
||||||
action of each is to exchange hello messages:
|
a hello messages to its peer:
|
||||||
|
|
||||||
uint32 MUX_MSG_HELLO
|
uint32 MUX_MSG_HELLO
|
||||||
uint32 protocol version
|
uint32 protocol version
|
||||||
@ -17,16 +54,16 @@ action of each is to exchange hello messages:
|
|||||||
string extension value [optional]
|
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.
|
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
|
2. Opening a passenger mode session
|
||||||
request:
|
|
||||||
|
To open a new multiplexed session in passenger mode, a client sends the
|
||||||
|
following request:
|
||||||
|
|
||||||
uint32 MUX_C_NEW_SESSION
|
uint32 MUX_C_NEW_SESSION
|
||||||
uint32 request id
|
uint32 request id
|
||||||
@ -80,7 +117,25 @@ return its local tty to "cooked" mode.
|
|||||||
uint32 MUX_S_TTY_ALLOC_FAIL
|
uint32 MUX_S_TTY_ALLOC_FAIL
|
||||||
uint32 session id
|
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:
|
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 client request id
|
||||||
uint32 server pid
|
uint32 server pid
|
||||||
|
|
||||||
4. Remotely terminating a master
|
5. Remotely terminating a master
|
||||||
|
|
||||||
A client may request that a master terminate immediately:
|
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.
|
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:
|
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 client request id
|
||||||
uint32 allocated remote listen port
|
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).
|
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
|
A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
|
||||||
MUX_S_FAILURE.
|
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
|
8. Requesting shutdown of mux listener
|
||||||
|
|
||||||
A client may request the master to stop accepting new multiplexing requests
|
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
|
A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
|
||||||
MUX_S_FAILURE.
|
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:
|
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
|
uint32 client request id
|
||||||
string reason
|
string reason
|
||||||
|
|
||||||
10. Protocol numbers
|
11. Protocol numbers
|
||||||
|
|
||||||
#define MUX_MSG_HELLO 0x00000001
|
#define MUX_MSG_HELLO 0x00000001
|
||||||
#define MUX_C_NEW_SESSION 0x10000002
|
#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 inject packet (what about replies)
|
||||||
XXX server->client error/warning notifications
|
XXX server->client error/warning notifications
|
||||||
XXX send signals via mux
|
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 $
|
||||||
|
Loading…
x
Reference in New Issue
Block a user