upstream commit
Better desciption of Unix domain socket forwarding.
bz#2423; ok jmc@
Upstream-ID: 85e28874726897e3f26ae50dfa2e8d2de683805d
diff --git a/ssh.1 b/ssh.1
index fa87c27..85a2d87 100644
--- a/ssh.1
+++ b/ssh.1
@@ -33,8 +33,8 @@
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
-.\" $OpenBSD: ssh.1,v 1.359 2015/07/10 06:21:53 markus Exp $
-.Dd $Mdocdate: July 10 2015 $
+.\" $OpenBSD: ssh.1,v 1.360 2015/07/20 15:39:52 millert Exp $
+.Dd $Mdocdate: July 20 2015 $
.Dt SSH 1
.Os
.Sh NAME
@@ -52,14 +52,14 @@
.Op Fl F Ar configfile
.Op Fl I Ar pkcs11
.Op Fl i Ar identity_file
-.Op Fl L Oo Ar bind_address : Oc Ns Ar port : Ns Ar host : Ns Ar hostport
+.Op Fl L Ar address
.Op Fl l Ar login_name
.Op Fl m Ar mac_spec
.Op Fl O Ar ctl_cmd
.Op Fl o Ar option
.Op Fl p Ar port
.Op Fl Q Cm cipher | cipher-auth | mac | kex | key | protocol-version
-.Op Fl R Oo Ar bind_address : Oc Ns Ar port : Ns Ar host : Ns Ar hostport
+.Op Fl R Ar address
.Op Fl S Ar ctl_path
.Op Fl W Ar host : Ns Ar port
.Op Fl w Ar local_tun Ns Op : Ns Ar remote_tun
@@ -93,23 +93,28 @@
it is executed on the remote host instead of a login shell.
.Pp
The options are as follows:
-.Bl -tag -width Ds
+.Bl -tag -width Ds -compact
+.Pp
.It Fl 1
Forces
.Nm
to try protocol version 1 only.
+.Pp
.It Fl 2
Forces
.Nm
to try protocol version 2 only.
+.Pp
.It Fl 4
Forces
.Nm
to use IPv4 addresses only.
+.Pp
.It Fl 6
Forces
.Nm
to use IPv6 addresses only.
+.Pp
.It Fl A
Enables forwarding of the authentication agent connection.
This can also be specified on a per-host basis in a configuration file.
@@ -122,14 +127,17 @@
An attacker cannot obtain key material from the agent,
however they can perform operations on the keys that enable them to
authenticate using the identities loaded into the agent.
+.Pp
.It Fl a
Disables forwarding of the authentication agent connection.
+.Pp
.It Fl b Ar bind_address
Use
.Ar bind_address
on the local machine as the source address
of the connection.
Only useful on systems with more than one address.
+.Pp
.It Fl C
Requests compression of all data (including stdin, stdout, stderr, and
data for forwarded X11, TCP and
@@ -148,6 +156,7 @@
configuration files; see the
.Cm Compression
option.
+.Pp
.It Fl c Ar cipher_spec
Selects the cipher specification for encrypting the session.
.Pp
@@ -166,6 +175,7 @@
keyword in
.Xr ssh_config 5
for more information.
+.Pp
.It Fl D Xo
.Sm off
.Oo Ar bind_address : Oc
@@ -205,10 +215,12 @@
empty address or
.Sq *
indicates that the port should be available from all interfaces.
+.Pp
.It Fl E Ar log_file
Append debug logs to
.Ar log_file
instead of standard error.
+.Pp
.It Fl e Ar escape_char
Sets the escape character for sessions with a pty (default:
.Ql ~ ) .
@@ -221,6 +233,7 @@
Setting the character to
.Dq none
disables any escapes and makes the session fully transparent.
+.Pp
.It Fl F Ar configfile
Specifies an alternative per-user configuration file.
If a configuration file is given on the command line,
@@ -229,6 +242,7 @@
will be ignored.
The default for the per-user configuration file is
.Pa ~/.ssh/config .
+.Pp
.It Fl f
Requests
.Nm
@@ -251,6 +265,7 @@
.Fl f
will wait for all remote port forwards to be successfully established
before placing itself in the background.
+.Pp
.It Fl G
Causes
.Nm
@@ -259,15 +274,18 @@
and
.Cm Match
blocks and exit.
+.Pp
.It Fl g
Allows remote hosts to connect to local forwarded ports.
If used on a multiplexed connection, then this option must be specified
on the master process.
+.Pp
.It Fl I Ar pkcs11
Specify the PKCS#11 shared library
.Nm
should use to communicate with a PKCS#11 token providing the user's
private RSA key.
+.Pp
.It Fl i Ar identity_file
Selects a file from which the identity (private key) for
public key authentication is read.
@@ -291,33 +309,58 @@
by appending
.Pa -cert.pub
to identity filenames.
+.Pp
.It Fl K
Enables GSSAPI-based authentication and forwarding (delegation) of GSSAPI
credentials to the server.
+.Pp
.It Fl k
Disables forwarding (delegation) of GSSAPI credentials to the server.
+.Pp
.It Fl L Xo
.Sm off
.Oo Ar bind_address : Oc
.Ar port : host : hostport
.Sm on
.Xc
-Specifies that the given port on the local (client) host is to be
-forwarded to the given host and port on the remote side.
-This works by allocating a socket to listen to
+.It Fl L Xo
+.Sm off
+.Oo Ar bind_address : Oc
+.Ar port : remote_socket
+.Sm on
+.Xc
+.It Fl L Xo
+.Sm off
+.Ar local_socket : host : hostport
+.Sm on
+.Xc
+.It Fl L Xo
+.Sm off
+.Ar local_socket : remote_socket
+.Sm on
+.Xc
+Specifies that connections to the given TCP port or Unix socket on the local
+(client) host are to be forwarded to the given host and port, or Unix socket,
+on the remote side.
+This works by allocating a socket to listen to either a TCP
.Ar port
on the local side, optionally bound to the specified
-.Ar bind_address .
-Whenever a connection is made to this port, the
+.Ar bind_address ,
+or to a Unix socket.
+Whenever a connection is made to the local port or socket, the
connection is forwarded over the secure channel, and a connection is
-made to
+made to either
.Ar host
port
-.Ar hostport
+.Ar hostport ,
+or the Unix socket
+.Ar remote_socket ,
from the remote machine.
+.Pp
Port forwardings can also be specified in the configuration file.
-IPv6 addresses can be specified by enclosing the address in square brackets.
Only the superuser can forward privileged ports.
+IPv6 addresses can be specified by enclosing the address in square brackets.
+.Pp
By default, the local port is bound in accordance with the
.Cm GatewayPorts
setting.
@@ -332,9 +375,11 @@
empty address or
.Sq *
indicates that the port should be available from all interfaces.
+.Pp
.It Fl l Ar login_name
Specifies the user to log in as on the remote machine.
This also may be specified on a per-host basis in the configuration file.
+.Pp
.It Fl M
Places the
.Nm
@@ -353,6 +398,7 @@
in
.Xr ssh_config 5
for details.
+.Pp
.It Fl m Ar mac_spec
Additionally, for protocol version 2 a comma-separated list of MAC
(message authentication code) algorithms can
@@ -360,10 +406,12 @@
See the
.Cm MACs
keyword for more information.
+.Pp
.It Fl N
Do not execute a remote command.
This is useful for just forwarding ports
(protocol version 2 only).
+.Pp
.It Fl n
Redirects stdin from
.Pa /dev/null
@@ -384,6 +432,7 @@
needs to ask for a password or passphrase; see also the
.Fl f
option.)
+.Pp
.It Fl O Ar ctl_cmd
Control an active connection multiplexing master process.
When the
@@ -402,6 +451,7 @@
(request the master to exit), and
.Dq stop
(request the master to stop accepting further multiplexing requests).
+.Pp
.It Fl o Ar option
Can be used to give options in the format used in the configuration file.
This is useful for specifying options for which there is no separate
@@ -494,10 +544,12 @@
.It VisualHostKey
.It XAuthLocation
.El
+.Pp
.It Fl p Ar port
Port to connect to on the remote host.
This can be specified on a
per-host basis in the configuration file.
+.Pp
.It Fl Q Cm cipher | cipher-auth | mac | kex | key | protocol-version
Queries
.Nm
@@ -515,25 +567,47 @@
(key types) and
.Ar protocol-version
(supported SSH protocol versions).
+.Pp
.It Fl q
Quiet mode.
Causes most warning and diagnostic messages to be suppressed.
+.Pp
.It Fl R Xo
.Sm off
.Oo Ar bind_address : Oc
.Ar port : host : hostport
.Sm on
.Xc
-Specifies that the given port on the remote (server) host is to be
-forwarded to the given host and port on the local side.
-This works by allocating a socket to listen to
+.It Fl R Xo
+.Sm off
+.Oo Ar bind_address : Oc
+.Ar port : local_socket
+.Sm on
+.Xc
+.It Fl R Xo
+.Sm off
+.Ar remote_socket : host : hostport
+.Sm on
+.Xc
+.It Fl R Xo
+.Sm off
+.Ar remote_socket : local_socket
+.Sm on
+.Xc
+Specifies that connections to the given TCP port or Unix socket on the remote
+(server) host are to be forwarded to the given host and port, or Unix socket,
+on the local side.
+This works by allocating a socket to listen to either a TCP
.Ar port
-on the remote side, and whenever a connection is made to this port, the
-connection is forwarded over the secure channel, and a connection is
-made to
+or to a Unix socket on the remote side.
+Whenever a connection is made to this port or Unix socket, the
+connection is forwarded over the secure channel, and a connection
+is made to either
.Ar host
port
-.Ar hostport
+.Ar hostport ,
+or
+.Ar local_socket ,
from the local machine.
.Pp
Port forwardings can also be specified in the configuration file.
@@ -541,7 +615,7 @@
logging in as root on the remote machine.
IPv6 addresses can be specified by enclosing the address in square brackets.
.Pp
-By default, the listening socket on the server will be bound to the loopback
+By default, TCP listening sockets on the server will be bound to the loopback
interface only.
This may be overridden by specifying a
.Ar bind_address .
@@ -566,6 +640,7 @@
When used together with
.Ic -O forward
the allocated port will be printed to the standard output.
+.Pp
.It Fl S Ar ctl_path
Specifies the location of a control socket for connection sharing,
or the string
@@ -578,14 +653,17 @@
in
.Xr ssh_config 5
for details.
+.Pp
.It Fl s
May be used to request invocation of a subsystem on the remote system.
Subsystems are a feature of the SSH2 protocol which facilitate the use
of SSH as a secure transport for other applications (eg.\&
.Xr sftp 1 ) .
The subsystem is specified as the remote command.
+.Pp
.It Fl T
Disable pseudo-terminal allocation.
+.Pp
.It Fl t
Force pseudo-terminal allocation.
This can be used to execute arbitrary
@@ -596,8 +674,10 @@
options force tty allocation, even if
.Nm
has no local tty.
+.Pp
.It Fl V
Display the version number and exit.
+.Pp
.It Fl v
Verbose mode.
Causes
@@ -609,6 +689,7 @@
.Fl v
options increase the verbosity.
The maximum is 3.
+.Pp
.It Fl W Ar host : Ns Ar port
Requests that standard input and output on the client be forwarded to
.Ar host
@@ -622,6 +703,7 @@
and
.Cm ClearAllForwardings .
Works with Protocol version 2 only.
+.Pp
.It Fl w Xo
.Ar local_tun Ns Op : Ns Ar remote_tun
.Xc
@@ -651,6 +733,7 @@
.Cm Tunnel
directive is unset, it is set to the default tunnel mode, which is
.Dq point-to-point .
+.Pp
.It Fl X
Enables X11 forwarding.
This can also be specified on a per-host basis in a configuration file.
@@ -671,12 +754,15 @@
directive in
.Xr ssh_config 5
for more information.
+.Pp
.It Fl x
Disables X11 forwarding.
+.Pp
.It Fl Y
Enables trusted X11 forwarding.
Trusted X11 forwardings are not subjected to the X11 SECURITY extension
controls.
+.Pp
.It Fl y
Send log information using the
.Xr syslog 3