Annotation of src/usr.bin/ssh/PROTOCOL.mux, Revision 1.1
1.1 ! djm 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_MSG_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: 3. Health checks
! 77:
! 78: The client may request a health check/PID report from a server:
! 79:
! 80: uint32 MUX_C_ALIVE_CHECK
! 81: uint32 request id
! 82:
! 83: The server replies with:
! 84:
! 85: uint32 MUX_S_ALIVE
! 86: uint32 client request id
! 87: uint32 server pid
! 88:
! 89: 4. Remotely terminating a master
! 90:
! 91: A client may request that a master terminate immediately:
! 92:
! 93: uint32 MUX_C_TERMINATE
! 94: uint32 request id
! 95:
! 96: The server will reply with one of MUX_S_OK or MUX_S_PERMISSION_DENIED.
! 97:
! 98: 5. Requesting establishment of port forwards
! 99:
! 100: A client may request the master to establish a port forward:
! 101:
! 102: uint32 MUX_C_OPEN_FORWARD
! 103: uint32 request id
! 104: uint32 forwarding type
! 105: string listen host
! 106: string listen port
! 107: string connect host
! 108: string connect port
! 109:
! 110: forwarding type may be MUX_FWD_LOCAL, MUX_FWD_REMOTE, MUX_FWD_DYNAMIC.
! 111:
! 112: A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
! 113: MUX_S_FAILURE.
! 114:
! 115: 5. Requesting closure of port forwards
! 116:
! 117: A client may request the master to establish a port forward:
! 118:
! 119: uint32 MUX_C_OPEN_FORWARD
! 120: uint32 request id
! 121: uint32 forwarding type
! 122: string listen host
! 123: string listen port
! 124: string connect host
! 125: string connect port
! 126:
! 127: forwarding type may be MUX_FWD_LOCAL, MUX_FWD_REMOTE, MUX_FWD_DYNAMIC.
! 128:
! 129: A server may reply with a MUX_S_OK, a MUX_S_PERMISSION_DENIED or a
! 130: MUX_S_FAILURE.
! 131:
! 132: 6. Requesting stdio forwarding
! 133:
! 134: A client may request the master to establish a stdio forwarding:
! 135:
! 136: uint32 MUX_C_NEW_STDIO_FWD
! 137: uint32 request id
! 138: string reserved
! 139: string connect host
! 140: string connect port
! 141:
! 142: The client then sends its standard input and output file descriptors
! 143: (in that order) using Unix domain socket control messages.
! 144:
! 145: The contents of "reserved" are currently ignored.
! 146:
! 147: A server may reply with a MUX_S_SESSION_OPEED, a MUX_S_PERMISSION_DENIED
! 148: or a MUX_S_FAILURE.
! 149:
! 150: 7. Status messages
! 151:
! 152: The MUX_S_OK message is empty:
! 153:
! 154: uint32 MUX_S_OK
! 155: uint32 client request id
! 156:
! 157: The MUX_S_PERMISSION_DENIED and MUX_S_FAILURE include a reason:
! 158:
! 159: uint32 MUX_S_PERMISSION_DENIED
! 160: uint32 client request id
! 161: string reason
! 162:
! 163: uint32 MUX_S_FAILURE
! 164: uint32 client request id
! 165: string reason
! 166:
! 167: 7. Protocol numbers
! 168:
! 169: #define MUX_MSG_HELLO 0x00000001
! 170: #define MUX_C_NEW_SESSION 0x10000002
! 171: #define MUX_C_ALIVE_CHECK 0x10000004
! 172: #define MUX_C_TERMINATE 0x10000005
! 173: #define MUX_C_OPEN_FORWARD 0x10000006
! 174: #define MUX_C_CLOSE_FORWARD 0x10000007
! 175: #define MUX_S_OK 0x80000001
! 176: #define MUX_S_PERMISSION_DENIED 0x80000002
! 177: #define MUX_S_FAILURE 0x80000003
! 178: #define MUX_S_EXIT_MESSAGE 0x80000004
! 179: #define MUX_S_ALIVE 0x80000005
! 180: #define MUX_S_SESSION_OPENED 0x80000006
! 181:
! 182: #define MUX_FWD_LOCAL 1
! 183: #define MUX_FWD_REMOTE 2
! 184: #define MUX_FWD_DYNAMIC 3
! 185:
! 186: XXX TODO
! 187: XXX extended status (e.g. report open channels / forwards)
! 188: XXX graceful close (delete listening socket, but keep existing sessions active)
! 189: XXX lock (maybe)
! 190: XXX watch in/out traffic (pre/post crypto)
! 191: XXX inject packet (what about replies)
! 192: XXX server->client error/warning notifications
! 193: XXX port0 rfwd (need custom response message)
! 194: XXX send signals via mux
! 195:
! 196: $OpenBSD$
![[BACK]](/icons/back.gif){kind=icon}
Return to PROTOCOL.mux CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / ssh