man pages for ssh2
SSH2 Last change: March 22, 2000
NAME
ssh2 - secure shell client (remote login program)
SYNOPSIS
ssh2 [-l login_name] hostname [command]
ssh2 [-l login_name] [-n] [+a] [-a] [+x] [-x] [-i file]
[-F file] [-t] [-v] [-d debug_level] [-V] [-q] [-f[o]]
[-e char] [-c cipher] [-p port] [-S] [-L port:host:hostport]
[-R port:host:hostport] [+C] [-C] [-o `option'] [-h]
[login_name@]hostname[#port] [command]
DESCRIPTION
Ssh2 (Secure Shell) is a program for logging into a remote
machine and executing commands in a remote machine. It is
intended to replace rlogin and rsh, and provide secure,
encrypted communications between two untrusted hosts over an
insecure network. X11 connections and arbitrary TCP/IP
ports can also be forwarded over the secure channel.
Ssh2 connects and logs into the specified hostname. The
user must prove his identity to the remote machine using
some authentication method.
Public key authentication is based on the use of digital
signatures. Each user creates a public / private key pair
for authentication purposes. The server knows the user's
public key, and only the user has the private key. The
filenames of private keys that are used in authentication
are set in $HOME/.ssh2/identification. When the user tries
to authenticate himself, the server checks
$HOME/.ssh2/authorization for filenames of matching public
keys and sends a challenge to the user end. The user is
authenticated by signing the challenge using the private
key. See the FILES section below for more information on
identification and authorization files.
Private / public key pairs can be created with ssh-
keygen2(1). See ssh-agent2(1) for information on how to use
public key authentication in conjunction with an authentica-
tion agent.
If other authentication methods fail, ssh2 prompts for a
password. Since all communications are encrypted, the pass-
word will not be available for eavesdroppers.
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. All communication with the remote command or shell
will be automatically encrypted.
If no pseudo tty has been allocated, the session is tran-
sparent and can be used to reliably transfer binary data.
The session terminates when the command or shell in 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 ssh2.
If the user is using X11 (the DISPLAY environment variable
is set), the connection to the X11 display is automatically
forwarded to the remote side in such a way that any X11 pro-
grams started from the shell (or command) will go through
the encrypted channel, and the connection to the real X
server will be made from the local machine. The user should
not manually set DISPLAY. Forwarding of X11 connections can
be configured on the command line or in configuration files.
The DISPLAY value set by ssh2 will point to the server
machine, but with a display number greater than zero. This
is normal, and happens because ssh2 creates a "proxy" X
server on the server machine for forwarding the connections
over the encrypted channel.
Ssh2 will also automatically set up Xauthority data on the
server machine. For this purpose, it will generate a random
authorization cookie, store it in the Xauthority data on the
server, and verify that any forwarded connections carry this
cookie and replace it with the real cookie when the connec-
tion is opened. The real authentication cookie is never
sent to the server machine (and no cookies are sent in the
plain).
If the user is using an authentication agent, the connection
to the agent is automatically forwarded to the remote side
unless disabled on command line or in a configuration file.
Forwarding of arbitrary TCP/IP connections over the secure
channel can be specified either on the command line or in a
configuration file. TCP/IP forwarding can be used for
secure connections to electronic purses or for going through
firewalls.
Ssh2 automatically maintains and checks a database contain-
ing public keys of hosts. When logging on to a host for the
first time, the host's public key is stored to a file
.ssh2/hostkey_PORTNUMBER_HOSTNAME.pub in the user's home
directory. If a host's identification changes, ssh2 issues a
warning and disables password authentication to prevent a
Trojan horse from getting the user's password. Another pur-
pose of this mechanism is to prevent man-in-the-middle
attacks which could otherwise be used to circumvent the
encryption.
Ssh2 has built-in support for SOCKS version 4 for traversing
firewalls. See ENVIRONMENT.
OPTIONS
-l login_name
Specifies the user for login to the remote machine.
-n Redirect input from /dev/null, ie. don't read stdin.
This option can also be specified in the configuration
file.
+a Enable authentication agent forwarding. (default)
-a Disable authentication agent forwarding.
+x Enable X11 connection forwarding. (default)
-x Disable X11 connection forwarding.
-i file
Specifies the identity file for public key authentica-
tion. This option can also be specified in the confi-
guration file.
-F file
Specifies an alternative configuration file to use.
NOTE: $HOME/.ssh2/ssh2_config is still read, options
specified here will be in addition to those.
-t For tty allocation, ie. allocate a tty even if a com-
mand is given. This option can also be specified in the
configuration file.
-v Enable verbose mode. Display verbose debugging mes-
sages. Equal to `-d 2'. This option can also be speci-
fied in the configuration file.
-d debug_level
Print extensive debug information to stderr.
debug_level is either a number, from 0 to 99, where 99
specifies that all debug information should be
displayed, or a comma-separated list of assignments
"ModulePattern=debug_level".
-V Display version string.
-q Make ssh2 quiet, so that it doesn't display any warning
messages. This option can also be specified in the con-
figuration file.
-f [o]
Fork into background after authentication. This option
can also be specified in the configuration file.
Implies '-S'. With this option, ssh2 stays in the back-
ground, waiting for connections indefinitely (it has to
be killed for it to stop listening). With optional `o'
argument, goes to ``one-shot'' mode, which means that
once all channels are closed, ssh2 exits.
-e char
Set escape character. Use ``none'' to disable. This
option can also be specified in the configuration file.
(default; ~)
-c cipher
Select the encryption algorithm. Multiple -c options
are allowed and a single -c flag can have only one
cipher. This option can also be specified in the confi-
guration file.
-p port
Port to connect to on the remote host. This option can
also be specified in the configuration file.
-S Don't request a session channel. This can be used with
port-forwarding requests if a session channel (and tty)
isn't needed, or the server doesn't give one.
-L 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
be listened port on the local side, and whenever a con-
nection is made to this port, the connection is for-
warded over the secure channel and a connection is made
to host:hostport from the remote machine. Port for-
wardings can also be specified in the configuration
file. Only root can forward privileged ports.
-R 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 con-
nection is made to this port, the connection is for-
warded over the secure channel, and a connection is
made to host:hostport from the local machine.
Privileged ports can be forwarded only when logging in
as root on the remote machine.
+C Enable compression.
-C Disable compression. (default)
-o 'option'
Can be used to give options in the format used in the
configuration files. 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
configuration file. Comment lines are not currently
accepted via this option.
-h Display short help on command-line options.
Ssh2 obtains configuration data from the following sources
(in this order): system's global configuration file (typi-
cally /etc/ssh2/ssh2_config), user's configuration file
($HOME/.ssh2/ssh2_config) and the command line options. For
each parameter, the last obtained value will be effective.
The configuration file has the following format:
`expression:' denotes the start of a per-host confi-
guration block, where `expression' is an arbitrary
string which distinguishes this block from others. The
`expression' can contain wildcards. It will be compared
to the hostname obtained from the command-line, and if
it matches, the block will be evaluated. Evaluation
stops at the next `expression:' statement. If more than
one match is found, all will be evaluated and the last
obtained values for parameters will be effective. Note
that `expression' doesn't have to be a real hostname,
as long as the `expression' block contains a "Host"
configuration parameter, where the real hostname to
connect is defined.
Empty lines and lines starting with '#' are ignored as
comments.
Otherwise a line is of the format "keyword arguments".
Note that it is possible to enclose arguments in
quotes, and use the standard C convention. The possi-
ble keywords and their meanings are as follows (note
that the configuration files are case-sensitive, but
keywords are case-insensitive):
AuthorizationFile
Specifies the name of the user's authorization file.
BatchMode
If set to "yes", ssh2 disables password/passhphrase
querying. This is useful in scripts and other batch
jobs where you don't have a user to supply the pass-
word. If the "StrictHostKeyChecking" parameter is set
to "ask", ssh2 assumes a "no" answer to queries (this
is because ssh doesn't even try to get user input when
invoked with "BatchMode yes"). The argument must be
"yes" or "no".
Ciphers
Specifies the ciphers to use for encrypting the ses-
sion. Currently, des, 3des, blowfish, idea, arcfour and
twofish are supported, of which des, 3des, arcfour,
blowfish and twofish are in all distributions. Multiple
ciphers can be specified as a comma-separated list.
Special values to this option are any, anystd, that
allows only standard (see below) ciphers, and anycipher
that allows either any available cipher or excludes
nonencrypting cipher mode none but allows all others.
anystdcipher is the same as above, but includes only
those ciphers mentioned in the IETF-SecSH-draft
(excluding 'none').
Compression
Specifies whether to use compression. The argument must
be "yes" or "no".
DontReadStdin
Redirect input from /dev/null, ie. don't read stdin.
The argument must be "yes" or "no".
EscapeChar
Sets the escape character (default: ~). The escape
character can also be set on the command line. The
argument should be a single character, '^' followed by
a letter, or "none" to disable the escape character
entirely (making the connection transparent for binary
data).
ForcePTTYAllocation
For tty allocation. Ie. allocate a tty even if a com-
mand is given. The argument must be "yes" or "no".
(not yet implemented)
ForwardAgent
Specifies whether the connection to the authentication
agent (if any) will be forwarded to the remote machine.
The argument must be "yes" or "no".
ForwardX11
Specifies whether X11 connections will be automatically
redirected over the secure channel and DISPLAY set. The
argument must be "yes" or "no".
GatewayPorts
Specifies that also remote hosts may connect to locally
forwarded ports. The argument must be "yes" or "no".
The default is "no". (not yet implemented)
GoBackground
Requests ssh2 to go to background after authentication
is done and forwardings have been established. This is
useful if ssh2 is going to ask for passwords or
passphrases, but the user wants it in the background.
The argument must be "yes", "no" or "oneshot". With
"oneshot", ssh2 behaves the same way as with `-f o'
commandline arguments. The default is "no".
Host Specifies the real host name to log into. With `expres-
sion' above, this can be used to specify nicknames or
abbreviations for hosts. The default is the name given
on the command line. Numeric IP addresses are also per-
mitted (both on the command line and in HostName
specifications).
IdentityFile
Specifies the name of the user's identification file.
KeepAlive
Specifies whether the system should send keepalive mes-
sages to the other side. 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 find this annoying.
The default is "yes" (to send keepalives), and the
client will notice if the network goes down or the
remote host dies. This is important when using
scripts, and many users want it too.
To disable keepalives, the value should be set to "no"
in both the server and the client configuration files.
LocalForward
Specifies that a TCP/IP port on the local machine is
forwarded over the secure channel to given host:port
from the remote machine. The argument should be
enclosed in double-quotes (""). The argument format is
port:remotehost:remoteport .
NoDelay
If "yes", enable socket option TCP_NODELAY. The argu-
ment must be "yes" or "no". Default is "no".
PasswordPrompt
Sets the password prompt that the user sees when con-
necting to a host. Variables '%U' and '%H' can be used
to give the user's login name and host, respectively.
Port Specifies the port number to connect on the remote
host. The default port number is 22.
QuietMode
Quiet mode. Causes all warnings and diagnostic messages
to be suppressed. Only fatal errors are displayed. The
argument must be "yes" or "no".
RandomSeedFile
Specifies the name of the user's randomseed file.
RemoteForward
Specifies that a TCP/IP port on the remote machine is
forwarded over the secure channel to given host:port
from the local machine. The argument should be
enclosed in double-quotes (""). The argument format is
port:remotehost:remoteport .
Ssh1AgentCompatibility
Specifies whether to forward also SSH1 agent connec-
tion. Legal values for this option are "none", "tradi-
tional" and "ssh2". With value "none" (default), the
SSH1 agent connection is not forwarded at all. With
value "traditional", the SSH1 agent connection is for-
warded transparently like in SSH1. Value "traditional"
can always be used, but it constitutes a security risk,
because the agent does not get the information about
the forwarding path. Value "ssh2" makes SSH1 agent
forwarding similar to SSH2 agent forwarding. With this
mode the agent gets the information about the agent
forwarding path. Note that value "ssh2" can only be
used if you use ssh-agent2 in SSH1 compatibility mode.
"yes" or "no".
Ssh1Compatibility
Specifies whether to use SSH1 compatibility code. With
this option, ssh1 is executed when the server supports
only SSH 1.x protocols. The argument must be "yes" or
"no".
Ssh1Path
Specifies the path to ssh1 client, which is executed if
the server supports only SSH 1.x protocols. The argu-
ments for ssh2 are passed to the ssh1 client.
StrictHostKeyChecking
If this flag is set to "yes", ssh2 will never automati-
cally add host keys to the $HOME/.ssh2/hostkeys direc-
tory, and will refuse to connect 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 the necessary keys in
/etc/ssh2/hostkeys and you frequently connect new
hosts. Basically this option forces the user to manu-
ally add any new hosts. Normally this option is set to
"ask", and new hosts will automatically be added to the
known host files after you have confirmed you really
want to do that. If this value is set to "no" then new
host will automatically be added to the known host
files. The host keys of known hosts will be verified
automatically in either case. If this value is set to
"ask", the user also has the option to change the key
on the disk on the fly.
The argument must be "yes", "no" or "ask".
User Specifies the user to log in as. This can be useful if
you have a different user name in different machines.
This saves the trouble of having to remember to give
the user name on the command line.
VerboseMode
Verbose mode. Causes ssh2 to print debugging messages
about its progress. This is helpful when debugging con-
nection, authentication, and configuration problems.
Ssh2 will normally set the following environment variables:
DISPLAY
The DISPLAY variable indicates the location of the X11
server. It is automatically set by ssh2 to point to a
value of the form "hostname:n" where hostname indicates
the host where the shell runs, and n is an integer >=
1. Ssh2 uses this special value to forward X11 connec-
tions over the secure channel. The user should nor-
mally not set DISPLAY explicitly, as that will render
the X11 connection insecure (and will require the user
to manually copy any required authorization cookies).
HOME Set to the path of the user's home directory.
LOGNAME
Synonym for USER; set for compatibility with systems
using this variable.
MAIL Set to point the user's mailbox.
PATH Set to the default PATH, as specified when compiling
ssh2 or, on some systems, /etc/environment or
/etc/default/login.
SSH_SOCKS_SERVER
If SOCKS is used, it is configured with this variable.
The format of the variable is
socks://username@socks_server:port/network/netmask,network/netmask
... for example by setting environment variable
SSH_SOCKS_SERVER to
socks://mylogin@socks.ssh.fi:1080/203.123.0.0/16,198.74.23.0/24
uses host socks.ssh.fi port 1080 as your SOCKS server
if connection is attempted outside of networks
203.123.0.0 (16 bit domain) and 198.74.23.0 (8 bit
domain) which are connected directly.
A default value for SSH_SOCKS_SERVER variable can be
specified at compile time by specifying --with-socks-
server=VALUE on the configure command line when compil-
ing ssh2. The default value can be cancelled by setting
SSH_SOCKS_SERVER to an empty string, and overridden by
setting SSH_SOCKS_SERVER to a new value. If
SSH_SOCKS_SERVER variable is set, it should almost
always contain local loopback network (127.0.0.0/8) as
network that is connected directly.
SSH2_AUTH_SOCK
if exists, is used to indicate the path of a unix-
domain socket used to communicate with the authentica-
tion agent (or its local representative).
SSH2_CLIENT
Identifies the client end of the connection. The vari-
able contains three space-separated values: client ip-
address, client port number, and server port number.
SSH2_ORIGINAL_COMMAND
This will be the original command given to ssh2 if a
forced command is run. It can be used to fetch argu-
ments etc. from the other end. This need not be a real
command, it can be a name of a file, device, parameters
or anything else.
SSH2_TTY
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, this variable is not set.
TZ The timezone variable is set to indicate the present
timezone if it was set when the daemon was started (the
daemon passes the value to new connections).
USER Set to the name of the user logging in.
Additionally, ssh2 reads /etc/environment and
$HOME/.ssh2/environment, and adds lines of the format
VARNAME=value to the environment. Some systems may have
still additional mechanisms for setting up the environment,
such as /etc/default/login on Solaris.
FILES
$HOME/.ssh2/random_seed
Used for seeding the random number generator. This
file contains sensitive data and its permissions should
be 'read/write' for the user and 'not accessible' for
others. This file is created the first time the program
is run and updated automatically. The user should
never need to read or modify this file.
$HOME/.ssh2/ssh2_config
This is the per-user configuration file. The format of
this file is described above. This file is used by the
ssh2 client. This file does not usually contain any
sensitive information, but the recommended permissions
are 'read/write' for the user, and 'not accessible' for
others.
$HOME/.ssh2/identification
contains information on how the user wishes to authen-
ticate himself when contacting a specific host.
The identification file has the same general syntax as
the configuration files. The following keywords can be
used:
IdKey
This is followed by the filename of a private key in
the $HOME/.ssh2 directory used for identification when
contacting a host. If there are more than one IdKeys ,
they are tried in the order that they appear in the
identification file.
PgpSecretKeyFile
This is followed by the filename of the user's OpenPGP
private keyring in $HOME/.ssh2 directory. OpenPGP keys
listed after this line are expected to be found from
this file. Keys identified with "IdPgpKey*"-keywords
are used like ones identified with "IdKey"-keyword.
IdPgpKeyName
This is followed by the OpenPGP key name of the key in
PgpSecretKeyFile file.
IdPgpKeyFingerprint
This is followed by the OpenPGP key fingerprint of the
key in PgpSecretKeyFile file.
IdPgpKeyFingerprint
This is followed by the OpenPGP key id of the key in
PgpSecretKeyFile file.
$HOME/.ssh2/authorization
contains information on how the server will verify the
identity of an user.
The authorization file has the same general syntax as
the configuration files. The following keywords can be
used:
Key This is followed by the filename of a public key in the
$HOME/.ssh2 directory that is used for identification
when contacting the host. If there are more than one
key, they are all acceptable for login.
PgpPublicKeyFile
This is followed by the filename of the user's OpenPGP
public keyring in $HOME/.ssh2 directory. OpenPGP keys
listed after this line are expected to be found from
this file. Keys identified with "PgpKey*"-keywords are
used like ones identified with "Key"-keyword.
PgpKeyName
This is followed by the OpenPGP key name.
PgpKeyFingerprint
This is followed by the OpenPGP key fingerprint.
PgpKeyId
This is followed by the OpenPGP key id.
Command
This keyword, if used, must follow the "Key" or
"PgpKey*" -keyword above. This is used to specify a
"forced command", that will be executed on the server
side instead of anything else when the user is authen-
ticated. The command supplied by the user (if any) is
put in the environment variable
"SSH2_ORIGINAL_COMMAND". The command is run on a pty if
the connection requests a pty; otherwise it is run
without a tty. A quote may be included in the command
by quoting it with a backslash. This option might be
useful for restricting certain public keys to perform
just a specific operation. An example might be a key
that permits remote backups but nothing else. Notice
that the client may specify TCP/IP and/or X11 forward-
ings unless they are explicitly prohibited.
$HOME/.ssh2/hostkeys/key_xxxx_yyyy.pub
These file are the public keys of the hosts you connect
to. These update automatically, unless you have set
StrictHostKeyChecking to "yes". If a host's key
changes, you should put here the new key. (Do not do
that, unless you can be sure that the key is valid, ie.
that there has been no man-in-the-middle attack!) The
"xxxx" is the port on the server, where sshd2 runs, and
the "yyyy" is the host (specified on command-line).
/etc/ssh2/hostkeys/key_xxxx_yyyy.pub
If a host key is not found from the users
"$HOME/.ssh2/hostkeys" directory, this is looked next.
These files have to be updated manually; no files are
put here automatically.
$HOME/.rhosts
This file contains host-username pairs, separated by a
space, one per line. The given user on the correspond-
ing host is permitted to log in without password. The
same file is used by rlogind and rshd. sshd2 differs
from rlogind and rshd in that it requires public host
key authentication in addition to validating the host
name retrieved from domain name servers. The file must
be writable only by the user; it is recommended that
the file is not accessible by others.
It is also possible to use netgroups in the file.
Either host or user name may be of the form +@groupname
to specify all hosts or all users in the group.
$HOME/.shosts
For ssh2, this file is exactly the same as for .rhosts.
However, this file is not used by rlogin and rshd, so
using this permits access using ssh2 only.
/etc/hosts.equiv
This file is used during .rhosts authentication. In
its simplest form, this file contains host names, one
per line. Users on those hosts are permitted to log in
without a password, provided that they have the same
user name on both machines. The host name may also be
followed by a user name; such users are permitted to
log in as any user on this machine (except root).
Additionally, the syntax +@group can be used to specify
netgroups. Negated entries start with '-'.
If the client host/user is successfully matched in this
file, login is automatically permitted, provided the
client and server user names are the same. Addition-
ally, successful RSA host authentication is normally
required. This file must be writable only by root; it
is recommended that it be world-readable.
Warning: It is almost never a good idea to use user
names in hosts.equiv. Note that this really means that
the named user(s) can log in as anybody, including bin,
daemon, adm, and other accounts that own critical
binaries and directories. Using a user name practi-
cally grants the user root access. The only valid use
for user names should be in negative entries. Note
that this warning also applies to rsh/rlogin.
/etc/shosts.equiv
This is processed exactly as /etc/hosts.equiv. However,
this file may be useful in environments that want to
run both rsh/rlogin and ssh2.
$HOME/.ssh2/knownhosts/xxxxyyyy.pub
These are the public hostkeys of hosts that a user
wants to log from using "hostbased"-authentication
(equivalent with ssh1's RhostsRSAAuthentication). Also,
a user has to set up her/his $HOME/.shosts (which only
ssh uses) or $HOME/.rhosts file (insecure, as it is
used by the r*-commands also). If username is the same
in both hosts, it is adequate to put the public hostkey
to /etc/ssh2/knownhosts and add the host's name to
/etc/shosts.equiv (or /etc/hosts.equiv).
xxxx denotes the hostname (FQDN) and yyyy the publickey
algorithm of the key.
For example, zappa.foo.fi's hostkey algorithm is ssh-
dss. The hostkey would be named "zappa.foo.fi.ssh-
dss.pub" in the knownhosts-directory.
Possible names for publickey-algorithms are "ssh-dss"
and "ssh-rsa" (without the quotes).
/etc/ssh2/knownhosts/xxxxyyyy.pub
As above, but system-wide. These can be overridden by
the user by putting a file with the same name to
her/his $HOME/.ssh2/knownhosts directory.
AUTHORS
SSH Communications Security Ltd.
For more information, see http://www.ssh.fi.
SEE ALSO
sshd2(8), ssh-keygen2(1), ssh-agent2(1), ssh-add2(1),
scp2(1), sftp(1) rlogin(1), rsh(1), telnet(1)