.\" -*- nroff -*-
.\"
-.\" ssh.1.in
-.\"
.\" Author: Tatu Ylonen <ylo@cs.hut.fi>
-.\"
.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
.\" All rights reserved
.\"
-.\" Created: Sat Apr 22 21:55:14 1995 ylo
+.\" As far as I am concerned, the code I have written for this software
+.\" can be used freely for any purpose. Any derived versions of this
+.\" software must be clearly marked as such, and if the derived work is
+.\" incompatible with the protocol description in the RFC file, it must be
+.\" called by a name other than "ssh" or "Secure Shell".
+.\"
+.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved.
+.\" Copyright (c) 1999 Aaron Campbell. All rights reserved.
+.\" Copyright (c) 1999 Theo de Raadt. All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
.\"
-.\" $Id$
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (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.94 2001/03/05 15:56:16 deraadt Exp $
.Dd September 25, 1999
.Dt SSH 1
.Os
.Op Ar command
.Pp
.Nm ssh
-.Op Fl afgknqtvxCPX246
-.Op Fl c Ar blowfish | 3des
+.Op Fl afgknqstvxACNPTX1246
+.Op Fl c Ar cipher_spec
.Op Fl e Ar escape_char
.Op Fl i Ar identity_file
.Op Fl l Ar login_name
+.Op Fl m Ar mac_spec
.Op Fl o Ar option
.Op Fl p Ar port
.Oo Fl L Xo
connects and logs into the specified
.Ar hostname .
The user must prove
-his/her identity to the remote machine using one of several methods.
+his/her identity to the remote machine using one of several methods
+depending on the protocol version used:
+.Pp
+.Ss SSH protocol version 1
.Pp
First, if the machine the user logs in from is listed in
.Pa /etc/hosts.equiv
.Pa hosts.equiv
method combined with RSA-based host authentication.
It means that if the login would be permitted by
-.Pa \&.rhosts ,
-.Pa \&.shosts ,
+.Pa $HOME/.rhosts ,
+.Pa $HOME/.shosts ,
.Pa /etc/hosts.equiv ,
or
.Pa /etc/shosts.equiv ,
spoofing, DNS spoofing and routing spoofing.
[Note to the administrator:
.Pa /etc/hosts.equiv ,
-.Pa \&.rhosts ,
+.Pa $HOME/.rhosts ,
and the rlogin/rsh protocol in general, are inherently insecure and should be
disabled if security is desired.]
.Pp
The user creates his/her RSA key pair by running
.Xr ssh-keygen 1 .
This stores the private key in
-.Pa \&.ssh/identity
+.Pa $HOME/.ssh/identity
and the public key in
-.Pa \&.ssh/identity.pub
+.Pa $HOME/.ssh/identity.pub
in the user's home directory.
The user should then copy the
.Pa identity.pub
to
-.Pa \&.ssh/authorized_keys
+.Pa $HOME/.ssh/authorized_keys
in his/her home directory on the remote machine (the
.Pa authorized_keys
file corresponds to the conventional
-.Pa \&.rhosts
+.Pa $HOME/.rhosts
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.
host for checking; however, since all communications are encrypted,
the password cannot be seen by someone listening on the network.
.Pp
+.Ss SSH protocol version 2
+.Pp
+When a user connects using the protocol version 2
+different authentication methods are available:
+At first, the client attempts to authenticate using the public key method.
+If this method fails password authentication is tried.
+.Pp
+The public key method is similar to RSA authentication described
+in the previous section except that the DSA or RSA algorithm is used
+instead.
+The client uses his private key
+.Pa $HOME/.ssh/id_dsa
+to sign the session identifier and sends the result to the server.
+The server checks whether the matching public key is listed in
+.Pa $HOME/.ssh/authorized_keys2
+and grants access if both the key is found and the signature is correct.
+The session identifier is derived from a shared Diffie-Hellman value
+and is only known to the client and the server.
+.Pp
+If public key authentication fails or is not available a password
+can be sent encrypted to the remote host for proving the user's identity.
+This protocol 2 implementation does not yet support Kerberos or
+S/Key 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).
+Note that protocol 1 lacks a strong mechanism for ensuring the
+integrity of the connection.
+.Pp
+.Ss Login session and remote execution
+.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.
.Dq none
will also make the session transparent even if a tty is used.
.Pp
-The session terminates when the command or shell in on the remote
-machine exists and all X11 and TCP/IP connections have been closed.
+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
+.Ss X11 and TCP forwarding
+.Pp
If the user is using X11 (the
.Ev DISPLAY
environment variable is set), the connection to the X11 display is
Forwarding of arbitrary TCP/IP connections over the secure channel can
be specified either on 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 trough firewalls.
+electronic purse; another is going through firewalls.
+.Pp
+.Ss Server authentication
.Pp
.Nm
-automatically maintains and checks a database containing RSA-based
+automatically maintains and checks a database containing
identifications for all hosts it has ever been used with.
-The database is stored in
-.Pa \&.ssh/known_hosts
+RSA host keys are stored in
+.Pa $HOME/.ssh/known_hosts
+and
+host keys used in the protocol version 2 are stored in
+.Pa $HOME/.ssh/known_hosts2
in the user's home directory.
-Additionally, the file
+Additionally, the files
.Pa /etc/ssh_known_hosts
-is automatically checked for known hosts.
+and
+.Pa /etc/ssh_known_hosts2
+are automatically checked for known hosts.
Any new hosts are automatically added to the user's file.
If a host's identification
ever changes,
.Cm StrictHostKeyChecking
option (see below) can be used to prevent logins to machines whose
host key is not known or has changed.
-.Sh OPTIONS
+.Pp
+The options are as follows:
.Bl -tag -width Ds
.It Fl a
Disables forwarding of the authentication agent connection.
-This may also be specified on a per-host basis in the configuration file.
+.It Fl A
+Enables forwarding of the authentication agent connection.
+This can also be specified on a per-host basis in a configuration file.
.It Fl c Ar blowfish|3des
Selects the cipher to use for encrypting the session.
.Ar 3des
(triple-des) is an encrypt-decrypt-encrypt triple with three different keys.
It is presumably more secure than the
.Ar des
-cipher which is no longer supported in ssh.
+cipher which is no longer fully supported in
+.Nm ssh .
.Ar blowfish
is a fast block cipher, it appears very secure and is much faster than
.Ar 3des .
+.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.
.It Fl e Ar ch|^ch|none
Sets the escape character for sessions with a pty (default:
.Ql ~ ) .
Allows remote hosts to connect to local forwarded ports.
.It Fl i Ar identity_file
Selects the file from which the identity (private key) for
-RSA authentication is read.
+RSA or DSA authentication is read.
Default is
-.Pa \&.ssh/identity
+.Pa $HOME/.ssh/identity
in the user's home directory.
Identity files may also be specified on
a per-host basis in the configuration file.
.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 Ar mac_spec
+Additionally, for protocol version 2 a comma-separated list of MAC
+(message authentication code) algorithms can
+be specified in order of preference.
+See the
+.Cm MACs
+keyword for more information.
.It Fl n
Redirects stdin from
.Pa /dev/null
needs to ask for a password or passphrase; see also the
.Fl f
option.)
+.It Fl N
+Do not execute a remote command.
+This is useful if you just want to forward ports
+(protocol version 2 only).
.It Fl o Ar option
Can be used to give options in the format used in the config file.
This is useful for specifying options for which there is no separate
Note that this option turns off
.Cm RhostsAuthentication
and
-.Cm RhostsRSAAuthentication .
+.Cm RhostsRSAAuthentication
+for older servers.
.It Fl q
Quiet mode.
Causes all warning and diagnostic messages to be suppressed.
Only fatal errors are displayed.
+.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 application (eg. sftp). The
+subsystem is specified as the remote command.
.It Fl t
Force pseudo-tty allocation.
This can be used to execute arbitrary
screen-based programs on a remote machine, which can be very useful,
e.g., when implementing menu services.
+Multiple
+.Fl t
+options force tty allocation, even if
+.Nm
+has no local tty.
+.It Fl T
+Disable pseudo-tty allocation.
.It Fl v
Verbose mode.
Causes
to print debugging messages about its progress.
This is helpful in
debugging connection, authentication, and configuration problems.
-The verbose mode is also used to display
-.Xr skey 1
-challenges, if the user entered "s/key" as password.
+Multiple
+.Fl v
+options increases the verbosity.
+Maximum is 3.
.It Fl x
Disables X11 forwarding.
-This can also be specified on a per-host basis in a configuration file.
.It Fl X
Enables X11 forwarding.
+This can also be specified on a per-host basis in a configuration file.
.It Fl C
Requests compression of all data (including stdin, stdout, stderr, and
data for forwarded X11 and TCP/IP connections).
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.
+.It Fl 1
+Forces
+.Nm
+to try protocol version 1 only.
.It Fl 2
Forces
.Nm
-to use protocol version 2 only.
+to try protocol version 2 only.
.It Fl 4
Forces
.Nm
.Dq no ,
the check will not be executed.
.It Cm Cipher
-Specifies the cipher to use for encrypting the session.
+Specifies the cipher to use for encrypting the session
+in protocol version 1.
Currently,
-.Dq blowfish ,
+.Dq blowfish
and
.Dq 3des
are supported.
in order of preference.
Multiple ciphers must be comma-separated.
The default is
-.Dq blowfish-cbc,3des-cbc,arcfour,cast128-cbc .
+.Pp
+.Bd -literal
+ ``aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour,
+ aes192-cbc,aes256-cbc,rijndael128-cbc,rijndael192-cbc,
+ rijndael256-cbc,rijndael-cbc@lysator.liu.se''
+.Ed
.It Cm Compression
Specifies whether to use compression.
The argument must be
back to rsh or exiting.
The argument must be an integer.
This may be useful in scripts if the connection sometimes fails.
+.It Cm PubkeyAuthentication
+Specifies whether to try public key authentication.
+The argument to this keyword must be
+.Dq yes
+or
+.Dq no .
+Note that this option applies to protocol version 2 only.
.It Cm EscapeChar
Sets the escape character (default:
.Ql ~ ) .
.Dq yes
or
.Dq no .
+The default is
+.Dq no .
.It Cm ForwardX11
Specifies whether X11 connections will be automatically redirected
over the secure channel and
.It Cm GlobalKnownHostsFile
Specifies a file to use instead of
.Pa /etc/ssh_known_hosts .
+.It Cm HostKeyAlias
+Specifies an alias that should be used instead of the
+real host name when looking up or saving the host key
+in the known_hosts files.
+This option is useful for tunneling ssh connections
+or if you have multiple servers running on a single host.
.It Cm HostName
Specifies the real host name to log into.
This can be used to specify nicknames or abbreviations for hosts.
.It Cm IdentityFile
Specifies the file from which the user's RSA authentication identity
is read (default
-.Pa .ssh/identity
+.Pa $HOME/.ssh/identity
in the user's home directory).
Additionally, any identities represented by the authentication agent
will be used for authentication.
The possible values are:
QUIET, FATAL, ERROR, INFO, VERBOSE and DEBUG.
The default is INFO.
+.It Cm MACs
+Specifies the MAC (message authentication code) algorithms
+in order of preference.
+The MAC algorithm is used in protocol version 2
+for data integrity protection.
+Multiple algorithms must be comma-separated.
+The default is
+.Pp
+.Bd -literal
+ ``hmac-md5,hmac-sha1,hmac-ripemd160,hmac-ripemd160@openssh.com,
+ hmac-sha1-96,hmac-md5-96''
+.Ed
.It Cm NumberOfPasswordPrompts
Specifies the number of password prompts before giving up.
The argument to this keyword must be an integer.
.Dq yes
or
.Dq no .
+Note that this option applies to both protocol version 1 and 2.
.It Cm Port
Specifies the port number to connect on the remote host.
Default is 22.
.Dq 2 .
Multiple versions must be comma-separated.
The default is
-.Dq 1 .
+.Dq 1,2 .
+This means that
+.Nm
+tries version 1 and falls back to version 2
+if version 1 is not available.
.It Cm ProxyCommand
Specifies the command to use to connect to the server.
The command
RSA authentication will only be
attempted if the identity file exists, or an authentication agent is
running.
-.It Cm SkeyAuthentication
-Specifies whether to use
+Note that this option applies to protocol version 1 only.
+.It Cm ChallengeResponseAuthentication
+Specifies whether to use challenge response authentication.
+Currently there is only support for
.Xr skey 1
authentication.
The argument to this keyword must be
If this flag is set to
.Dq yes ,
.Nm
-ssh will never automatically add host keys to the
+will never automatically add host keys to the
.Pa $HOME/.ssh/known_hosts
-file, and refuses to connect hosts whose host key has changed.
+and
+.Pa $HOME/.ssh/known_hosts2
+files, and refuses to connect to hosts whose host key has changed.
This provides maximum protection against trojan horse attacks.
However, it can be somewhat annoying if you don't have good
.Pa /etc/ssh_known_hosts
+and
+.Pa /etc/ssh_known_hosts2
files installed and frequently
-connect new hosts.
-Basically this option forces the user to manually
-add any new hosts.
-Normally this option is disabled, and new hosts
-will automatically be added to the known host files.
+connect to new hosts.
+This option forces the user to manually
+add all new hosts.
+If this flag is set to
+.Dq no ,
+.Nm
+will automatically add new host keys to the
+user known hosts files.
+If this flag is set to
+.Dq ask ,
+new host keys
+will be added to the user known host files only after the user
+has confirmed that is what they really want to do, and
+.Nm
+will refuse to connect to hosts whose host key has changed.
The host keys of
-known hosts will be verified automatically in either case.
+known hosts will be verified automatically in all cases.
The argument must be
-.Dq yes
+.Dq yes ,
+.Dq no
or
-.Dq no .
+.Dq ask .
+The default is
+.Dq ask .
.It Cm UsePrivilegedPort
Specifies whether to use a privileged port for outgoing connections.
The argument must be
turns off
.Cm RhostsAuthentication
and
-.Cm RhostsRSAAuthentication .
+.Cm RhostsRSAAuthentication
+for older servers.
.It Cm User
Specifies the user to log in as.
This can be useful if you have a different user name on different machines.
.Dq yes
or
.Dq no .
+.It Cm XAuthLocation
+Specifies the location of the
+.Xr xauth 1
+program.
+The default is
+.Pa /usr/X11R6/bin/xauth .
+.El
.Sh ENVIRONMENT
.Nm
will normally set the following environment variables:
The variable contains
three space-separated values: client ip-address, client port number,
and server port number.
+.It Ev SSH_ORIGINAL_COMMAND
+The 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
This is set to the name of the tty (path to the device) associated
with the current shell or command.
this variable is not set.
.It Ev TZ
The timezone variable is set to indicate the present timezone if it
-was set when the daemon was started (e.i., the daemon passes the value
+was set when the daemon was started (i.e., the daemon passes the value
on to new connections).
.It Ev USER
Set to the name of the user logging in.
.Pa /etc/ssh_known_hosts ) .
See
.Xr sshd 8 .
-.It Pa $HOME/.ssh/identity
-Contains the RSA authentication identity of the user.
-This file
-contains sensitive data and should be readable by the user but not
+.It Pa $HOME/.ssh/identity, $HOME/.ssh/id_dsa
+Contains the RSA and the DSA authentication identity of the user.
+These files
+contain sensitive data and should be readable by the user but not
accessible by others (read/write/execute).
Note that
.Nm
-ignores this file if it is accessible by others.
+ignores 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
sensitive part of this file using 3DES.
-.It Pa $HOME/.ssh/identity.pub
+.It Pa $HOME/.ssh/identity.pub, $HOME/.ssh/id_dsa.pub
Contains the public key for authentication (public part of the
identity file in human-readable form).
-The contents of this file should be added to
+The contents of the
+.Pa $HOME/.ssh/identity.pub
+file should be added to
.Pa $HOME/.ssh/authorized_keys
on all machines
where you wish to log in using RSA authentication.
-This file is not
+The contents of the
+.Pa $HOME/.ssh/id_dsa.pub
+file should be added to
+.Pa $HOME/.ssh/authorized_keys2
+on all machines
+where you wish to log in using DSA authentication.
+These files are not
sensitive and can (but need not) be readable by anyone.
-This file is
-never used automatically and is not necessary; it is only provided for
+These files are
+never used automatically and are not necessary; they are only provided for
the convenience of the user.
.It Pa $HOME/.ssh/config
This is the per-user configuration file.
spaces).
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_known_hosts
+.It Pa $HOME/.ssh/authorized_keys2
+Lists the public keys (DSA/RSA) that can be used for logging in as this user.
+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_known_hosts, /etc/ssh_known_hosts2
Systemwide list of known host keys.
-This file should be prepared by the
+.Pa /etc/ssh_known_hosts
+contains RSA and
+.Pa /etc/ssh_known_hosts2
+contains DSA or RSA keys for protocol version 2.
+These files 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.
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.
-One some machines this file may need to be
+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
.Pa $HOME/.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 inxi
+will automatically add the host key to
.Pa $HOME/.ssh/known_hosts .
.It Pa $HOME/.shosts
This file is used exactly the same way as
.It Pa libcrypto.so.X.1
A version of this library which includes support for the RSA algorithm
is required for proper operation.
-.Sh AUTHOR
-OpenSSH
-is a derivative of the original (free) ssh 1.2.12 release by Tatu Ylonen,
-but with bugs removed and newer features re-added.
-Rapidly after the
-1.2.12 release, newer versions of the original ssh bore successively
-more restrictive licenses, and thus demand for a free version was born.
-This version of OpenSSH
-.Bl -bullet
-.It
-has all components of a restrictive nature (i.e., patents, see
-.Xr ssl 8 )
-directly removed from the source code; any licensed or patented components
-are chosen from
-external libraries.
-.It
-has been updated to support ssh protocol 1.5, making it compatible with
-all other ssh protocol 1 clients and servers.
-.It
-contains added support for
-.Xr kerberos 8
-authentication and ticket passing.
-.It
-supports one-time password authentication with
-.Xr skey 1 .
.El
-.Pp
-The libraries described in
-.Xr ssl 8
-are required for proper operation.
-.Pp
-OpenSSH has been created by Aaron Campbell, Bob Beck, Markus Friedl,
-Niels Provos, Theo de Raadt, and Dug Song.
+.Sh AUTHORS
+OpenSSH is a derivative of the original and free
+ssh 1.2.12 release by Tatu Ylonen.
+Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
+Theo de Raadt and Dug Song
+removed many bugs, re-added newer features and
+created OpenSSH.
+Markus Friedl contributed the support for SSH
+protocol versions 1.5 and 2.0.
.Sh SEE ALSO
.Xr rlogin 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 sshd 8 ,
-.Xr ssl 8
+.Xr sshd 8
andersk / openssh.git / blobdiff