[openssh-commits] [openssh] 01/02: upstream: Document mux proxy mode; added by Markus in openssh-7.4
git+noreply at mindrot.org
git+noreply at mindrot.org
Wed Sep 26 17:35:58 AEST 2018
This is an automated email from the git hooks/post-receive script.
djm pushed a commit to branch master
in repository openssh.
commit 92b61a38ee9b765f5049f03cd1143e13f3878905
Author: djm at openbsd.org <djm at openbsd.org>
Date: Wed Sep 26 07:30:05 2018 +0000
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
---
PROTOCOL.mux | 144 ++++++++++++++++++++++++++++++++++++++++++++---------------
1 file changed, 107 insertions(+), 37 deletions(-)
diff --git a/PROTOCOL.mux b/PROTOCOL.mux
index f042961f..77a0780a 100644
--- a/PROTOCOL.mux
+++ b/PROTOCOL.mux
@@ -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 $
--
To stop receiving notification emails like this one, please contact
djm at mindrot.org.
More information about the openssh-commits
mailing list