ssh [-1246AaCfgkMNnqsTtVvXxY] [-b bind_address] [-c ci-
pher_spec]
[-D port] [-e escape_char] [-F configfile] [-i identi-
ty_file]
[-L [bind_address:]port:host:hostport] [-l login_name]
[-m mac_spec]
[-O ctl_cmd] [-o option] [-p port]
[-R [bind_address:]port:host:hostport] [-S ctl_path]
[user@]hostname
[command]
DESCRIPTION
ssh (SSH client) is a program for logging into a remote ma-
chine and for
executing commands on a remote machine. It is intended to
replace rlogin
and rsh, and provide secure encrypted communications between
two untrust-
ed hosts over an insecure network. X11 connections and ar-
bitrary TCP/IP
ports can also be forwarded over the secure channel.
ssh connects and logs into the specified hostname (with op-
tional user
name). The user must prove his/her identity to the remote
machine using
one of several methods depending on the protocol version
used.
If command is specified, command is executed on the remote
host instead
of a login shell.
SSH protocol version 1
The first authentication method is the rhosts or hosts.equiv
method com-
bined with RSA-based host authentication. If the machine
the user logs
in from is listed in /etc/hosts.equiv or /etc/shosts.equiv
on the remote
machine, and the user names are the same on both sides, or
if the files
~/.rhosts or ~/.shosts exist in the user's home directory on
the remote
machine and contain a line containing the name of the client
machine and
the name of the user on that machine, the user is considered
for log in.
Additionally, if the server can verify the client's host key
(see
/etc/ssh/ssh_known_hosts and ~/.ssh/known_hosts in the FILES
section),
where encryption and decryption are done using separate
keys, and it is
not possible to derive the decryption key from the encryp-
tion key. RSA
is one such system. The idea is that each user creates a
public/private
key pair for authentication purposes. The server knows the
public key,
and only the user knows the private key.
The file ~/.ssh/authorized_keys lists the public keys that
are permitted
for logging in. When the user logs in, the ssh program
tells the server
which key pair it would like to use for authentication. The
server
checks if this key is permitted, and if so, sends the user
(actually the
ssh program running on behalf of the user) a challenge, a
random number,
encrypted by the user's public key. The challenge can only
be decrypted
using the proper private key. The user's client then de-
crypts the chal-
lenge using the private key, proving that he/she knows the
private key
but without disclosing it to the server.
ssh implements the RSA authentication protocol automatical-
ly. The user
creates his/her RSA key pair by running ssh-keygen(1). This
stores the
private key in ~/.ssh/identity and stores the public key in
~/.ssh/identity.pub in the user's home directory. The user
should then
copy the identity.pub to ~/.ssh/authorized_keys in his/her
home directory
on the remote machine (the authorized_keys file corresponds
to the con-
ventional ~/.rhosts file, and has one key per line, though
the lines can
be very long). After this, the user can log in without giv-
ing the pass-
word.
The most convenient way to use RSA authentication may be
with an authen-
tication agent. See ssh-agent(1) for more information.
If other authentication methods fail, ssh prompts the user
for a pass-
word. The password is sent to the remote host for checking;
active and
password authentication are tried.
The public key method is similar to RSA authentication de-
scribed in the
previous section and allows the RSA or DSA algorithm to be
used: The
client uses his private key, ~/.ssh/id_dsa or ~/.ssh/id_rsa,
to sign the
session identifier and sends the result to the server. The
server checks
whether the matching public key is listed in ~/.ssh/autho-
rized_keys 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.
If public key authentication fails or is not available, a
password can be
sent encrypted to the remote host to prove the user's iden-
tity.
Additionally, ssh supports hostbased or challenge response
authentica-
tion.
Protocol 2 provides additional mechanisms for confidentiali-
ty (the traf-
fic is encrypted using AES, 3DES, Blowfish, CAST128 or Arc-
four) and in-
tegrity (hmac-md5, hmac-sha1, hmac-ripemd160). Note that
protocol 1
lacks a strong mechanism for ensuring the integrity of the
connection.
Login session and remote execution
When the user's identity has been accepted by the server,
the server ei-
ther executes the given command, or logs into the machine
and gives the
user a normal shell on the remote machine. All communica-
tion with the
remote command or shell will be automatically encrypted.
If a pseudo-terminal has been allocated (normal login ses-
sion), the user
may use the escape characters noted below.
If no pseudo-tty has been allocated, the session is trans-
parent and can
When a pseudo-terminal has been requested, ssh supports a
number of func-
tions through the use of an escape character.
A single tilde character can be sent as ~~ or by following
the tilde by a
character other than those described below. The escape
character must
always follow a newline to be interpreted as special. The
escape charac-
ter can be changed in configuration files using the Es-
capeChar configura-
tion directive or on the command line by the -e option.
The supported escapes (assuming the default `~') are:
~. Disconnect.
~^Z Background ssh.
~# List forwarded connections.
~& Background ssh at logout when waiting for forwarded
connection /
X11 sessions to terminate.
~? Display a list of escape characters.
~B Send a BREAK to the remote system (only useful for
SSH protocol
version 2 and if the peer supports it).
~C Open command line. Currently this allows the addi-
tion of port
forwardings using the -L and -R options (see below).
It also al-
lows the cancellation of existing remote port-for-
wardings using
-KR hostport. Basic help is available, using the -h
option.
~R Request rekeying of the connection (only useful for
SSH protocol
version 2 and if the peer supports it).
X11 and TCP forwarding
If the ForwardX11 variable is set to ``yes'' (or see the de-
scription of
the -X and -x options described later) and the user is using
X11 (the
DISPLAY environment variable is set), the connection to the
X11 display
display number greater than zero. This is normal, and hap-
pens because
ssh creates a ``proxy'' X server on the server machine for
forwarding the
connections over the encrypted channel.
ssh will also automatically set up Xauthority data on the
server machine.
For this purpose, it will generate a random authorization
cookie, store
it in Xauthority on the server, and verify that any forward-
ed connections
carry this cookie and replace it by the real cookie when the
connection
is opened. The real authentication cookie is never sent to
the server
machine (and no cookies are sent in the plain).
If the ForwardAgent variable is set to ``yes'' (or see the
description of
the -A and -a options described later) and the user is using
an authenti-
cation agent, the connection to the agent is automatically
forwarded to
the remote side.
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 con-
nection to an
electronic purse; another is going through firewalls.
Server authentication
ssh automatically maintains and checks a database containing
identifica-
tions for all hosts it has ever been used with. Host keys
are stored in
~/.ssh/known_hosts in the user's home directory. Addition-
ally, the file
/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 iden-
tification ever changes, ssh warns about this and disables
password au-
thentication to prevent a trojan horse from getting the us-
er's password.
Another purpose of this mechanism is to prevent man-in-the-
middle attacks
which could otherwise be used to circumvent the encryption.
-1 Forces ssh to try protocol version 1 only.
-2 Forces ssh to try protocol version 2 only.
-4 Forces ssh to use IPv4 addresses only.
-6 Forces ssh to use IPv6 addresses only.
-A Enables forwarding of the authentication agent con-
nection. This
can also be specified on a per-host basis in a con-
figuration
file.
Agent forwarding should be enabled with caution.
Users with the
ability to bypass file permissions on the remote
host (for the
agent's Unix-domain socket) can access the local
agent through
the forwarded connection. An attacker cannot obtain
key material
from the agent, however they can perform operations
on the keys
that enable them to authenticate using the identi-
ties loaded into
the agent.
-a Disables forwarding of the authentication agent con-
nection.
-b bind_address
Use bind_address on the local machine as the source
address of
the connection. Only useful on systems with more
than one ad-
dress.
-C Requests compression of all data (including stdin,
stdout,
stderr, and data for forwarded X11 and TCP/IP con-
nections). The
compression algorithm is the same used by gzip(1),
and the
``level'' can be controlled by the CompressionLevel
option for
protocol version 1. Compression is desirable on mo-
dem lines and
other slow connections, but will only slow down
things on fast
networks. The default value can be set on a host-
ferent keys. It is believed to be secure. blowfish
is a fast
block cipher; it appears very secure and is much
faster than
3des. des is only supported in the ssh client for
interoperabil-
ity with legacy protocol 1 implementations that do
not support
the 3des cipher. Its use is strongly discouraged
due to crypto-
graphic weaknesses. The default is ``3des''.
For protocol version 2 cipher_spec is a comma-sepa-
rated list of
ciphers listed in order of preference. The support-
ed ciphers are
``3des-cbc'', ``aes128-cbc'', ``aes192-cbc'',
``aes256-cbc'',
``aes128-ctr'', ``aes192-ctr'', ``aes256-ctr'',
``arcfour128'',
``arcfour256'', ``arcfour'', ``blowfish-cbc'', and
``cast128-cbc''. The default is
``aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,ar-
cfour128,
arcfour256,arc-
four,aes192-cbc,aes256-cbc,aes128-ctr,
aes192-ctr,aes256-ctr''
-D port
Specifies a local ``dynamic'' application-level port
forwarding.
This works by allocating a socket to listen to port
on the local
side, and whenever a connection is made to this
port, the connec-
tion is forwarded over the secure channel, and the
application
protocol is then used to determine where to connect
to from the
remote machine. Currently the SOCKS4 and SOCKS5
protocols are
supported, and ssh will act as a SOCKS server. Only
root can
forward privileged ports. Dynamic port forwardings
can also be
specified in the configuration file.
-e ch | ^ch | none
Sets the escape character for sessions with a pty
(default: `~').
The escape character is only recognized at the be-
figuration file is given on the command line, the
system-wide
configuration file (/etc/ssh/ssh_config) will be ig-
nored. The
default for the per-user configuration file is
~/.ssh/config.
-f Requests ssh to go to background just before command
execution.
This is useful if ssh is going to ask for passwords
or passphras-
es, but the user wants it in the background. This
implies -n.
The recommended way to start X11 programs at a re-
mote site is
with something like ssh -f host xterm.
-g Allows remote hosts to connect to local forwarded
ports.
-I smartcard_device
Specifies which smartcard device to use. The argu-
ment is the de-
vice ssh should use to communicate with a smartcard
used for
storing the user's private RSA key.
-i identity_file
Selects a file from which the identity (private key)
for RSA or
DSA authentication is read. The default is
~/.ssh/identity for
protocol version 1, and ~/.ssh/id_rsa and
~/.ssh/id_dsa for pro-
tocol version 2. Identity files may also be speci-
fied on a per-
host basis in the configuration file. It is possi-
ble to have
multiple -i options (and multiple identities speci-
fied in config-
uration files).
-k Disables forwarding (delegation) of GSSAPI creden-
tials to the
server.
-L [bind_address:]port:host:hostport
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 by allocating a socket to listen to port on
Only the
superuser can forward privileged ports. By default,
the local
port is bound in accordance with the GatewayPorts
setting. How-
ever, an explicit bind_address may be used to bind
the connection
to a specific address. The bind_address of ``local-
host'' indi-
cates that the listening port be bound for local use
only, while
an empty address or `*' indicates that the port
should be avail-
able from all interfaces.
-l login_name
Specifies the user to log in as on the remote ma-
chine. This also
may be specified on a per-host basis in the configu-
ration file.
-M Places the ssh client into ``master'' mode for con-
nection shar-
ing. Refer to the description of ControlMaster in
ssh_config(5)
for details.
-m mac_spec
Additionally, for protocol version 2 a comma-sepa-
rated list of
MAC (message authentication code) algorithms can be
specified in
order of preference. See the MACs keyword for more
information.
-N Do not execute a remote command. This is useful for
just for-
warding ports (protocol version 2 only).
-n Redirects stdin from /dev/null (actually, prevents
reading from
stdin). This must be used when ssh is run in the
background. A
common trick is to use this to run X11 programs on a
remote ma-
chine. For example, ssh -n shadows.cs.hut.fi emacs
& will start
an emacs on shadows.cs.hut.fi, and the X11 connec-
tion will be au-
tomatically forwarded over an encrypted channel.
The ssh program
will be put in the background. (This does not work
-o option
Can be used to give options in the format used in
the configura-
tion file. This is useful for specifying options
for which there
is no separate command-line flag. For full details
of the op-
tions listed below, and their possible values, see
ssh_config(5).
AddressFamily
BatchMode
BindAddress
ChallengeResponseAuthentication
CheckHostIP
Cipher
Ciphers
ClearAllForwardings
Compression
CompressionLevel
ConnectionAttempts
ConnectTimeout
ControlMaster
ControlPath
DynamicForward
EscapeChar
ForwardAgent
ForwardX11
ForwardX11Trusted
GatewayPorts
GlobalKnownHostsFile
GSSAPIAuthentication
GSSAPIDelegateCredentials
HashKnownHosts
Host
HostbasedAuthentication
HostKeyAlgorithms
HostKeyAlias
HostName
IdentityFile
IdentitiesOnly
KbdInteractiveDevices
LocalForward
LogLevel
MACs
NoHostAuthenticationForLocalhost
NumberOfPasswordPrompts
PasswordAuthentication
Port
PreferredAuthentications
Protocol
VerifyHostKeyDNS
XAuthLocation
-p port
Port to connect to on the remote host. This can be
specified on
a per-host basis in the configuration file.
-q Quiet mode. Causes all warning and diagnostic mes-
sages to be
suppressed.
-R [bind_address:]port:host:hostport
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 by allocating a socket to listen to port on
the remote
side, and whenever a connection is made to this
port, the connec-
tion is forwarded over the secure channel, and a
connection is
made to host port hostport from the local machine.
Port forwardings can also be specified in the con-
figuration file.
Privileged ports can be forwarded only when logging
in as root on
the remote machine. IPv6 addresses can be specified
by enclosing
the address in square braces or using an alternative
syntax:
[bind_address/]host/port/hostport.
By default, the listening socket on the server will
be bound to
the loopback interface only. This may be overriden
by specifying
a bind_address. An empty bind_address, or the ad-
dress `*', indi-
cates that the remote socket should listen on all
interfaces.
Specifying a remote bind_address will only succeed
if the serv-
er's GatewayPorts option is enabled (see sshd_con-
fig(5)).
-S ctl_path
Specifies the location of a control socket for con-
nection shar-
ing. Refer to the description of ControlPath and
-t Force pseudo-tty allocation. This can be used to
execute arbi-
trary screen-based programs on a remote machine,
which can be
very useful, e.g., when implementing menu services.
Multiple -t
options force tty allocation, even if ssh has no lo-
cal tty.
-V Display the version number and exit.
-v Verbose mode. Causes ssh to print debugging mes-
sages about its
progress. This is helpful in debugging connection,
authentica-
tion, and configuration problems. Multiple -v op-
tions increase
the verbosity. The maximum is 3.
-X Enables X11 forwarding. This can also be specified
on a per-host
basis in a configuration file.
X11 forwarding should be enabled with caution.
Users with the
ability to bypass file permissions on the remote
host (for the
user's X authorization database) can access the lo-
cal X11 display
through the forwarded connection. An attacker may
then be able
to perform activities such as keystroke monitoring.
For this reason, X11 forwarding is subjected to X11
SECURITY ex-
tension restrictions by default. Please refer to
the ssh -Y op-
tion and the ForwardX11Trusted directive in ssh_con-
fig(5) for
more information.
-x Disables X11 forwarding.
-Y Enables trusted X11 forwarding. Trusted X11 for-
wardings are not
subjected to the X11 SECURITY extension controls.
CONFIGURATION FILES
ssh may additionally obtain configuration data from a per-
user configura-
tion file and a system-wide configuration file. The file
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 manu-
ally copy any required authorization cookies).
HOME Set to the path of the user's home directory.
LOGNAME Synonym for USER; set for compatibility with sys-
tems that use
this variable.
MAIL Set to the path of the user's mailbox.
PATH Set to the default PATH, as specified when compil-
ing ssh.
SSH_ASKPASS
If ssh needs a passphrase, it will read the
passphrase from the
current terminal if it was run from a terminal. If
ssh does not
have a terminal associated with it but DISPLAY and
SSH_ASKPASS
are set, it will execute the program specified by
SSH_ASKPASS
and open an X11 window to read the passphrase.
This is particu-
larly useful when calling ssh from a .xsession or
related
script. (Note that on some machines it may be nec-
essary to
redirect the input from /dev/null to make this
work.)
SSH_AUTH_SOCK
Identifies the path of a unix-domain socket used to
communicate
with the agent.
SSH_CONNECTION
Identifies the client and server ends of the con-
nection. The
variable contains four space-separated values:
client ip-ad-
dress, client port number, server ip-address and
server port
number.
SSH_ORIGINAL_COMMAND
it was set when the daemon was started (i.e., the
daemon passes
the value on to new connections).
USER Set to the name of the user logging in.
Additionally, ssh reads ~/.ssh/environment, and adds lines
of the format
``VARNAME=value'' to the environment if the file exists and
if users are
allowed to change their environment. For more information,
see the
PermitUserEnvironment option in sshd_config(5).
FILES
~/.ssh/known_hosts
Records host keys for all hosts the user has logged
into that are
not in /etc/ssh/ssh_known_hosts. See sshd(8).
~/.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.
These files contain sensitive data and should be
readable by the
user but not accessible by others (read/write/exe-
cute). Note
that ssh ignores a private key file if it is acces-
sible by oth-
ers. It is possible to specify a passphrase when
generating the
key; the passphrase will be used to encrypt the sen-
sitive part of
this file using 3DES.
~/.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
~/.ssh/identity.pub file should be added to the file
~/.ssh/authorized_keys on all machines where the us-
er wishes to
log in using protocol version 1 RSA authentication.
The contents
of the ~/.ssh/id_dsa.pub and ~/.ssh/id_rsa.pub file
should be
added to ~/.ssh/authorized_keys on all machines
where the user
wishes to log in using protocol version 2 DSA/RSA
the potential for abuse, this file must have strict
permissions:
read/write for the user, and not accessible by oth-
ers.
~/.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
sshd(8) manual page. In the simplest form the for-
mat is the same
as the .pub identity files. This file is not highly
sensitive,
but the recommended permissions are read/write for
the user, and
not accessible by others.
/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): sys-
tem name, pub-
lic key and optional comment field. When different
names are
used for the same machine, all such names should be
listed, sepa-
rated by commas. The format is described in the
sshd(8) manual
page.
The canonical system name (as returned by name
servers) is used
by sshd(8) to verify the client host when logging
in; other names
are needed because ssh 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 au-
thentication.
/etc/ssh/ssh_config
Systemwide configuration file. The file format and
configuration
the host keys for HostbasedAuthentication. This
eliminates the
requirement that ssh be setuid root when that au-
thentication
method is used. By default ssh is not setuid root.
~/.rhosts
This file is used in RhostsRSAAuthentication and
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 parti-
tion, because sshd(8) reads it as root. Additional-
ly, 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 oth-
ers.
Note that sshd(8) allows authentication only in com-
bination with
client host key authentication before permitting log
in. If the
server machine does not have the client's host key
in
/etc/ssh/ssh_known_hosts, it can be stored in
~/.ssh/known_hosts.
The easiest way to do this is to connect back to the
client from
the server machine using ssh; this will automatical-
ly add the
host key to ~/.ssh/known_hosts.
~/.shosts
This file is used exactly the same way as .rhosts.
The purpose
for having this file is to be able to use RhostsR-
SAAuthentication
and HostbasedAuthentication authentication without
permitting lo-
thentication is required. This file should only be
writable by
root.
/etc/shosts.equiv
This file is processed exactly as /etc/hosts.equiv.
This file
may be useful to permit logins using ssh but not us-
ing
rsh/rlogin.
/etc/ssh/sshrc
Commands in this file are executed by ssh when the
user logs in
just before the user's shell (or command) is start-
ed. See the
sshd(8) manual page for more information.
~/.ssh/rc
Commands in this file are executed by ssh when the
user logs in
just before the user's shell (or command) is start-
ed. See the
sshd(8) manual page for more information.
~/.ssh/environment
Contains additional definitions for environment
variables, see
section ENVIRONMENT above.
DIAGNOSTICS
ssh exits with the exit status of the remote command or with
255 if an
error occurred.
SEE ALSO
gzip(1), rsh(1), scp(1), sftp(1), ssh-add(1), ssh-agent(1),
ssh-keygen(1), telnet(1), hosts.equiv(5), ssh_config(5),
ssh-keysign(8),
sshd(8)
T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne, and S. Lehti-
nen, SSH
Protocol Architecture, draft-ietf-secsh-architecture-12.txt,
January
2002, work in progress material.
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
Man(1) output converted with man2html