SSH2(1) SSH2 SSH2(1)
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] [-m MAC] [-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-key
gen2(1). See ssh-agent2(1) for information on how to use
public key authentication in conjunction with an authenti
cation agent.
If other authentication methods fail, ssh2 will prompt for
a password. Since all communications are encrypted, the
password 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 trans
parent 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 automati
cally forwarded to the remote side in such a way that any
X11 programs 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 connec
tions over the encrypted channel.
Ssh2 will also automatically set up the 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 connec
tions carry this cookie and replace it with the real
cookie when the connection is opened. The real authenti
cation 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 connec
tion to the agent is automatically forwarded to the remote
side unless disabled on the command line or in a configu
ration 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 con
taining the host public keys. When logging on to a host
for the first time, the host's public key is stored in 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 the password authentication
in order to prevent a Trojan horse from getting the user's
password. Another purpose of this mechanism is to prevent
man-in-the-middle attacks which could otherwise be used to
circumvent the encryption.
Ssh2 has built-in support for SOCKS version 4 for travers
ing 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 authen
tication. This option can also be specified in the
configuration file.
-F file
Specifies an alternative configuration file to use.
NOTE: $HOME/.ssh2/ssh2_config is still read,
options specified here will be used in addition to
those.
-t For tty allocation, ie. allocate a tty even if a
command 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
specified 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 configuration file.
-f [o] Fork into background after authentication. This
option can also be specified in the configuration
file. Implies '-S' and '-n'. With this option, ssh2
stays in the background, waiting for connections
indefinitely (it has to be killed for it to stop
listening). With an optional `o' argument, it goes
to ``one-shot'' mode, which means that once all
channels are closed, ssh2 exits.
-e char
Set the escape character. Use ``none'' to disable.
This option can also be specified in the configura
tion 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 configuration file. You can use blowfish,
twofish, cast, arcfour, and 3des.
-m MAC Select the MAC (Message Authentication Code) algo
rithm. Multiple -m options are allowed and a single
-m flag can have only one MAC. This option can also
be specified in the configuration 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. When
ever a connection is made to this port, the connec
tion is forwarded over the secure channel and a
connection is made to host:hostport from the remote
machine. Port forwardings 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 allocat
ing a socket to listen to port 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 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 specify options in the format used
in the configuration files. This is useful for
specifying options for which there are no separate
command-line flags. The option has the same format
as a line in the configuration file. Comment lines
are not currently accepted via this option.
-h Display a short help on command-line options.
CONFIGURATION FILES
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 effec
tive.
For format of ssh2_config, see ssh2_config(5).
ESCAPE SEQUENCES
Ssh2 supports escape sequeneces that enable you to have
some managability with the session. In order for any
escape sequences to take effect, you will need to have
entered a newline character (read: press return before
actually doing any of these). What you need to do after
that is manually enter the characters (for example, a new
line, a tidle ~, and the appropriate character for the
appropriate task).
~. Terminate the connection.
~^Z Suspend the session (press control-Z, not ^ and Z).
~~ Send the escape character.
~# List forwarded connections (Not yet implemented).
~- Disable the escape character's ability to cancel.
~& Backgroun ssh (when waiting for connections to ter
minate).
~? See a summary of escape sequences.
~r Initialiates rekeying manually.
~s Give all sorts of statistics on the connection,
including server and client version, compression,
PIPO (packets in, packets out), compression, public
key exchange algorithms, and symmetric ciphers.
Much more useful for troubleshooting.
~V Dump the client version number to stderr (useful
for troubleshooting).
ENVIRONMENT
Ssh2 will normally set the following environment vari
ables:
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 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 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 sys
tems using this variable.
MAIL Set to point the user's mailbox.
PATH Set to the default PATH, as specified when compil
ing ssh2 or, on some systems, /etc/environment or
/etc/default/login.
SSH_SOCKS_SERVER
If SOCKS is used, it is configured with this vari
able. The format of the variable is socks://user
name@socks_server:port/network/netmask,network/net
mask ... for example by setting environment vari
able SSH_SOCKS_SERVER to socks://mylo
gin@socks.ssh.com:1080/203.123.0.0/16,198.74.23.0/24
uses host socks.ssh.com port 1080 as your SOCKS
server if connection is attempted outside of net
works 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 compiling ssh2. The default value can be can
celled by setting SSH_SOCKS_SERVER to an empty
string, and overridden by setting SSH_SOCKS_SERVER
to a new value. If the SSH_SOCKS_SERVER variable
is set, it should almost always contain local loop
back network (127.0.0.0/8) as network that is con
nected directly.
SSH2_AUTH_SOCK
If this exists, it is used to indicate the path of
a unix-domain socket used to communicate with the
authentication agent (or its local representative).
SSH2_CLIENT
Identifies the client end of the connection. The
variable 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
arguments etc. from the other end. This does not
have to 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 com
mand. If the current session has no tty, this
variable is not set.
TZ The timezone variable is set to indicate the pre
sent timezone if it was set when the daemon was
started (the daemon passes the value to new connec
tions).
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 VAR
NAME=value to the environment. Some systems may have
still additional mechanisms for setting up the environ
ment, 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 acces
sible' for others. This file is created the first
time the program is run and it is updated automati
cally. The user should never need to read or mod
ify this file.
$HOME/.ssh2/ssh2_config
This is the per-user configuration file. The for
mat of this file is described above. This file is
used by the ssh2 client. This file does not usu
ally contain any sensitive information, but the
recommended permissions are 'read/write' for the
user, and
$HOME/.ssh2/identification
contains information on how the user wishes to
authenticate himself when contacting a specific
host.
The identification file has the same general syntax
as the configuration files. The following keywords
may be used:
IdKey This is followed by the filename of a private key
in the $HOME/.ssh2 directory used for identifica
tion 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 the $HOME/.ssh2 direc
tory. OpenPGP keys listed after this line are
expected to be found from this file. Keys identi
fied 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
may be used:
Key This is followed by the filename of a public key in
the $HOME/.ssh2 directory that is used for identi
fication 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 authenticated. 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 pub
lic 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 spec
ify TCP/IP and/or X11 forwardings, unless they are
explicitly prohibited.
$HOME/.ssh2/hostkeys/key_xxxx_yyyy.pub
These files are the public keys of the hosts you
connect to. These are updated automatically, unless
you have set StrictHostKeyChecking to "yes". If a
host's key changes, you should put here the new
key. (But don't do that, unless you can be sure the
key is valid, ie. that no man-in-the-middle attack
has occurred!) 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 the next
location to be checked. These files have to be
updated manually; no files are put here automati
cally.
$HOME/.rhosts
This file contains host-username pairs, separated
by a space, one per line. The given user on the
corresponding 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 addi
tion to validating the host name retrieved from
domain name servers. The file must be writable only
by the user; it is recommended that it not be
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 per
mitted 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, pro
vided that the client and server user names are the
same. Additionally, successful public key 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 practically grants the user root access.
The only valid use for user names should be in neg
ative 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. (This
is insecure, as the file is used also by the
r*-commands.) 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 pub
lickey 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-direc
tory.
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 settings 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 Corp
For more information, see http://www.ssh.com.
SEE ALSO
ssh2_config(5), sshd2(8), ssh-keygen2(1), ssh-agent2(1),
ssh-add2(1), scp2(1), sftp(1) rlogin(1), rsh(1), telnet(1)
SSH2 May 23, 2000 SSH2(1)