===================================================================
RCS file: /cvsrepo/anoncvs/cvs/src/usr.bin/ssh/ssh.1,v
retrieving revision 1.182
retrieving revision 1.182.2.2
diff -u -r1.182 -r1.182.2.2
--- src/usr.bin/ssh/ssh.1	2004/03/05 10:53:58	1.182
+++ src/usr.bin/ssh/ssh.1	2005/03/10 17:15:05	1.182.2.2
@@ -34,7 +34,7 @@
 .\" (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.182 2004/03/05 10:53:58 markus Exp $
+.\" $OpenBSD: ssh.1,v 1.182.2.2 2005/03/10 17:15:05 brad Exp $
 .Dd September 25, 1999
 .Dt SSH 1
 .Os
@@ -43,39 +43,35 @@
 .Nd OpenSSH SSH client (remote login program)
 .Sh SYNOPSIS
 .Nm ssh
-.Op Fl 1246AaCfgkNnqsTtVvXxY
+.Bk -words
+.Op Fl 1246AaCfgkMNnqsTtVvXxY
 .Op Fl b Ar bind_address
 .Op Fl c Ar cipher_spec
 .Op Fl D Ar port
 .Op Fl e Ar escape_char
 .Op Fl F Ar configfile
 .Op Fl i Ar identity_file
-.Bk -words
-.Oo Fl L Xo
+.Oo Fl L\ \&
 .Sm off
-.Ar port :
-.Ar host :
-.Ar hostport
+.Oo Ar bind_address : Oc
+.Ar port : host : hostport
 .Sm on
-.Xc
 .Oc
-.Ek
 .Op Fl l Ar login_name
 .Op Fl m Ar mac_spec
+.Op Fl O Ar ctl_cmd
 .Op Fl o Ar option
-.Bk -words
 .Op Fl p Ar port
-.Ek
-.Oo Fl R Xo
+.Oo Fl R\ \&
 .Sm off
-.Ar port :
-.Ar host :
-.Ar hostport
+.Oo Ar bind_address : Oc
+.Ar port : host : hostport
 .Sm on
-.Xc
 .Oc
+.Op Fl S Ar ctl_path
 .Oo Ar user Ns @ Oc Ns Ar hostname
 .Op Ar command
+.Ek
 .Sh DESCRIPTION
 .Nm
 (SSH client) is a program for logging into a remote machine and for
@@ -102,35 +98,25 @@
 .Ar command
 is executed on the remote host instead of a login shell.
 .Ss SSH protocol version 1
-First, if the machine the user logs in from is listed in
+The first authentication method is the
+.Em rhosts
+or
+.Em hosts.equiv
+method combined with RSA-based host authentication.
+If the machine the user logs in from is listed in
 .Pa /etc/hosts.equiv
 or
 .Pa /etc/shosts.equiv
 on the remote machine, and the user names are
-the same on both sides, the user is immediately permitted to log in.
-Second, if
-.Pa .rhosts
+the same on both sides, or if the files
+.Pa $HOME/.rhosts
 or
-.Pa .shosts
-exists in the user's home directory on the
-remote machine and contains a line containing the name of the client
+.Pa $HOME/.shosts
+exist in the user's home directory on the
+remote machine and contain a line containing the name of the client
 machine and the name of the user on that machine, the user is
-permitted to log in.
-This form of authentication alone is normally not
-allowed by the server because it is not secure.
-.Pp
-The second authentication method is the
-.Em rhosts
-or
-.Em hosts.equiv
-method combined with RSA-based host authentication.
-It means that if the login would be permitted by
-.Pa $HOME/.rhosts ,
-.Pa $HOME/.shosts ,
-.Pa /etc/hosts.equiv ,
-or
-.Pa /etc/shosts.equiv ,
-and if additionally the server can verify the client's
+considered for log in.
+Additionally, if the server can verify the client's
 host key (see
 .Pa /etc/ssh/ssh_known_hosts
 and
@@ -146,7 +132,7 @@
 and the rlogin/rsh protocol in general, are inherently insecure and should be
 disabled if security is desired.]
 .Pp
-As a third authentication method,
+As a second authentication method,
 .Nm
 supports RSA based authentication.
 The scheme is based on public-key cryptography: there are cryptosystems
@@ -194,9 +180,6 @@
 file, and has one key
 per line, though the lines can be very long).
 After this, the user can log in without giving the password.
-RSA authentication is much more secure than
-.Em rhosts
-authentication.
 .Pp
 The most convenient way to use RSA authentication may be with an
 authentication agent.
@@ -241,8 +224,8 @@
 supports hostbased or challenge response authentication.
 .Pp
 Protocol 2 provides additional mechanisms for confidentiality
-(the traffic is encrypted using 3DES, Blowfish, CAST128 or Arcfour)
-and integrity (hmac-md5, hmac-sha1).
+(the traffic is encrypted using AES, 3DES, Blowfish, CAST128 or Arcfour)
+and integrity (hmac-md5, hmac-sha1, hmac-ripemd160).
 Note that protocol 1 lacks a strong mechanism for ensuring the
 integrity of the connection.
 .Ss Login session and remote execution
@@ -302,11 +285,18 @@
 Send a BREAK to the remote system
 (only useful for SSH protocol version 2 and if the peer supports it).
 .It Cm ~C
-Open command line (only useful for adding port forwardings using the
+Open command line.
+Currently this allows the addition of port forwardings using the
 .Fl L
 and
 .Fl R
-options).
+options (see below).
+It also allows the cancellation of existing remote port-forwardings
+using
+.Fl KR Ar hostport .
+Basic help is available, using the
+.Fl h
+option.
 .It Cm ~R
 Request rekeying of the connection
 (only useful for SSH protocol version 2 and if the peer supports it).
@@ -392,6 +382,15 @@
 option can be used to prevent logins to machines whose
 host key is not known or has changed.
 .Pp
+.Nm
+can be configured to verify host identification using fingerprint resource
+records (SSHFP) published in DNS.
+The
+.Cm VerifyHostKeyDNS
+option can be used to control how DNS lookups are performed.
+SSHFP resource records can be generated using
+.Xr ssh-keygen 1 .
+.Pp
 The options are as follows:
 .Bl -tag -width Ds
 .It Fl 1
@@ -442,13 +441,18 @@
 configuration files; see the
 .Cm Compression
 option.
-.It Fl c Ar blowfish | 3des | des
-Selects the cipher to use for encrypting the session.
+.It Fl c Ar cipher_spec
+Selects the cipher specification for encrypting the session.
+.Pp
+Protocol version 1 allows specification of a single cipher.
+The suported values are
+.Dq 3des ,
+.Dq blowfish
+and
+.Dq des .
 .Ar 3des
-is used by default.
-It is believed to be secure.
-.Ar 3des
 (triple-des) is an encrypt-decrypt-encrypt triple with three different keys.
+It is believed to be secure.
 .Ar blowfish
 is a fast block cipher; it appears very secure and is much faster than
 .Ar 3des .
@@ -460,12 +464,30 @@
 .Ar 3des
 cipher.
 Its use is strongly discouraged due to cryptographic weaknesses.
-.It Fl c Ar cipher_spec
-Additionally, for protocol version 2 a comma-separated list of ciphers can
-be specified in order of preference.
-See
-.Cm Ciphers
-for more information.
+The default is
+.Dq 3des .
+.Pp
+For protocol version 2
+.Ar cipher_spec
+is a comma-separated list of ciphers
+listed in order of preference.
+The supported ciphers are
+.Dq 3des-cbc ,
+.Dq aes128-cbc ,
+.Dq aes192-cbc ,
+.Dq aes256-cbc ,
+.Dq aes128-ctr ,
+.Dq aes192-ctr ,
+.Dq aes256-ctr ,
+.Dq arcfour ,
+.Dq blowfish-cbc ,
+and
+.Dq cast128-cbc .
+The default is
+.Bd -literal
+  ``aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour,
+    aes192-cbc,aes256-cbc''
+.Ed
 .It Fl D Ar port
 Specifies a local
 .Dq dynamic
@@ -542,6 +564,7 @@
 Disables forwarding (delegation) of GSSAPI credentials to the server.
 .It Fl L Xo
 .Sm off
+.Oo Ar bind_address : Oc
 .Ar port : host : hostport
 .Sm on
 .Xc
@@ -549,7 +572,9 @@
 forwarded to the given host and port on the remote side.
 This works by allocating a socket to listen to
 .Ar port
-on the local side, and whenever a connection is made to this port, the
+on the local side, optionally bound to the specified
+.Ar bind_address .
+Whenever a connection is made to this port, the
 connection is forwarded over the secure channel, and a connection is
 made to
 .Ar host
@@ -557,17 +582,44 @@
 .Ar hostport
 from the remote machine.
 Port forwardings can also be specified in the configuration file.
-Only root can forward privileged ports.
 IPv6 addresses can be specified with an alternative syntax:
 .Sm off
 .Xo
+.Op Ar bind_address No /
 .Ar port No / Ar host No /
-.Ar hostport .
+.Ar hostport
 .Xc
 .Sm on
+or by enclosing the address in square brackets.
+Only the superuser can forward privileged ports.
+By default, the local port is bound in accordance with the
+.Cm GatewayPorts
+setting.
+However, an explicit
+.Ar bind_address
+may be used to bind the connection to a specific address.
+The
+.Ar bind_address
+of
+.Dq localhost
+indicates that the listening port be bound for local use only, while an
+empty address or
+.Sq *
+indicates that the port should be available from all interfaces.
 .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.
+.It Fl M
+Places the
+.Nm
+client into
+.Dq master
+mode for connection sharing.
+Refer to the description of
+.Cm ControlMaster
+in
+.Xr ssh_config 5
+for details.
 .It Fl m Ar mac_spec
 Additionally, for protocol version 2 a comma-separated list of MAC
 (message authentication code) algorithms can
@@ -599,6 +651,18 @@
 needs to ask for a password or passphrase; see also the
 .Fl f
 option.)
+.It Fl O Ar ctl_cmd
+Control an active connection multiplexing master process.
+When the
+.Fl O
+option is specified, the
+.Ar ctl_cmd
+argument is interpreted and passed to the master process.
+Valid commands are:
+.Dq check
+(check that the master process is running) and
+.Dq exit
+(request the master to exit).
 .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
@@ -618,7 +682,9 @@
 .It Compression
 .It CompressionLevel
 .It ConnectionAttempts
-.It ConnectionTimeout
+.It ConnectTimeout
+.It ControlMaster
+.It ControlPath
 .It DynamicForward
 .It EscapeChar
 .It ForwardAgent
@@ -628,6 +694,7 @@
 .It GlobalKnownHostsFile
 .It GSSAPIAuthentication
 .It GSSAPIDelegateCredentials
+.It HashKnownHosts
 .It Host
 .It HostbasedAuthentication
 .It HostKeyAlgorithms
@@ -635,6 +702,7 @@
 .It HostName
 .It IdentityFile
 .It IdentitiesOnly
+.It KbdInteractiveDevices
 .It LocalForward
 .It LogLevel
 .It MACs
@@ -649,6 +717,7 @@
 .It RemoteForward
 .It RhostsRSAAuthentication
 .It RSAAuthentication
+.It SendEnv
 .It ServerAliveInterval
 .It ServerAliveCountMax
 .It SmartcardDevice
@@ -669,6 +738,7 @@
 Causes all warning and diagnostic messages to be suppressed.
 .It Fl R Xo
 .Sm off
+.Oo Ar bind_address : Oc
 .Ar port : host : hostport
 .Sm on
 .Xc
@@ -683,16 +753,44 @@
 port
 .Ar hostport
 from the local machine.
+.Pp
 Port forwardings can also be specified in the configuration file.
 Privileged ports can be forwarded only when
 logging in as root on the remote machine.
-IPv6 addresses can be specified with an alternative syntax:
+IPv6 addresses can be specified by enclosing the address in square braces or
+using an alternative syntax:
 .Sm off
 .Xo
-.Ar port No / Ar host No /
-.Ar hostport .
-.Xc
+.Op Ar bind_address No /
+.Ar host No / Ar port No /
+.Ar hostport
+.Xc .
 .Sm on
+.Pp
+By default, the listening socket on the server will be bound to the loopback
+interface only.
+This may be overriden by specifying a
+.Ar bind_address .
+An empty
+.Ar bind_address ,
+or the address
+.Ql * ,
+indicates that the remote socket should listen on all interfaces.
+Specifying a remote
+.Ar bind_address
+will only succeed if the server's
+.Cm GatewayPorts
+option is enabled (see
+.Xr sshd_config 5 ) .
+.It Fl S Ar ctl_path
+Specifies the location of a control socket for connection sharing.
+Refer to the description of
+.Cm ControlPath
+and
+.Cm ControlMaster
+in
+.Xr ssh_config 5
+for details.
 .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
@@ -733,10 +831,23 @@
 (for the user's X authorization database)
 can access the local X11 display through the forwarded connection.
 An attacker may then be able to perform activities such as keystroke monitoring.
+.Pp
+For this reason, X11 forwarding is subjected to X11 SECURITY extension
+restrictions by default.
+Please refer to the
+.Nm
+.Fl Y
+option and the
+.Cm ForwardX11Trusted
+directive in
+.Xr ssh_config 5
+for more information.
 .It Fl x
 Disables X11 forwarding.
 .It Fl Y
 Enables trusted X11 forwarding.
+Trusted X11 forwardings are not subjected to the X11 SECURITY extension
+controls.
 .El
 .Sh CONFIGURATION FILES
 .Nm
@@ -796,7 +907,7 @@
 This is particularly useful when calling
 .Nm
 from a
-.Pa .Xsession
+.Pa .xsession
 or related script.
 (Note that on some machines it
 may be necessary to redirect the input from
@@ -885,6 +996,8 @@
 This is the per-user configuration file.
 The file format and configuration options are described in
 .Xr ssh_config 5 .
+Because of the potential for abuse, this file must have strict permissions:
+read/write for the user, and not accessible by others.
 .It Pa $HOME/.ssh/authorized_keys
 Lists the public keys (RSA/DSA) that can be used for logging in as this user.
 The format of this file is described in the
@@ -947,7 +1060,9 @@
 is not setuid root.
 .It Pa $HOME/.rhosts
 This file is used in
-.Em rhosts
+.Cm RhostsRSAAuthentication
+and
+.Cm HostbasedAuthentication
 authentication to list the
 host/user pairs that are permitted to log in.
 (Note that this file is
@@ -966,12 +1081,10 @@
 permission for most machines is read/write for the user, and not
 accessible by others.
 .Pp
-Note that by default
+Note that
 .Xr sshd 8
-will be installed so that it requires successful RSA host
-authentication before permitting
-.Em rhosts
-authentication.
+allows authentication only in combination with client host key
+authentication before permitting log in.
 If the server machine does not have the client's host key in
 .Pa /etc/ssh/ssh_known_hosts ,
 it can be stored in
@@ -984,15 +1097,19 @@
 This file is used exactly the same way as
 .Pa .rhosts .
 The purpose for
-having this file is to be able to use rhosts authentication with
-.Nm
-without permitting login with
+having this file is to be able to use
+.Cm RhostsRSAAuthentication
+and
+.Cm HostbasedAuthentication
+authentication without permitting login with
 .Xr rlogin
 or
 .Xr rsh 1 .
 .It Pa /etc/hosts.equiv
 This file is used during
-.Em rhosts
+.Cm RhostsRSAAuthentication
+and
+.Cm HostbasedAuthentication
 authentication.
 It contains
 canonical hosts names, one per line (the full format is described in the
@@ -1001,8 +1118,7 @@
 If the client host is found in this file, login is
 automatically permitted provided client and server user names are the
 same.
-Additionally, successful RSA host authentication is normally
-required.
+Additionally, successful client host key authentication is required.
 This file should only be writable by root.
 .It Pa /etc/shosts.equiv
 This file is processed exactly as