version 1.39, 2000/03/04 07:07:05 |
version 1.40, 2000/03/11 21:40:03 |
|
|
.Sh DESCRIPTION |
.Sh DESCRIPTION |
.Nm |
.Nm |
(Secure Shell) is a program for logging into a remote machine and for |
(Secure Shell) is a program for logging into a remote machine and for |
executing commands on a remote machine. It is intended to replace |
executing commands on a remote machine. |
|
It is intended to replace |
rlogin and rsh, and provide secure encrypted communications between |
rlogin and rsh, and provide secure encrypted communications between |
two untrusted hosts over an insecure network. X11 connections and |
two untrusted hosts over an insecure network. |
|
X11 connections and |
arbitrary TCP/IP ports can also be forwarded over the secure channel. |
arbitrary TCP/IP ports can also be forwarded over the secure channel. |
.Pp |
.Pp |
.Nm |
.Nm |
|
|
exists in the user's home directory on the |
exists in the user's home directory on the |
remote machine and contains a line containing the name of the client |
remote machine and contains a line containing the name of the client |
machine and the name of the user on that machine, the user is |
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 |
permitted to log in. |
|
This form of authentication alone is normally not |
allowed by the server because it is not secure. |
allowed by the server because it is not secure. |
.Pp |
.Pp |
The second (and primary) authentication method is the |
The second (and primary) authentication method is the |
.Pa rhosts |
.Pa rhosts |
or |
or |
.Pa hosts.equiv |
.Pa hosts.equiv |
method combined with RSA-based host authentication. It |
method combined with RSA-based host authentication. |
means that if the login would be permitted by |
It means that if the login would be permitted by |
.Pa \&.rhosts , |
.Pa \&.rhosts , |
.Pa \&.shosts , |
.Pa \&.shosts , |
.Pa /etc/hosts.equiv , |
.Pa /etc/hosts.equiv , |
|
|
.Pa $HOME/.ssh/known_hosts |
.Pa $HOME/.ssh/known_hosts |
in the |
in the |
.Sx FILES |
.Sx FILES |
section), only then login is |
section), only then login is permitted. |
permitted. This authentication method closes security holes due to IP |
This authentication method closes security holes due to IP |
spoofing, DNS spoofing and routing spoofing. [Note to the |
spoofing, DNS spoofing and routing spoofing. |
administrator: |
[Note to the administrator: |
.Pa /etc/hosts.equiv , |
.Pa /etc/hosts.equiv , |
.Pa \&.rhosts , |
.Pa \&.rhosts , |
and the rlogin/rsh protocol in general, are inherently insecure and should be |
and the rlogin/rsh protocol in general, are inherently insecure and should be |
|
|
The scheme is based on public-key cryptography: there are cryptosystems |
The scheme is based on public-key cryptography: there are cryptosystems |
where encryption and decryption are done using separate keys, and it |
where encryption and decryption are done using separate keys, and it |
is not possible to derive the decryption key from the encryption key. |
is not possible to derive the decryption key from the encryption key. |
RSA is one such system. The idea is that each user creates a public/private |
RSA is one such system. |
key pair for authentication purposes. The |
The idea is that each user creates a public/private |
server knows the public key, and only the user knows the private key. |
key pair for authentication purposes. |
|
The server knows the public key, and only the user knows the private key. |
The file |
The file |
.Pa $HOME/.ssh/authorized_keys |
.Pa $HOME/.ssh/authorized_keys |
lists the public keys that are permitted for logging |
lists the public keys that are permitted for logging |
in. When the user logs in, the |
in. |
|
When the user logs in, the |
.Nm |
.Nm |
program tells the server which key pair it would like to use for |
program tells the server which key pair it would like to use for |
authentication. The server checks if this key is permitted, and if |
authentication. |
|
The server checks if this key is permitted, and if |
so, sends the user (actually the |
so, sends the user (actually the |
.Nm |
.Nm |
program running on behalf of the user) a challenge, a random number, |
program running on behalf of the user) a challenge, a random number, |
encrypted by the user's public key. The challenge can only be |
encrypted by the user's public key. |
decrypted using the proper private key. The user's client then decrypts the |
The challenge can only be |
|
decrypted using the proper private key. |
|
The user's client then decrypts the |
challenge using the private key, proving that he/she knows the private |
challenge using the private key, proving that he/she knows the private |
key but without disclosing it to the server. |
key but without disclosing it to the server. |
.Pp |
.Pp |
.Nm |
.Nm |
implements the RSA authentication protocol automatically. The user |
implements the RSA authentication protocol automatically. |
creates his/her RSA key pair by running |
The user creates his/her RSA key pair by running |
.Xr ssh-keygen 1 . |
.Xr ssh-keygen 1 . |
This stores the private key in |
This stores the private key in |
.Pa \&.ssh/identity |
.Pa \&.ssh/identity |
and the public key in |
and the public key in |
.Pa \&.ssh/identity.pub |
.Pa \&.ssh/identity.pub |
in the user's home directory. The user should then |
in the user's home directory. |
copy the |
The user should then copy the |
.Pa identity.pub |
.Pa identity.pub |
to |
to |
.Pa \&.ssh/authorized_keys |
.Pa \&.ssh/authorized_keys |
|
|
file corresponds to the conventional |
file corresponds to the conventional |
.Pa \&.rhosts |
.Pa \&.rhosts |
file, and has one key |
file, and has one key |
per line, though the lines can be very long). After this, the user |
per line, though the lines can be very long). |
can log in without giving the password. RSA authentication is much |
After this, the user can log in without giving the password. |
|
RSA authentication is much |
more secure than rhosts authentication. |
more secure than rhosts authentication. |
.Pp |
.Pp |
The most convenient way to use RSA authentication may be with an |
The most convenient way to use RSA authentication may be with an |
authentication agent. See |
authentication agent. |
|
See |
.Xr ssh-agent 1 |
.Xr ssh-agent 1 |
for more information. |
for more information. |
.Pp |
.Pp |
If other authentication methods fail, |
If other authentication methods fail, |
.Nm |
.Nm |
prompts the user for a password. The password is sent to the remote |
prompts the user for a password. |
|
The password is sent to the remote |
host for checking; however, since all communications are encrypted, |
host for checking; however, since all communications are encrypted, |
the password cannot be seen by someone listening on the network. |
the password cannot be seen by someone listening on the network. |
.Pp |
.Pp |
When the user's identity has been accepted by the server, the server |
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 |
either executes the given command, or logs into the machine and gives |
the user a normal shell on the remote machine. All communication with |
the user a normal shell on the remote machine. |
|
All communication with |
the remote command or shell will be automatically encrypted. |
the remote command or shell will be automatically encrypted. |
.Pp |
.Pp |
If a pseudo-terminal has been allocated (normal login session), the |
If a pseudo-terminal has been allocated (normal login session), the |
|
|
connections to terminate, it can be backgrounded with |
connections to terminate, it can be backgrounded with |
.Ic ~& |
.Ic ~& |
(this should not be used while the user shell is active, as it can cause the |
(this should not be used while the user shell is active, as it can cause the |
shell to hang). All available escapes can be listed with |
shell to hang). |
|
All available escapes can be listed with |
.Ic ~? . |
.Ic ~? . |
.Pp |
.Pp |
A single tilde character can be sent as |
A single tilde character can be sent as |
.Ic ~~ |
.Ic ~~ |
(or by following the tilde by a character other than those described above). |
(or by following the tilde by a character other than those described above). |
The escape character must always follow a newline to be interpreted as |
The escape character must always follow a newline to be interpreted as |
special. The escape character can be changed in configuration files |
special. |
or on the command line. |
The escape character can be changed in configuration files |
|
or on the command line. |
.Pp |
.Pp |
If no pseudo tty has been allocated, the |
If no pseudo tty has been allocated, the |
session is transparent and can be used to reliably transfer binary |
session is transparent and can be used to reliably transfer binary |
data. On most systems, setting the escape character to |
data. |
|
On most systems, setting the escape character to |
.Dq none |
.Dq none |
will also make the session transparent even if a tty is used. |
will also make the session transparent even if a tty is used. |
.Pp |
.Pp |
|
|
automatically forwarded to the remote side in such a way that any X11 |
automatically forwarded to the remote side in such a way that any X11 |
programs started from the shell (or command) will go through the |
programs started from the shell (or command) will go through the |
encrypted channel, and the connection to the real X server will be made |
encrypted channel, and the connection to the real X server will be made |
from the local machine. The user should not manually set |
from the local machine. |
|
The user should not manually set |
.Ev DISPLAY . |
.Ev DISPLAY . |
Forwarding of X11 connections can be |
Forwarding of X11 connections can be |
configured on the command line or in configuration files. |
configured on the command line or in configuration files. |
|
|
value set by |
value set by |
.Nm |
.Nm |
will point to the server machine, but with a display number greater |
will point to the server machine, but with a display number greater |
than zero. This is normal, and happens because |
than zero. |
|
This is normal, and happens because |
.Nm |
.Nm |
creates a |
creates a |
.Dq proxy |
.Dq proxy |
|
|
For this purpose, it will generate a random authorization cookie, |
For this purpose, it will generate a random authorization cookie, |
store it in Xauthority on the server, and verify that any forwarded |
store it in Xauthority on the server, and verify that any forwarded |
connections carry this cookie and replace it by the real cookie when |
connections carry this cookie and replace it by the real cookie when |
the connection is opened. The real authentication cookie is never |
the connection is opened. |
|
The real authentication cookie is never |
sent to the server machine (and no cookies are sent in the plain). |
sent to the server machine (and no cookies are sent in the plain). |
.Pp |
.Pp |
If the user is using an authentication agent, the connection to the agent |
If the user is using an authentication agent, the connection to the agent |
|
|
command line or in a configuration file. |
command line or in a configuration file. |
.Pp |
.Pp |
Forwarding of arbitrary TCP/IP connections over the secure channel can |
Forwarding of arbitrary TCP/IP connections over the secure channel can |
be specified either on command line or in a configuration file. One |
be specified either on command line or in a configuration file. |
possible application of TCP/IP forwarding is a secure connection to an |
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 trough firewalls. |
.Pp |
.Pp |
.Nm |
.Nm |
automatically maintains and checks a database containing RSA-based |
automatically maintains and checks a database containing RSA-based |
identifications for all hosts it has ever been used with. The |
identifications for all hosts it has ever been used with. |
database is stored in |
The database is stored in |
.Pa \&.ssh/known_hosts |
.Pa \&.ssh/known_hosts |
in the user's home directory. Additionally, the file |
in the user's home directory. |
|
Additionally, the file |
.Pa /etc/ssh_known_hosts |
.Pa /etc/ssh_known_hosts |
is automatically checked for known hosts. Any new hosts are |
is automatically checked for known hosts. |
automatically added to the user's file. If a host's identification |
Any new hosts are automatically added to the user's file. |
|
If a host's identification |
ever changes, |
ever changes, |
.Nm |
.Nm |
warns about this and disables password authentication to prevent a |
warns about this and disables password authentication to prevent a |
trojan horse from getting the user's password. Another purpose of |
trojan horse from getting the user's password. |
|
Another purpose of |
this mechanism is to prevent man-in-the-middle attacks which could |
this mechanism is to prevent man-in-the-middle attacks which could |
otherwise be used to circumvent the encryption. The |
otherwise be used to circumvent the encryption. |
|
The |
.Cm StrictHostKeyChecking |
.Cm StrictHostKeyChecking |
option (see below) can be used to prevent logins to machines whose |
option (see below) can be used to prevent logins to machines whose |
host key is not known or has changed. |
host key is not known or has changed. |
|
|
.It Fl c Ar blowfish|3des |
.It Fl c Ar blowfish|3des |
Selects the cipher to use for encrypting the session. |
Selects the cipher to use for encrypting the session. |
.Ar 3des |
.Ar 3des |
is used by default. It is believed to be secure. |
is used by default. |
|
It is believed to be secure. |
.Ar 3des |
.Ar 3des |
(triple-des) is an encrypt-decrypt-encrypt triple with three different keys. |
(triple-des) is an encrypt-decrypt-encrypt triple with three different keys. |
It is presumably more secure than the |
It is presumably more secure than the |
|
|
cipher which is no longer supported in ssh. |
cipher which is no longer supported in ssh. |
.Ar blowfish |
.Ar blowfish |
is a fast block cipher, it appears very secure and is much faster than |
is a fast block cipher, it appears very secure and is much faster than |
.Ar 3des . |
.Ar 3des . |
.It Fl e Ar ch|^ch|none |
.It Fl e Ar ch|^ch|none |
Sets the escape character for sessions with a pty (default: |
Sets the escape character for sessions with a pty (default: |
.Ql ~ ) . |
.Ql ~ ) . |
The escape character is only recognized at the beginning of a line. The |
The escape character is only recognized at the beginning of a line. |
escape character followed by a dot |
The escape character followed by a dot |
.Pq Ql \&. |
.Pq Ql \&. |
closes the connection, followed |
closes the connection, followed |
by control-Z suspends the connection, and followed by itself sends the |
by control-Z suspends the connection, and followed by itself sends the |
escape character once. Setting the character to |
escape character once. |
|
Setting the character to |
.Dq none |
.Dq none |
disables any escapes and makes the session fully transparent. |
disables any escapes and makes the session fully transparent. |
.It Fl f |
.It Fl f |
Requests |
Requests |
.Nm |
.Nm |
to go to background just before command execution. This is useful |
to go to background just before command execution. |
if |
This is useful if |
.Nm |
.Nm |
is going to ask for passwords or passphrases, but the user |
is going to ask for passwords or passphrases, but the user |
wants it in the background. This implies |
wants it in the background. |
|
This implies |
.Fl n . |
.Fl n . |
The recommended way to start X11 programs at a remote site is with |
The recommended way to start X11 programs at a remote site is with |
something like |
something like |
|
|
Allows remote hosts to connect to local forwarded ports. |
Allows remote hosts to connect to local forwarded ports. |
.It Fl i Ar identity_file |
.It Fl i Ar identity_file |
Selects the file from which the identity (private key) for |
Selects the file from which the identity (private key) for |
RSA authentication is read. Default is |
RSA authentication is read. |
|
Default is |
.Pa \&.ssh/identity |
.Pa \&.ssh/identity |
in the user's home directory. Identity files may also be specified on |
in the user's home directory. |
a per-host basis in the configuration file. It is possible to have |
Identity files may also be specified on |
multiple |
a per-host basis in the configuration file. |
|
It is possible to have multiple |
.Fl i |
.Fl i |
options (and multiple identities specified in |
options (and multiple identities specified in |
configuration files). |
configuration files). |
|
|
Disables forwarding of Kerberos tickets and AFS tokens. This may |
Disables forwarding of Kerberos tickets and AFS tokens. This may |
also be specified on a per-host basis in the configuration file. |
also be specified on a per-host basis in the configuration file. |
.It Fl l Ar login_name |
.It Fl l Ar login_name |
Specifies the user to log in as on the remote machine. This may also |
Specifies the user to log in as on the remote machine. |
be specified on a per-host basis in the configuration file. |
This also may be specified on a per-host basis in the configuration file. |
.It Fl n |
.It Fl n |
Redirects stdin from |
Redirects stdin from |
.Pa /dev/null |
.Pa /dev/null |
(actually, prevents reading from stdin). |
(actually, prevents reading from stdin). |
This must be used when |
This must be used when |
.Nm |
.Nm |
is run in the background. A common trick is to use this to run X11 |
is run in the background. |
programs in a remote machine. For example, |
A common trick is to use this to run X11 programs on a remote machine. |
|
For example, |
.Ic ssh -n shadows.cs.hut.fi emacs & |
.Ic ssh -n shadows.cs.hut.fi emacs & |
will start an emacs on shadows.cs.hut.fi, and the X11 |
will start an emacs on shadows.cs.hut.fi, and the X11 |
connection will be automatically forwarded over an encrypted channel. |
connection will be automatically forwarded over an encrypted channel. |
|
|
.It Fl o Ar option |
.It Fl o Ar option |
Can be used to give options in the format used in the config file. |
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 |
This is useful for specifying options for which there is no separate |
command-line flag. The option has the same format as a line in the |
command-line flag. |
configuration file. |
The option has the same format as a line in the configuration file. |
.It Fl p Ar port |
.It Fl p Ar port |
Port to connect to on the remote host. This can be specified on a |
Port to connect to on the remote host. |
|
This can be specified on a |
per-host basis in the configuration file. |
per-host basis in the configuration file. |
.It Fl P |
.It Fl P |
Use a non-privileged port for outgoing connections. |
Use a non-privileged port for outgoing connections. |
|
|
and |
and |
.Cm RhostsRSAAuthentication . |
.Cm RhostsRSAAuthentication . |
.It Fl q |
.It Fl q |
Quiet mode. Causes all warning and diagnostic messages to be |
Quiet mode. |
suppressed. Only fatal errors are displayed. |
Causes all warning and diagnostic messages to be suppressed. |
|
Only fatal errors are displayed. |
.It Fl t |
.It Fl t |
Force pseudo-tty allocation. This can be used to execute arbitary |
Force pseudo-tty allocation. |
screen-based programs on a remote machine, which can be very useful |
This can be used to execute arbitary |
e.g. when implementing menu services. |
screen-based programs on a remote machine, which can be very useful, |
|
e.g., when implementing menu services. |
.It Fl v |
.It Fl v |
Verbose mode. Causes |
Verbose mode. |
|
Causes |
.Nm |
.Nm |
to print debugging messages about its progress. This is helpful in |
to print debugging messages about its progress. |
|
This is helpful in |
debugging connection, authentication, and configuration problems. |
debugging connection, authentication, and configuration problems. |
The verbose mode is also used to display |
The verbose mode is also used to display |
.Xr skey 1 |
.Xr skey 1 |
challenges, if the user entered "s/key" as password. |
challenges, if the user entered "s/key" as password. |
.It Fl x |
.It Fl x |
Disables X11 forwarding. This can also be specified on a per-host |
Disables X11 forwarding. |
basis in a configuration file. |
This can also be specified on a per-host basis in a configuration file. |
.It Fl X |
.It Fl X |
Enables X11 forwarding. |
Enables X11 forwarding. |
.It Fl C |
.It Fl C |
Requests compression of all data (including stdin, stdout, stderr, and |
Requests compression of all data (including stdin, stdout, stderr, and |
data for forwarded X11 and TCP/IP connections). The compression |
data for forwarded X11 and TCP/IP connections). |
algorithm is the same used by |
The compression algorithm is the same used by |
.Xr gzip 1 , |
.Xr gzip 1 , |
and the |
and the |
.Dq level |
.Dq level |
can be controlled by the |
can be controlled by the |
.Cm CompressionLevel |
.Cm CompressionLevel |
option (see below). Compression is desirable on modem lines and other |
option (see below). |
|
Compression is desirable on modem lines and other |
slow connections, but will only slow down things on fast networks. |
slow connections, but will only slow down things on fast networks. |
The default value can be set on a host-by-host basis in the |
The default value can be set on a host-by-host basis in the |
configuration files; see the |
configuration files; see the |
|
|
option below. |
option below. |
.It Fl L Ar port:host:hostport |
.It Fl L Ar port:host:hostport |
Specifies that the given port on the local (client) host is to be |
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 |
forwarded to the given host and port on the remote side. |
by allocating a socket to listen to |
This works by allocating a socket to listen to |
.Ar port |
.Ar port |
on the local side, and whenever a connection is made to this port, the |
on the local side, and whenever a connection is made to this port, the |
connection is forwarded over the secure channel, and a connection is |
connection is forwarded over the secure channel, and a connection is |
|
|
.Ar host |
.Ar host |
port |
port |
.Ar hostport |
.Ar hostport |
from the remote machine. Port forwardings can also be specified in the |
from the remote machine. |
configuration file. Only root can forward privileged ports. |
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: |
IPv6 addresses can be specified with an alternative syntax: |
.Ar port/host/hostport |
.Ar port/host/hostport |
.It Fl R Ar port:host:hostport |
.It Fl R Ar port:host:hostport |
Specifies that the given port on the remote (server) host is to be |
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 |
forwarded to the given host and port on the local side. |
by allocating a socket to listen to |
This works by allocating a socket to listen to |
.Ar port |
.Ar port |
on the remote side, and whenever a connection is made to this port, the |
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 |
connection is forwarded over the secure channel, and a connection is |
|
|
.Ar host |
.Ar host |
port |
port |
.Ar hostport |
.Ar hostport |
from the local machine. Port forwardings can also be specified in the |
from the local machine. |
configuration file. Privileged ports can be forwarded only when |
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. |
logging in as root on the remote machine. |
.It Fl 4 |
.It Fl 4 |
Forces |
Forces |
|
|
and system-wide configuration file |
and system-wide configuration file |
.Pq Pa /etc/ssh_config . |
.Pq Pa /etc/ssh_config . |
For each parameter, the first obtained value |
For each parameter, the first obtained value |
will be used. The configuration files contain sections bracketed by |
will be used. |
"Host" specifications, and that section is only applied for hosts that |
The configuration files contain sections bracketed by |
match one of the patterns given in the specification. The matched |
.Dq Host |
host name is the one given on the command line. |
specifications, and that section is only applied for hosts that |
|
match one of the patterns given in the specification. |
|
The matched host name is the one given on the command line. |
.Pp |
.Pp |
Since the first obtained value for each parameter is used, more |
Since the first obtained value for each parameter is used, more |
host-specific declarations should be given near the beginning of the |
host-specific declarations should be given near the beginning of the |
|
|
and |
and |
.Ql ? |
.Ql ? |
can be used as wildcards in the |
can be used as wildcards in the |
patterns. A single |
patterns. |
|
A single |
.Ql \&* |
.Ql \&* |
as a pattern can be used to provide global |
as a pattern can be used to provide global |
defaults for all hosts. The host is the |
defaults for all hosts. |
|
The host is the |
.Ar hostname |
.Ar hostname |
argument given on the command line (i.e., the name is not converted to |
argument given on the command line (i.e., the name is not converted to |
a canonicalized host name before matching). |
a canonicalized host name before matching). |
|
|
.It Cm BatchMode |
.It Cm BatchMode |
If set to |
If set to |
.Dq yes , |
.Dq yes , |
passphrase/password querying will be disabled. This |
passphrase/password querying will be disabled. |
option is useful in scripts and other batch jobs where you have no |
This option is useful in scripts and other batch jobs where you have no |
user to supply the password. The argument must be |
user to supply the password. |
|
The argument must be |
.Dq yes |
.Dq yes |
or |
or |
.Dq no . |
.Dq no . |
|
|
.Dq no , |
.Dq no , |
the check will not be executed. |
the check will not be executed. |
.It Cm Cipher |
.It Cm Cipher |
Specifies the cipher to use for encrypting the session. Currently, |
Specifies the cipher to use for encrypting the session. |
|
Currently, |
.Dq blowfish , |
.Dq blowfish , |
and |
and |
.Dq 3des |
.Dq 3des |
are supported. The default is |
are supported. |
|
The default is |
.Dq 3des . |
.Dq 3des . |
.It Cm Compression |
.It Cm Compression |
Specifies whether to use compression. The argument must be |
Specifies whether to use compression. |
|
The argument must be |
.Dq yes |
.Dq yes |
or |
or |
.Dq no . |
.Dq no . |
.It Cm CompressionLevel |
.It Cm CompressionLevel |
Specifies the compression level to use if compression is enable. The |
Specifies the compression level to use if compression is enable. |
argument must be an integer from 1 (fast) to 9 (slow, best). The |
The argument must be an integer from 1 (fast) to 9 (slow, best). |
default level is 6, which is good for most applications. The meaning |
The default level is 6, which is good for most applications. |
of the values is the same as in |
The meaning of the values is the same as in |
.Xr gzip 1 . |
.Xr gzip 1 . |
.It Cm ConnectionAttempts |
.It Cm ConnectionAttempts |
Specifies the number of tries (one per second) to make before falling |
Specifies the number of tries (one per second) to make before falling |
back to rsh or exiting. The argument must be an integer. This may be |
back to rsh or exiting. |
useful in scripts if the connection sometimes fails. |
The argument must be an integer. |
|
This may be useful in scripts if the connection sometimes fails. |
.It Cm EscapeChar |
.It Cm EscapeChar |
Sets the escape character (default: |
Sets the escape character (default: |
.Ql ~ ) . |
.Ql ~ ) . |
The escape character can also |
The escape character can also |
be set on the command line. The argument should be a single |
be set on the command line. |
character, |
The argument should be a single character, |
.Ql ^ |
.Ql ^ |
followed by a letter, or |
followed by a letter, or |
.Dq none |
.Dq none |
|
|
listening on the remote host), |
listening on the remote host), |
.Xr rsh 1 |
.Xr rsh 1 |
should automatically be used instead (after a suitable warning about |
should automatically be used instead (after a suitable warning about |
the session being unencrypted). The argument must be |
the session being unencrypted). |
|
The argument must be |
.Dq yes |
.Dq yes |
or |
or |
.Dq no . |
.Dq no . |
.It Cm ForwardAgent |
.It Cm ForwardAgent |
Specifies whether the connection to the authentication agent (if any) |
Specifies whether the connection to the authentication agent (if any) |
will be forwarded to the remote machine. The argument must be |
will be forwarded to the remote machine. |
|
The argument must be |
.Dq yes |
.Dq yes |
or |
or |
.Dq no . |
.Dq no . |
|
|
Specifies whether X11 connections will be automatically redirected |
Specifies whether X11 connections will be automatically redirected |
over the secure channel and |
over the secure channel and |
.Ev DISPLAY |
.Ev DISPLAY |
set. The argument must be |
set. |
|
The argument must be |
.Dq yes |
.Dq yes |
or |
or |
.Dq no . |
.Dq no . |
|
|
Specifies a file to use instead of |
Specifies a file to use instead of |
.Pa /etc/ssh_known_hosts . |
.Pa /etc/ssh_known_hosts . |
.It Cm HostName |
.It Cm HostName |
Specifies the real host name to log into. This can be used to specify |
Specifies the real host name to log into. |
nicnames or abbreviations for hosts. Default is the name given on the |
This can be used to specify nicknames or abbreviations for hosts. |
command line. Numeric IP addresses are also permitted (both on the |
Default is the name given on the command line. |
command line and in |
Numeric IP addresses are also permitted (both on the command line and in |
.Cm HostName |
.Cm HostName |
specifications). |
specifications). |
.It Cm IdentityFile |
.It Cm IdentityFile |
|
|
.Pa .ssh/identity |
.Pa .ssh/identity |
in the user's home directory). |
in the user's home directory). |
Additionally, any identities represented by the authentication agent |
Additionally, any identities represented by the authentication agent |
will be used for authentication. The file name may use the tilde |
will be used for authentication. |
syntax to refer to a user's home directory. It is possible to have |
The file name may use the tilde |
|
syntax to refer to a user's home directory. |
|
It is possible to have |
multiple identity files specified in configuration files; all these |
multiple identity files specified in configuration files; all these |
identities will be tried in sequence. |
identities will be tried in sequence. |
.It Cm KeepAlive |
.It Cm KeepAlive |
Specifies whether the system should send keepalive messages to the |
Specifies whether the system should send keepalive messages to the |
other side. If they are sent, death of the connection or crash of one |
other side. |
of the machines will be properly noticed. However, this means that |
If they are sent, death of the connection or crash of one |
|
of the machines will be properly noticed. |
|
However, this means that |
connections will die if the route is down temporarily, and some people |
connections will die if the route is down temporarily, and some people |
find it annoying. |
find it annoying. |
.Pp |
.Pp |
The default is |
The default is |
.Dq yes |
.Dq yes |
(to send keepalives), and the client will notice |
(to send keepalives), and the client will notice |
if the network goes down or the remote host dies. This is important |
if the network goes down or the remote host dies. |
in scripts, and many users want it too. |
This is important in scripts, and many users want it too. |
.Pp |
.Pp |
To disable keepalives, the value should be set to |
To disable keepalives, the value should be set to |
.Dq no |
.Dq no |
|
|
.Dq no . |
.Dq no . |
.It Cm LocalForward |
.It Cm LocalForward |
Specifies that a TCP/IP port on the local machine be forwarded over |
Specifies that a TCP/IP port on the local machine be forwarded over |
the secure channel to given host:port from the remote machine. The |
the secure channel to given host:port from the remote machine. |
first argument must be a port number, and the second must be |
The first argument must be a port number, and the second must be |
host:port. Multiple forwardings may be specified, and additional |
host:port. |
forwardings can be given on the command line. Only the root can |
Multiple forwardings may be specified, and additional |
forward privileged ports. |
forwardings can be given on the command line. |
|
Only the superuser can forward privileged ports. |
.It Cm LogLevel |
.It Cm LogLevel |
Gives the verbosity level that is used when logging messages from |
Gives the verbosity level that is used when logging messages from |
.Nm ssh . |
.Nm ssh . |
|
|
Specifies the number of password prompts before giving up. The |
Specifies the number of password prompts before giving up. The |
argument to this keyword must be an integer. Default is 3. |
argument to this keyword must be an integer. Default is 3. |
.It Cm PasswordAuthentication |
.It Cm PasswordAuthentication |
Specifies whether to use password authentication. The argument to |
Specifies whether to use password authentication. |
this keyword must be |
The argument to this keyword must be |
.Dq yes |
.Dq yes |
or |
or |
.Dq no . |
.Dq no . |
.It Cm Port |
.It Cm Port |
Specifies the port number to connect on the remote host. Default is |
Specifies the port number to connect on the remote host. |
22. |
Default is 22. |
.It Cm ProxyCommand |
.It Cm ProxyCommand |
Specifies the command to use to connect to the server. The command |
Specifies the command to use to connect to the server. |
string extends to the end of the line, and is executed with /bin/sh. |
The command |
In the command string, %h will be substituted by the host name to |
string extends to the end of the line, and is executed with |
connect and %p by the port. The command can be basically anything, |
.Pa /bin/sh . |
and should read from its stdin and write to its stdout. It should |
In the command string, |
eventually connect an |
.Ql %h |
|
will be substituted by the host name to |
|
connect and |
|
.Ql %p |
|
by the port. |
|
The command can be basically anything, |
|
and should read from its standard input and write to its standard output. |
|
It should eventually connect an |
.Xr sshd 8 |
.Xr sshd 8 |
server running on some machine, or execute |
server running on some machine, or execute |
.Ic sshd -i |
.Ic sshd -i |
somewhere. Host key management will be done using the |
somewhere. |
|
Host key management will be done using the |
HostName of the host being connected (defaulting to the name typed by |
HostName of the host being connected (defaulting to the name typed by |
the user). |
the user). |
Note that |
Note that |
|
|
.Pp |
.Pp |
.It Cm RemoteForward |
.It Cm RemoteForward |
Specifies that a TCP/IP port on the remote machine be forwarded over |
Specifies that a TCP/IP port on the remote machine be forwarded over |
the secure channel to given host:port from the local machine. The |
the secure channel to given host:port from the local machine. |
first argument must be a port number, and the second must be |
The first argument must be a port number, and the second must be |
host:port. Multiple forwardings may be specified, and additional |
host:port. |
forwardings can be given on the command line. Only the root can |
Multiple forwardings may be specified, and additional |
forward privileged ports. |
forwardings can be given on the command line. |
|
Only the superuser can forward privileged ports. |
.It Cm RhostsAuthentication |
.It Cm RhostsAuthentication |
Specifies whether to try rhosts based authentication. Note that this |
Specifies whether to try rhosts based authentication. |
|
Note that this |
declaration only affects the client side and has no effect whatsoever |
declaration only affects the client side and has no effect whatsoever |
on security. Disabling rhosts authentication may reduce |
on security. |
|
Disabling rhosts authentication may reduce |
authentication time on slow connections when rhosts authentication is |
authentication time on slow connections when rhosts authentication is |
not used. Most servers do not permit RhostsAuthentication because it |
not used. |
is not secure (see RhostsRSAAuthentication). The argument to this |
Most servers do not permit RhostsAuthentication because it |
keyword must be |
is not secure (see RhostsRSAAuthentication). |
|
The argument to this keyword must be |
.Dq yes |
.Dq yes |
or |
or |
.Dq no . |
.Dq no . |
.It Cm RhostsRSAAuthentication |
.It Cm RhostsRSAAuthentication |
Specifies whether to try rhosts based authentication with RSA host |
Specifies whether to try rhosts based authentication with RSA host |
authentication. This is the primary authentication method for most |
authentication. |
sites. The argument must be |
This is the primary authentication method for most sites. |
|
The argument must be |
.Dq yes |
.Dq yes |
or |
or |
.Dq no . |
.Dq no . |
.It Cm RSAAuthentication |
.It Cm RSAAuthentication |
Specifies whether to try RSA authentication. The argument to this |
Specifies whether to try RSA authentication. |
keyword must be |
The argument to this keyword must be |
.Dq yes |
.Dq yes |
or |
or |
.Dq no . |
.Dq no . |
|
|
.It Cm SkeyAuthentication |
.It Cm SkeyAuthentication |
Specifies whether to use |
Specifies whether to use |
.Xr skey 1 |
.Xr skey 1 |
authentication. The argument to |
authentication. |
this keyword must be |
The argument to this keyword must be |
.Dq yes |
.Dq yes |
or |
or |
.Dq no . |
.Dq no . |
|
|
.Nm |
.Nm |
ssh will never automatically add host keys to the |
ssh will never automatically add host keys to the |
.Pa $HOME/.ssh/known_hosts |
.Pa $HOME/.ssh/known_hosts |
file, and refuses to connect hosts whose host key has changed. This |
file, and refuses to connect hosts whose host key has changed. |
provides maximum protection against trojan horse attacks. However, it |
This provides maximum protection against trojan horse attacks. |
can be somewhat annoying if you don't have good |
However, it can be somewhat annoying if you don't have good |
.Pa /etc/ssh_known_hosts |
.Pa /etc/ssh_known_hosts |
files installed and frequently |
files installed and frequently |
connect new hosts. Basically this option forces the user to manually |
connect new hosts. |
add any new hosts. Normally this option is disabled, and new hosts |
Basically this option forces the user to manually |
will automatically be added to the known host files. The host keys of |
add any new hosts. |
known hosts will be verified automatically in either case. The |
Normally this option is disabled, and new hosts |
argument must be |
will automatically be added to the known host files. |
|
The host keys of |
|
known hosts will be verified automatically in either case. |
|
The argument must be |
.Dq yes |
.Dq yes |
or |
or |
.Dq no . |
.Dq no . |
|
|
and |
and |
.Cm RhostsRSAAuthentication . |
.Cm RhostsRSAAuthentication . |
.It Cm User |
.It Cm User |
Specifies the user to log in as. This can be useful if you have a |
Specifies the user to log in as. |
different user name in different machines. This saves the trouble of |
This can be useful if you have a different user name on different machines. |
|
This saves the trouble of |
having to remember to give the user name on the command line. |
having to remember to give the user name on the command line. |
.It Cm UserKnownHostsFile |
.It Cm UserKnownHostsFile |
Specifies a file to use instead of |
Specifies a file to use instead of |
.Pa $HOME/.ssh/known_hosts . |
.Pa $HOME/.ssh/known_hosts . |
.It Cm UseRsh |
.It Cm UseRsh |
Specifies that rlogin/rsh should be used for this host. It is |
Specifies that rlogin/rsh should be used for this host. |
possible that the host does not at all support the |
It is possible that the host does not at all support the |
.Nm |
.Nm |
protocol. This causes |
protocol. |
|
This causes |
.Nm |
.Nm |
to immediately exec |
to immediately execute |
.Xr rsh 1 . |
.Xr rsh 1 . |
All other options (except |
All other options (except |
.Cm HostName ) |
.Cm HostName ) |
are ignored if this has been specified. The argument must be |
are ignored if this has been specified. |
|
The argument must be |
.Dq yes |
.Dq yes |
or |
or |
.Dq no . |
.Dq no . |
|
|
.It Ev DISPLAY |
.It Ev DISPLAY |
The |
The |
.Ev DISPLAY |
.Ev DISPLAY |
variable indicates the location of the X11 server. It is |
variable indicates the location of the X11 server. |
automatically set by |
It is automatically set by |
.Nm |
.Nm |
to point to a value of the form |
to point to a value of the form |
.Dq hostname:n |
.Dq hostname:n |
where hostname indicates |
where hostname indicates |
the host where the shell runs, and n is an integer >= 1. Ssh uses |
the host where the shell runs, and n is an integer >= 1. |
this special value to forward X11 connections over the secure |
.Nm |
channel. The user should normally not set DISPLAY explicitly, as that |
uses this special value to forward X11 connections over the secure |
|
channel. |
|
The user should normally not set DISPLAY explicitly, as that |
will render the X11 connection insecure (and will require the user to |
will render the X11 connection insecure (and will require the user to |
manually copy any required authorization cookies). |
manually copy any required authorization cookies). |
.It Ev HOME |
.It Ev HOME |
|
|
set for compatibility with systems that use this variable. |
set for compatibility with systems that use this variable. |
.It Ev MAIL |
.It Ev MAIL |
Set to point the user's mailbox. |
Set to point the user's mailbox. |
.It Ev PATH |
.It Ev PATH |
Set to the default |
Set to the default |
.Ev PATH , |
.Ev PATH , |
as specified when compiling |
as specified when compiling |
|
|
indicates the path of a unix-domain socket used to communicate with the |
indicates the path of a unix-domain socket used to communicate with the |
agent. |
agent. |
.It Ev SSH_CLIENT |
.It Ev SSH_CLIENT |
Identifies the client end of the connection. The variable contains |
Identifies the client end of the connection. |
|
The variable contains |
three space-separated values: client ip-address, client port number, |
three space-separated values: client ip-address, client port number, |
and server port number. |
and server port number. |
.It Ev SSH_TTY |
.It Ev SSH_TTY |
This is set to the name of the tty (path to the device) associated |
This is set to the name of the tty (path to the device) associated |
with the current shell or command. If the current session has no tty, |
with the current shell or command. |
|
If the current session has no tty, |
this variable is not set. |
this variable is not set. |
.It Ev TZ |
.It Ev TZ |
The timezone variable is set to indicate the present timezone if it |
The timezone variable is set to indicate the present timezone if it |
|
|
See |
See |
.Xr sshd 8 . |
.Xr sshd 8 . |
.It Pa $HOME/.ssh/identity |
.It Pa $HOME/.ssh/identity |
Contains the RSA authentication identity of the user. This file |
Contains the RSA authentication identity of the user. |
|
This file |
contains sensitive data and should be readable by the user but not |
contains sensitive data and should be readable by the user but not |
accessible by others (read/write/execute). |
accessible by others (read/write/execute). |
Note that |
Note that |
|
|
sensitive part of this file using 3DES. |
sensitive part of this file using 3DES. |
.It Pa $HOME/.ssh/identity.pub |
.It Pa $HOME/.ssh/identity.pub |
Contains the public key for authentication (public part of the |
Contains the public key for authentication (public part of the |
identity file in human-readable form). The contents of this file |
identity file in human-readable form). |
should be added to |
The contents of this file should be added to |
.Pa $HOME/.ssh/authorized_keys |
.Pa $HOME/.ssh/authorized_keys |
on all machines |
on all machines |
where you wish to log in using RSA authentication. This file is not |
where you wish to log in using RSA authentication. |
sensitive and can (but need not) be readable by anyone. This file is |
This file is 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 |
never used automatically and is not necessary; it is only provided for |
the convenience of the user. |
the convenience of the user. |
.It Pa $HOME/.ssh/config |
.It Pa $HOME/.ssh/config |
This is the per-user configuration file. The format of this file is |
This is the per-user configuration file. |
described above. This file is used by the |
The format of this file is described above. |
|
This file is used by the |
.Nm |
.Nm |
client. This file does not usually contain any sensitive information, |
client. |
|
This file does not usually contain any sensitive information, |
but the recommended permissions are read/write for the user, and not |
but the recommended permissions are read/write for the user, and not |
accessible by others. |
accessible by others. |
.It Pa $HOME/.ssh/authorized_keys |
.It Pa $HOME/.ssh/authorized_keys |
Lists the RSA keys that can be used for logging in as this user. The |
Lists the RSA keys that can be used for logging in as this user. |
format of this file is described in the |
The format of this file is described in the |
.Xr sshd 8 |
.Xr sshd 8 |
manual page. In the simplest form the format is the same as the .pub |
manual page. |
|
In the simplest form the format is the same as the .pub |
identity files (that is, each line contains the number of bits in |
identity files (that is, each line contains the number of bits in |
modulus, public exponent, modulus, and comment fields, separated by |
modulus, public exponent, modulus, and comment fields, separated by |
spaces). This file is not highly sensitive, but the recommended |
spaces). |
|
This file is not highly sensitive, but the recommended |
permissions are read/write for the user, and not accessible by others. |
permissions are read/write for the user, and not accessible by others. |
.It Pa /etc/ssh_known_hosts |
.It Pa /etc/ssh_known_hosts |
Systemwide list of known host keys. This file should be prepared by the |
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 |
system administrator to contain the public host keys of all machines in the |
organization. This file should be world-readable. This file contains |
organization. |
|
This file should be world-readable. |
|
This file contains |
public keys, one per line, in the following format (fields separated |
public keys, one per line, in the following format (fields separated |
by spaces): system name, number of bits in modulus, public exponent, |
by spaces): system name, number of bits in modulus, public exponent, |
modulus, and optional comment field. When different names are used |
modulus, and optional comment field. |
|
When different names are used |
for the same machine, all such names should be listed, separated by |
for the same machine, all such names should be listed, separated by |
commas. The format is described on the |
commas. |
|
The format is described on the |
.Xr sshd 8 |
.Xr sshd 8 |
manual page. |
manual page. |
.Pp |
.Pp |
|
|
checking the key, because someone with access to the name servers |
checking the key, because someone with access to the name servers |
would then be able to fool host authentication. |
would then be able to fool host authentication. |
.It Pa /etc/ssh_config |
.It Pa /etc/ssh_config |
Systemwide configuration file. This file provides defaults for those |
Systemwide configuration file. |
|
This file provides defaults for those |
values that are not specified in the user's configuration file, and |
values that are not specified in the user's configuration file, and |
for those users who do not have a configuration file. This file must |
for those users who do not have a configuration file. |
be world-readable. |
This file must be world-readable. |
.It Pa $HOME/.rhosts |
.It Pa $HOME/.rhosts |
This file is used in |
This file is used in |
.Pa \&.rhosts |
.Pa \&.rhosts |
authentication to list the |
authentication to list the |
host/user pairs that are permitted to log in. (Note that this file is |
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.) |
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 |
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, |
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 |
separated by a space. |
|
One some machines this file may need to be |
world-readable if the user's home directory is on a NFS partition, |
world-readable if the user's home directory is on a NFS partition, |
because |
because |
.Xr sshd 8 |
.Xr sshd 8 |
reads it as root. Additionally, this file must be owned by the user, |
reads it as root. |
and must not have write permissions for anyone else. The recommended |
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 |
permission for most machines is read/write for the user, and not |
accessible by others. |
accessible by others. |
.Pp |
.Pp |
Note that by default |
Note that by default |
.Xr sshd 8 |
.Xr sshd 8 |
will be installed so that it requires successful RSA host |
will be installed so that it requires successful RSA host |
authentication before permitting \s+2.\s0rhosts authentication. If your |
authentication before permitting \s+2.\s0rhosts authentication. |
server machine does not have the client's host key in |
If your server machine does not have the client's host key in |
.Pa /etc/ssh_known_hosts , |
.Pa /etc/ssh_known_hosts , |
you can store it in |
you can store it in |
.Pa $HOME/.ssh/known_hosts . |
.Pa $HOME/.ssh/known_hosts . |
|
|
.Xr rsh 1 . |
.Xr rsh 1 . |
.It Pa /etc/hosts.equiv |
.It Pa /etc/hosts.equiv |
This file is used during |
This file is used during |
.Pa \&.rhosts authentication. It contains |
.Pa \&.rhosts authentication. |
|
It contains |
canonical hosts names, one per line (the full format is described on |
canonical hosts names, one per line (the full format is described on |
the |
the |
.Xr sshd 8 |
.Xr sshd 8 |
manual page). If the client host is found in this file, login is |
manual page). |
|
If the client host is found in this file, login is |
automatically permitted provided client and server user names are the |
automatically permitted provided client and server user names are the |
same. Additionally, successful RSA host authentication is normally |
same. |
required. This file should only be writable by root. |
Additionally, successful RSA host authentication is normally |
|
required. |
|
This file should only be writable by root. |
.It Pa /etc/shosts.equiv |
.It Pa /etc/shosts.equiv |
This file is processed exactly as |
This file is processed exactly as |
.Pa /etc/hosts.equiv . |
.Pa /etc/hosts.equiv . |
|
|
.Sh AUTHOR |
.Sh AUTHOR |
OpenSSH |
OpenSSH |
is a derivative of the original (free) ssh 1.2.12 release by Tatu Ylonen, |
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 |
but with bugs removed and newer features re-added. |
|
Rapidly after the |
1.2.12 release, newer versions of the original ssh bore successively |
1.2.12 release, newer versions of the original ssh bore successively |
more restrictive licenses, and thus demand for a free version was born. |
more restrictive licenses, and thus demand for a free version was born. |
This version of OpenSSH |
This version of OpenSSH |