.\" (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.205 2005/03/07 23:41:54 jmc Exp $
.Dd September 25, 1999
.Dt SSH 1
.Os
.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
.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
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
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.
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
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).
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
configuration files; see the
.Cm Compression
option.
-.It Fl c Ar blowfish | 3des | des
-Selects the cipher to use for encrypting the session.
-.Ar 3des
-is used by default.
-It is believed to be secure.
+.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
(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 .
.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
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
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
.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
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
.It Compression
.It CompressionLevel
.It ConnectionAttempts
-.It ConnectionTimeout
+.It ConnectTimeout
+.It ControlMaster
+.It ControlPath
.It DynamicForward
.It EscapeChar
.It ForwardAgent
.It GlobalKnownHostsFile
.It GSSAPIAuthentication
.It GSSAPIDelegateCredentials
+.It HashKnownHosts
.It Host
.It HostbasedAuthentication
.It HostKeyAlgorithms
.It HostName
.It IdentityFile
.It IdentitiesOnly
+.It KbdInteractiveDevices
.It LocalForward
.It LogLevel
.It MACs
.It RemoteForward
.It RhostsRSAAuthentication
.It RSAAuthentication
+.It SendEnv
.It ServerAliveInterval
.It ServerAliveCountMax
.It SmartcardDevice
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
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
(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
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
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
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
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
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
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
andersk / gssapi-openssh.git / blobdiff