.\" (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.223 2005/12/20 22:02:50 jmc Exp $
+.\" $OpenBSD: ssh.1,v 1.249 2006/01/15 17:37:05 jmc Exp $
.Dd September 25, 1999
.Dt SSH 1
.Os
It is intended to replace rlogin and rsh,
and provide secure encrypted communications between
two untrusted hosts over an insecure network.
-X11 connections and arbitrary TCP/IP ports
+X11 connections and arbitrary TCP ports
can also be forwarded over the secure channel.
.Pp
.Nm
Only useful on systems with more than one address.
.It Fl C
Requests compression of all data (including stdin, stdout, stderr, and
-data for forwarded X11 and TCP/IP connections).
+data for forwarded X11 and TCP connections).
The compression algorithm is the same used by
.Xr gzip 1 ,
and the
The default is
.Dq 3des .
.Pp
-For protocol version 2
+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 arcfour128 ,
-.Dq arcfour256 ,
-.Dq arcfour ,
-.Dq blowfish-cbc ,
+The supported ciphers are:
+3des-cbc,
+aes128-cbc,
+aes192-cbc,
+aes256-cbc,
+aes128-ctr,
+aes192-ctr,
+aes256-ctr,
+arcfour128,
+arcfour256,
+arcfour,
+blowfish-cbc,
and
-.Dq cast128-cbc .
+cast128-cbc.
The default is:
.Bd -literal -offset indent
aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour128,
empty address or
.Sq *
indicates that the port should be available from all interfaces.
-.It Fl e Ar ch | ^ch | none
+.It Fl e Ar escape_char
Sets the escape character for sessions with a pty (default:
.Ql ~ ) .
The escape character is only recognized at the beginning of a line.
.It Fl g
Allows remote hosts to connect to local forwarded ports.
.It Fl I Ar smartcard_device
-Specifies which smartcard device to use.
-The argument is the device
+Specify the device
.Nm
should use to communicate with a smartcard used for storing the user's
private RSA key.
+This option is only available if support for smartcard devices
+is compiled in (default is no support).
.It Fl i Ar identity_file
Selects a file from which the identity (private key) for
RSA or DSA authentication is read.
client into
.Dq master
mode for connection sharing.
+Multiple
+.Fl M
+options places
+.Nm
+into
+.Dq master
+mode with confirmation required before slave connections are accepted.
Refer to the description of
.Cm ControlMaster
in
.It Fl w Ar tunnel : Ns Ar tunnel
Requests a
.Xr tun 4
-device on the client and server like the
+device on the client
+(first
+.Ar tunnel
+arg)
+and server
+(second
+.Ar tunnel
+arg).
+The devices may be specified by numerical ID or the keyword
+.Dq any ,
+which uses the next available tunnel device.
+See also the
.Cm Tunnel
directive in
.Xr ssh_config 5 .
Trusted X11 forwardings are not subjected to the X11 SECURITY extension
controls.
.El
+.Pp
+.Nm
+may additionally obtain configuration data from
+a per-user configuration file and a system-wide configuration file.
+The file format and configuration options are described in
+.Xr ssh_config 5 .
+.Pp
+.Nm
+exits with the exit status of the remote command or with 255
+if an error occurred.
.Sh AUTHENTICATION
-The OpenSSH SSH client supports OpenSSH protocols 1 and 2.
+The OpenSSH SSH client supports SSH protocols 1 and 2.
Protocol 2 is the default, with
.Nm
falling back to protocol 1 if it detects protocol 2 is unsupported.
The password is sent to the remote
host for checking; however, since all communications are encrypted,
the password cannot be seen by someone listening on the network.
-.Sh LOGIN SESSION AND REMOTE EXECUTION
+.Pp
+.Nm
+automatically maintains and checks a database containing
+identification for all hosts it has ever been used with.
+Host keys are stored in
+.Pa ~/.ssh/known_hosts
+in the user's home directory.
+Additionally, the file
+.Pa /etc/ssh/ssh_known_hosts
+is automatically checked for known hosts.
+Any new hosts are automatically added to the user's file.
+If a host's identification ever changes,
+.Nm
+warns about this and disables password authentication to prevent
+server spoofing or man-in-the-middle attacks,
+which could otherwise be used to circumvent the encryption.
+The
+.Cm StrictHostKeyChecking
+option can be used to control 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
When the user's identity has been accepted by the server, the server
either executes the given command, or logs into the machine and gives
the user a normal shell on the remote machine.
will also make the session transparent even if a tty is used.
.Pp
The session terminates when the command or shell on the remote
-machine exits and all X11 and TCP/IP connections have been closed.
-The exit status of the remote program is returned as the exit status of
-.Nm ssh .
-.Pp
-.Nm
-may additionally obtain configuration data from
-a per-user configuration file and a system-wide configuration file.
-The file format and configuration options are described in
-.Xr ssh_config 5 .
+machine exits and all X11 and TCP connections have been closed.
.Sh ESCAPE CHARACTERS
When a pseudo-terminal has been requested,
.Nm
Disconnect.
.It Cm ~^Z
Background
-.Nm ssh .
+.Nm .
.It Cm ~#
List forwarded connections.
.It Cm ~&
.Fl L
and
.Fl R
-options (see below).
+options (see above).
It also allows the cancellation of existing remote port-forwardings
using
.Fl KR Ar hostport .
Request rekeying of the connection
(only useful for SSH protocol version 2 and if the peer supports it).
.El
-.Sh X11 AND TCP FORWARDING
+.Sh TCP FORWARDING
+Forwarding of arbitrary TCP connections over the secure channel can
+be specified either on the command line or in a configuration file.
+One possible application of TCP forwarding is a secure connection to a
+mail server; another is going through firewalls.
+.Pp
+In the example below, we look at encrypting communication between
+an IRC client and server, even though the IRC server does not directly
+support encrypted communications.
+This works as follows:
+the user connects to the remote host using
+.Nm ,
+specifying a port to be used to forward connections
+to the remote server.
+After that it is possible to start the service which is to be encrypted
+on the client machine,
+connecting to the same local port,
+and
+.Nm
+will encrypt and forward the connection.
+.Pp
+The following example tunnels an IRC session from client machine
+.Dq 127.0.0.1
+(localhost)
+to remote server
+.Dq server.example.com :
+.Bd -literal -offset 4n
+$ ssh -f -L 1234:localhost:6667 server.example.com sleep 10
+$ irc -c '#users' -p 1234 pinky 127.0.0.1
+.Ed
+.Pp
+This tunnels a connection to IRC server
+.Dq server.example.com ,
+joining channel
+.Dq #users ,
+nickname
+.Dq pinky ,
+using port 1234.
+It doesn't matter which port is used,
+as long as it's greater than 1023
+(remember, only root can open sockets on privileged ports)
+and doesn't conflict with any ports already in use.
+The connection is forwarded to port 6667 on the remote server,
+since that's the standard port for IRC services.
+.Pp
+The
+.Fl f
+option backgrounds
+.Nm
+and the remote command
+.Dq sleep 10
+is specified to allow an amount of time
+(10 seconds, in the example)
+to start the service which is to be tunnelled.
+If no connections are made within the time specified,
+.Nm
+will exit.
+.Sh X11 FORWARDING
If the
.Cm ForwardX11
variable is set to
.Dq yes
(or see the description of the
-.Fl X
+.Fl X ,
+.Fl x ,
and
-.Fl x
-options described later)
+.Fl Y
+options above)
and the user is using X11 (the
.Ev DISPLAY
environment variable is set), the connection to the X11 display is
.Fl A
and
.Fl a
-options described later) and
+options above) and
the user is using an authentication agent, the connection to the agent
is automatically forwarded to the remote side.
-.Pp
-Forwarding of arbitrary TCP/IP connections over the secure channel can
-be specified either on the command line or in a configuration file.
-One possible application of TCP/IP forwarding is a secure connection to an
-electronic purse; another is going through firewalls.
-.Sh SERVER AUTHENTICATION
-.Nm
-automatically maintains and checks a database containing
-identifications for all hosts it has ever been used with.
-Host keys are stored in
-.Pa ~/.ssh/known_hosts
-in the user's home directory.
-Additionally, the file
-.Pa /etc/ssh/ssh_known_hosts
-is automatically checked for known hosts.
-Any new hosts are automatically added to the user's file.
-If a host's identification ever changes,
-.Nm
-warns about this and disables password authentication to prevent a
-trojan horse from getting the user's password.
-Another purpose of this mechanism is to prevent man-in-the-middle attacks
-which could otherwise be used to circumvent the encryption.
-The
-.Cm StrictHostKeyChecking
-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 .
.Sh ENVIRONMENT
.Nm
will normally set the following environment variables:
-.Bl -tag -width LOGNAME
+.Bl -tag -width "SSH_ORIGINAL_COMMAND"
.It Ev DISPLAY
The
.Ev DISPLAY
It is automatically set by
.Nm
to point to a value of the form
-.Dq hostname:n
-where hostname indicates
-the host where the shell runs, and n is an integer \*(Ge 1.
+.Dq hostname:n ,
+where
+.Dq hostname
+indicates the host where the shell runs, and
+.Sq n
+is an integer \*(Ge 1.
.Nm
uses this special value to forward X11 connections over the secure
channel.
Set to the default
.Ev PATH ,
as specified when compiling
-.Nm ssh .
+.Nm .
.It Ev SSH_ASKPASS
If
.Nm
.Pa /dev/null
to make this work.)
.It Ev SSH_AUTH_SOCK
-Identifies the path of a unix-domain socket used to communicate with the
-agent.
+Identifies the path of a
+.Ux Ns -domain
+socket used to communicate with the agent.
.It Ev SSH_CONNECTION
Identifies the client and server ends of the connection.
The variable contains
-four space-separated values: client ip-address, client port number,
-server ip-address and server port number.
+four space-separated values: client IP address, client port number,
+server IP address, and server port number.
.It Ev SSH_ORIGINAL_COMMAND
-The variable contains the original command line if a forced command
+This variable contains the original command line if a forced command
is executed.
It can be used to extract the original arguments.
.It Ev SSH_TTY
.Pa ~/.ssh/environment ,
and adds lines of the format
.Dq VARNAME=value
-to the environment if the file exists and if users are allowed to
+to the environment if the file exists and users are allowed to
change their environment.
For more information, see the
.Cm PermitUserEnvironment
option in
.Xr sshd_config 5 .
.Sh FILES
-.Bl -tag -width Ds
-.It Pa ~/.ssh/known_hosts
-Records host keys for all hosts the user has logged into that are not
-in
-.Pa /etc/ssh/ssh_known_hosts .
-See
-.Xr sshd 8 .
-.It Pa ~/.ssh/identity, ~/.ssh/id_dsa, ~/.ssh/id_rsa
-Contains the authentication identity of the user.
-They are for protocol 1 RSA, protocol 2 DSA, and protocol 2 RSA, respectively.
+.Bl -tag -width Ds -compact
+.It ~/.rhosts
+This file is used for host-based authentication (see above).
+On some machines this file may need to be
+world-readable if the user's home directory is on an NFS partition,
+because
+.Xr sshd 8
+reads it as root.
+Additionally, this file must be owned by the user,
+and must not have write permissions for anyone else.
+The recommended
+permission for most machines is read/write for the user, and not
+accessible by others.
+.Pp
+.It ~/.shosts
+This file is used in exactly the same way as
+.Pa .rhosts ,
+but allows host-based authentication without permitting login with
+rlogin/rsh.
+.Pp
+.It ~/.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
+.Xr sshd 8
+manual page.
+This file is not highly sensitive, but the recommended
+permissions are read/write for the user, and not accessible by others.
+.Pp
+.It ~/.ssh/config
+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.
+.Pp
+.It ~/.ssh/environment
+Contains additional definitions for environment variables; see
+.Sx ENVIRONMENT ,
+above.
+.Pp
+.It ~/.ssh/identity
+.It ~/.ssh/id_dsa
+.It ~/.ssh/id_rsa
+Contains the private key for authentication.
These files
contain sensitive data and should be readable by the user but not
accessible by others (read/write/execute).
-Note that
.Nm
-ignores a private key file if it is accessible by others.
+will simply ignore a private key file if it is accessible by others.
It is possible to specify a passphrase when
-generating the key; the passphrase will be used to encrypt the
+generating the key which will be used to encrypt the
sensitive part of this file using 3DES.
-.It Pa ~/.ssh/identity.pub, ~/.ssh/id_dsa.pub, ~/.ssh/id_rsa.pub
-Contains the public key for authentication (public part of the
-identity file in human-readable form).
-The contents of the
-.Pa ~/.ssh/identity.pub
-file should be added to the file
-.Pa ~/.ssh/authorized_keys
-on all machines
-where the user wishes to log in using protocol version 1 RSA authentication.
-The contents of the
-.Pa ~/.ssh/id_dsa.pub
-and
-.Pa ~/.ssh/id_rsa.pub
-file should be added to
-.Pa ~/.ssh/authorized_keys
-on all machines
-where the user wishes to log in using protocol version 2 DSA/RSA authentication.
+.Pp
+.It ~/.ssh/identity.pub
+.It ~/.ssh/id_dsa.pub
+.It ~/.ssh/id_rsa.pub
+Contains the public key for authentication.
These files are not
sensitive and can (but need not) be readable by anyone.
-These files are
-never used automatically and are not necessary; they are only provided for
+They are
+never used automatically and are not necessary: they are only provided for
the convenience of the user.
-.It Pa ~/.ssh/config
-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 ~/.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
-.Xr sshd 8
-manual page.
-In the simplest form the format is the same as the
-.Pa .pub
-identity files.
-This file is not highly sensitive, but the recommended
-permissions are read/write for the user, and not accessible by others.
-.It Pa /etc/ssh/ssh_known_hosts
-Systemwide list of known host keys.
-This file should be prepared by the
-system administrator to contain the public host keys of all machines in the
-organization.
-This file should be world-readable.
-This file contains
-public keys, one per line, in the following format (fields separated
-by spaces): system name, public key and optional comment field.
-When different names are used
-for the same machine, all such names should be listed, separated by
-commas.
-The format is described in the
-.Xr sshd 8
-manual page.
.Pp
-The canonical system name (as returned by name servers) is used by
+.It ~/.ssh/known_hosts
+Contains a list of host keys for all hosts the user has logged into
+that are not already in the systemwide list of known host keys.
+See
.Xr sshd 8
-to verify the client host when logging in; other names are needed because
+for further details of the format of this file.
+.Pp
+.It ~/.ssh/rc
+Commands in this file are executed by
.Nm
-does not convert the user-supplied name to a canonical name before
-checking the key, because someone with access to the name servers
-would then be able to fool host authentication.
+when the user logs in, just before the user's shell (or command) is
+started.
+See the
+.Xr sshd 8
+manual page for more information.
+.Pp
+.It /etc/hosts.equiv
+This file is for host-based authentication (see above).
+It should only be writable by root.
+.Pp
+.It /etc/shosts.equiv
+This file is used in exactly the same way as
+.Pa hosts.equiv ,
+but allows host-based authentication without permitting login with
+rlogin/rsh.
+.Pp
.It Pa /etc/ssh/ssh_config
Systemwide configuration file.
The file format and configuration options are described in
.Xr ssh_config 5 .
-.It Pa /etc/ssh/ssh_host_key, /etc/ssh/ssh_host_dsa_key, /etc/ssh/ssh_host_rsa_key
+.Pp
+.It /etc/ssh/ssh_host_key
+.It /etc/ssh/ssh_host_dsa_key
+.It /etc/ssh/ssh_host_rsa_key
These three files contain the private parts of the host keys
-and are used for
-.Cm RhostsRSAAuthentication
-and
-.Cm HostbasedAuthentication .
-If the protocol version 1
-.Cm RhostsRSAAuthentication
-method is used,
+and are used for host-based authentication.
+If protocol version 1 is used,
.Nm
must be setuid root, since the host key is readable only by root.
For protocol version 2,
.Nm
uses
.Xr ssh-keysign 8
-to access the host keys for
-.Cm HostbasedAuthentication .
-This eliminates the requirement that
+to access the host keys,
+eliminating the requirement that
.Nm
-be setuid root when that authentication method is used.
+be setuid root when host-based authentication is used.
By default
.Nm
is not setuid root.
-.It Pa ~/.rhosts
-This file is used in
-.Cm RhostsRSAAuthentication
-and
-.Cm HostbasedAuthentication
-authentication to list the
-host/user pairs that are permitted to log in.
-(Note that this file is
-also used by rlogin and rsh, which makes using this file insecure.)
-Each line of the file contains a host name (in the canonical form
-returned by name servers), and then a user name on that host,
-separated by a space.
-On some machines this file may need to be
-world-readable if the user's home directory is on a NFS partition,
-because
-.Xr sshd 8
-reads it as root.
-Additionally, this file must be owned by the user,
-and must not have write permissions for anyone else.
-The recommended
-permission for most machines is read/write for the user, and not
-accessible by others.
.Pp
-Note that
-.Xr sshd 8
-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
-.Pa ~/.ssh/known_hosts .
-The easiest way to do this is to
-connect back to the client from the server machine using ssh; this
-will automatically add the host key to
-.Pa ~/.ssh/known_hosts .
-.It Pa ~/.shosts
-This file is used exactly the same way as
-.Pa .rhosts .
-The purpose for
-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
-.Cm RhostsRSAAuthentication
-and
-.Cm HostbasedAuthentication
-authentication.
-It contains
-canonical hosts names, one per line (the full format is described in the
-.Xr sshd 8
-manual page).
-If the client host is found in this file, login is
-automatically permitted provided client and server user names are the
-same.
-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
-.Pa /etc/hosts.equiv .
-This file may be useful to permit logins using
-.Nm
-but not using rsh/rlogin.
-.It Pa /etc/ssh/sshrc
-Commands in this file are executed by
-.Nm
-when the user logs in just before the user's shell (or command) is started.
-See the
+.It /etc/ssh/ssh_known_hosts
+Systemwide list of known host keys.
+This file should be prepared by the
+system administrator to contain the public host keys of all machines in the
+organization.
+It should be world-readable.
+See
.Xr sshd 8
-manual page for more information.
-.It Pa ~/.ssh/rc
+for further details of the format of this file.
+.Pp
+.It /etc/ssh/sshrc
Commands in this file are executed by
.Nm
-when the user logs in just before the user's shell (or command) is
-started.
+when the user logs in, just before the user's shell (or command) is started.
See the
.Xr sshd 8
manual page for more information.
-.It Pa ~/.ssh/environment
-Contains additional definitions for environment variables, see section
-.Sx ENVIRONMENT
-above.
.El
-.Sh DIAGNOSTICS
-.Nm
-exits with the exit status of the remote command or with 255
-if an error occurred.
.Sh SEE ALSO
-.Xr gzip 1 ,
-.Xr rsh 1 ,
.Xr scp 1 ,
.Xr sftp 1 ,
.Xr ssh-add 1 ,
.Xr ssh-agent 1 ,
.Xr ssh-keygen 1 ,
-.Xr telnet 1 ,
+.Xr ssh-keyscan 1 ,
.Xr hosts.equiv 5 ,
.Xr ssh_config 5 ,
.Xr ssh-keysign 8 ,
andersk / openssh.git / blobdiff