 |
|
ssh2
SSH2(1) SSH2 SSH2(1)
NAME
ssh2 - Secure Shell client (remote login program)
SYNOPSIS
ssh2 [-l username] host [command]
ssh2 [-l username] [-n] [+a] [-a] [+x] [+X] [-x] [-i file]
[-F file] [-t] [--verbose] [-v] [-d debug_level] [--ver-
sion] [-V] [-q] [-f[o]] [-e char] [-c cipher] [-m MAC]
[-p port] [-S] [-L [protocol/][localhost:]port:host:host-
port] [-L socks/port] [-R [protocol/][local-
host:]port:host:hostport] [-g] [+g] [+C] [-C]
[-E provider] [-I initstring] [-4] [-6] [-1 [ti]]
[-o 'option'] [-h] [--help] [username@]host[#port] [com-
mand]
DESCRIPTION
ssh2 (Secure Shell) is a program for logging in on a
remote machine and executing commands on a remote machine.
It is intended for replacing rlogin and rsh, and providing
secure, encrypted communication channels between two hosts
over an unsecured network. X11 connections and arbitrary
TCP/IP ports can also be forwarded over such secure chan-
nels.
ssh2 connects to and logs in on the specified host. The
users must prove their identities 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, the server checks $HOME/.ssh2/authoriza-
tion for filenames of matching public keys and sends a
challenge to the user end. The user is authenticated by
signing the challenge with 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 communication is 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 in
on the machine and gives the user a normal shell. 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 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 X11 con-
nections can be configured on the command line or in con-
figuration 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 authentication 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 public host keys. When logging in on a host
for the first time, the host's public key is stored in the
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 man-in-the-middle attacks which could
otherwise be used to circumvent the encryption or steal
passwords.
ssh2 has built-in support for SOCKS versions 4 and 5 for
traversing firewalls. See the ENVIRONMENT section. Note
that the SOCKS5 support does not include support for the
SOCKS authentication methods.
OPTIONS
-l username
Logs in on the remote machine as user username.
-n Redirects input from /dev/null (i.e. does not read
stdin). This option can also be specified in the
configuration file.
+a Enables authentication agent forwarding (default).
-a Disables authentication agent forwarding.
+x Enables X11 connection forwarding (default). If X11
SECURITY extension is compiled in, treats the
client applications as UNTRUSTED (the effects of
this depend on your Xserver's security policy).
Binary distributions of SSH Tectia Client do not
include X11 security extensions. See TrustX11Appli-
cations in ssh2_config(5) for additional details.
+X As +x above, but if X11 SECURITY extension is com-
piled in, the client applications are treated as
TRUSTED.
-x Disables 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 additional configuration file to use.
Note: $HOME/.ssh2/ssh2_config is still read, but
options specified here will be overridden by file.
-t Tty allocation, that is, allocates a tty even if a
command is given. This option can also be speci-
fied in the configuration file.
-v,--verbose
Enables verbose mode. Displays verbose debugging
messages. Equivalent to -d 2. This option can
also be specified in the configuration file.
-d debug_level
Prints 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
of the format ModulePattern=debug_level, for exam-
ple "*=10,sshd2=2". This should be the first argu-
ment on the command line.
-V,--version
Displays version string.
-q Makes ssh2 quiet, so that it does not display any
warning messages. This option can also be speci-
fied in the configuration file.
-f[o] Forks 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 to stop listen-
ing). With an optional o argument, it goes to
'one-shot' mode, which means that once all channels
are closed, ssh2 exits.
-e char
Sets the escape character. Use 'none' to disable.
This option can also be specified in the configura-
tion file (default: ~).
-c cipher
Selects the encryption algorithm. Multiple -c
options are allowed, but a single -c flag can have
only one cipher. This option can also be specified
in the configuration file. Allowed values are aes,
blowfish, twofish, cast, arcfour, 3des, and des.
-m MAC Selects the MAC (Message Authentication Code) algo-
rithm. Multiple -m options are allowed, but a sin-
gle -m flag can have only one MAC. This option can
also be specified in the configuration file (see
ssh2_config(5) for a list of known algorithms).
-p port
Port to connect to on the remote host. This option
can also be specified in the configuration file.
-S Does not request a session channel. This can be
used with port-forwarding requests if a session
channel (and tty) is not needed, or the server does
not give one.
-L [protocol/][localhost:]port:host:hostport or
-L socks/[localhost:]port
The given port on the local (client) host is for-
warded to the given host and port on the remote
side. This allocates a listener port port on the
local side. Whenever a connection is made to this
listener, the connection is forwarded over the
secure channel and a connection is made to
host:hostport from the remote machine (this latter
connection will not be secure, it is a normal TCP
connection). Port forwarding can also be specified
in the configuration file.
Only root can forward privileged ports. Giving the
argument protocol enables protocol-specific for-
warding. The protocols implemented are tcp
(default, no special processing), ftp (temporary
forwarding is created for FTP data channels, effec-
tively securing the whole FTP session), and socks.
With socks, the ssh2 client will act as a SOCKS
server for other applications, creating forwards as
requested by the SOCKS transaction. This supports
both SOCKS4 and SOCKS5. For example, ssh2 supports
SOCKS5, so you can configure it to use your socks
forward by setting an appropriate value for the
SocksServer configuration option. See ssh2_con-
fig(5). Use it with care, as other clients may be
able to connect to the forwarded port as well
(depending on your localhost setting, and whether
the client machine has other users besides you). If
you are using it to ease traversing a firewall,
consult the administrator of the destination net-
work for the policy.
If localhost is given, forwarding listens only to
the interface that is bound to the address of the
given host. If it is omitted, all interfaces are
listening. Parameters localhost and host can
optionally be enclosed in square brackets [] to
allow semicolons in the parameters.
-R [protocol/][localhost:]port:host:hostport
Remote port forwarding. The given port on the
remote (server) host is forwarded to the given host
and port on the local side. This allocates a lis-
tener port port on the remote side, and whenever a
connection is made to this port, the connection is
forwarded over the secure channel and further to
host:hostport from the local machine (this latter
connection will not be secure, as it is a normal
TCP connection).
Privileged ports can be forwarded only when logging
in as root on the remote machine. Parameters
localhost and host can optionally be enclosed in
square brackets [] to allow semicolons in the
parameters. See option -L for details on protocol
and localhost.
-g Gateways ports, which means that also remote hosts
may connect to locally forwarded ports. Note the
logic of + and - in this option.
+g Does not gateway ports. Listens to tunneling con-
nections originating only from the localhost. Note
the logic of + and - in this option.
+C Enables compression.
-C Disables compression (default).
-E provider
Uses external key provider provider for accessing
external keys for user authentication. This feature
is only available when external key support is
included in the software. See ssh-externalkeys(5)
for further information.
-I initstring
Uses initialization string initstring for external
key provider for accessing external keys for user
authentication. This feature is only available when
external key support is included in the software.
See ssh-externalkeys(5) for further information.
-4 Uses IPv4 to connect.
-6 Uses IPv6 to connect.
-1[ti] Fallback to SSH1 protocol. Additional letter is
mandatory: i means internal emulation, t means tra-
ditional mechanism (call to ssh1 executable).
-o 'option'
Can be used to give options in the format used in
the configuration files. This is useful for speci-
fying options for which there is no separate com-
mand-line flag. The option has the same format as
a line in the configuration file. Comment lines
are not accepted. Where applicable, egrep regex
format is used.
-h,--help
Displays 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.
Commercial packages use a license file (typically
/etc/ssh2/license_ssh2.dat) to specify the type of the
license. For more information, see SSH Tectia Server
Administrator's Guide.
For the format of ssh2_config, see ssh2_config(5).
ESCAPE SEQUENCES
ssh2 supports escape sequences to manage a running ses-
sion. In order for an escape sequence to take effect, it
must be typed directly after a newline character (read:
press Enter first). The escape sequences are not dis-
played on screen during typing.
~. Terminates the connection.
~^Z Suspends the session (press control-Z, not ^ and
Z).
~~ Sends the escape character.
~# Lists forwarded connections.
~- Disables the escape character irrevocably.
~? Displays a summary of escape sequences.
~r Initiates rekeying manually.
~s Gives connection statistics, including server and
client version, packets in, packets out, compres-
sion, key exchange algorithms, public-key algo-
rithms, and symmetric ciphers.
~c Gives statistics for individual channels (data win-
dow sizes etc). This is for debugging purposes.
~V Dumps 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 host-
name indicates the host on which server and shell
are running, 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 unsecured (and will require the user to
manually copy any required authorization cookies).
HOME The user's home directory.
LOGNAME
Synonym for USER; set for compatibility with sys-
tems using this variable.
MAIL 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
The format of this option is specified in ssh2_con-
fig(5), option ProxyServer.
Use of that option overrides this environment vari-
able. Normally, use of an environment variable
would override the matching configuration option.
The reason for this exceptional behaviour is his-
torical.
A default value for SSH_SOCKS_SERVER can be speci-
fied at compile time by specifying --with-socks-
server=VALUE on the configure command line when
compiling 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.
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 and the like from the other end. This
does not have to be a real command, it can be the
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 time-zone variable is set to indicate the pre-
sent time zone if it was set when the daemon was
started (the daemon passes the value to new connec-
tions).
USER The name of the user.
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 'not accessible' for others.
$HOME/.ssh2/identification
Contains information on how the user wishes to
authenticate 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 is more than
one IdKey, 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 key ring in the $HOME/.ssh2 direc-
tory. OpenPGP keys listed after this line are
expected to be found in this file. Keys identified
with the IdPgpKey* keywords are used like the ones
identified with the 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.
IdPgpKeyId
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 is more
than one key, they are all acceptable for login.
PgpPublicKeyFile
This is followed by the filename of the user's
OpenPGP public key ring in the $HOME/.ssh2 direc-
tory. OpenPGP keys listed after this line are
expected to be found in this file. Keys identified
with the PgpKey* keywords are used like the ones
identified with the 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.
Options
This keyword, if used, must follow the Key or Pgp-
Key* keyword above. The various options are speci-
fied as a comma-separated list. See section PUB-
LIC-KEY OPTIONS for documentation of the options.
Command
This keyword is deprecated (though it still works),
use Options instead.
$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 the new key
here. Do not do this unless you can be sure the
key is valid, i.e. no man-in-the-middle attack has
occurred! xxxx is the port on the server where
sshd2 runs and yyyy is the host (specified on the
command line).
/etc/ssh2/hostkeys/key_xxxx_yyyy.pub
If a host key is not found in $HOME/.ssh2/hostkeys,
this is the next location to be checked. These
files have to be updated manually. No files are
put here automatically.
$HOME/.rhosts
This file contains host-username pairs, separated
by a whitespace, one per line. The given user is
permitted to log in from the given host without a
password. The same file is used by rlogind and
rshd. sshd2 differs from rlogind and rshd in that
it requires public host-key authentication from the
ssh2 server running on this host 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 it is not accessible
by others.
It is also possible to use netgroups in the file.
Either the hostname or username 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 hostnames,
one per line. Users on those hosts are permitted
to log in without a password, provided they have
the same username on both machines. The hostname
may also be followed by a username; 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 usernames are the
same. Additionally, successful host-based authen-
tication 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
usernames in hosts.equiv. Note that it 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
username practically grants the user root access.
The only valid use for usernames should be in nega-
tive entries. Note that this warning also applies
to rsh/rlogin.
/etc/shosts.equiv
This is processed exactly as /etc/hosts.equiv.
However, this file is not used by rlogin and rshd,
so using this permits access using ssh2 only.
$HOME/.ssh2/knownhosts/xxxxyyyy.pub
These are the public host keys of hosts that a user
wants to log in from using hostbased authentication
(equivalent to RhostsRSAAuthentication in ssh1).
Also, users have to set up their $HOME/.shosts
(only used by ssh) or $HOME/.rhosts files (inse-
cure, as it is used by the /fBr*/fR commands also).
If the username is the same on both hosts, it is
adequate to put the public host key to
/etc/ssh2/knownhosts and add the hostname to
/etc/shosts.equiv (or /etc/hosts.equiv).
xxxx denotes the host name (FQDN) and yyyy denotes
the public-key algorithm of the key.
For example, if the host-key algorithm of
zappa.foo.fi is ssh-dss, the host key is contained
in the file zappa.foo.fi.ssh-dss.pub in the known-
hosts directory.
Possible names for public-key algorithms are ssh-
dss and ssh-rsa.
/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 the $HOME/.ssh2/knownhosts directory.
|
PUBLIC-KEY OPTIONS
Options are specified as a comma-separated list.
allow-from and deny-from
In addition to public-key authentication, the
canonical name of the remote host must match the
given pattern(s). These parameters follow the
logic of {Allow,Deny}Hosts, described in detail in
sshd2_config(5). Specify one pattern per keyword;
multiple keywords can be used. See Examples below.
command="command"
This is used to specify a "forced command" that
will be executed on the server side instead of any-
thing 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. Quotes
may be used in the command if escaped with back-
slashes.
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 back-
ups but nothing else. Notice that the client may
specify TCP/IP and/or X11 forwarding, unless they
are explicitly prohibited (see no-port-forwarding).
environment="NAME=value"
Specifies that the string is to be added to the
environment when logging in using this key. Envi-
ronment variables set this way override other
default environment values. Multiple options of
this type are permitted.
idle-timeout=time
Sets idle timeout limit to time either in seconds
(s or nothing after the number), in minutes (m), in
hours (h), in days (d), or in weeks (w). If the
connection has been idle (all channels) this long,
the connection is closed.
no-port-forwarding
Forbids TCP/IP forwarding when this key is used for
authentication. Any port forward requests by the
client will return an error. This is useful in
combination with the command option.
no-x11-forwarding
Forbids X11 forwarding when this key is used for
authentication. Any X11 forward requests by the
client will return an error.
no-agent-forwarding
Forbids authentication agent forwarding when this
key is used for authentication.
no-pty Prevents tty allocation (a request to allocate a
pty will fail).
Examples
Options allow-from=".*\.niksula\.hut\.fi", deny-
from="pc\.niksula\.hut\.fi"
Options command="echo $SSH2_ORIGINAL_COMMAND $FOO $BAR",
environment="FOO=zuppa", environment="BAR=zappa", allow-
from="kungfoo.org", allow-from="linux.com"
EXIT VALUES
On normal execution, ssh2 exits with the status of the
command run. On successful runs this is normally 0 (zero).
If ssh2 encounters an error, you usually see the reason in
an error message. However, accommodating for that in e.g.
batch files is difficult, so some usual exit values for
ssh2 are documented here. Note that the command you have
run may also return the same exit values. Unfortunately,
little can be done to avoid this, as the exit value space
is so small (8 bits).
128 + signal number
This is returned if ssh2 encounters a fatal signal.
E.g. 143 would be returned for SIGTERM (signal num-
ber 15).
64 + disconnect code
This is returned on disconnect, clean or otherwise.
host not allowed to connect 1
protocol error 2
key exchange failed 3
reserved 4
MAC error 5
compression error 6
service not available 7
protocol version not supported 8
host key not verifiable 9
connection lost 10
by application 11
too many connections 12
auth cancelled by user 13
no more auth methods available 14
illegal user name 15
E.g. 74 would mean 'Connection lost'.
255 Returned on a call for ssh_fatal().
254 Usually means that ssh2 failed to exec(3) something
(generic catch-all in the libraries for failures to
fork(2) or exec(3)).
1 Generic error.
2 Connecting to remote host failed.
AUTHORS
SSH Communications Security Corp.
For more information, see http://www.ssh.com.
SEE ALSO
ssh2_config(5), sshd2(8), sshd2_config(5), ssh-keygen2(1),
ssh-agent2(1), ssh-add2(1), scp2(1), sftp2(1), rlogin(1),
rsh(1), telnet(1)
|
[Contents]
[Index]
[ Contact Information | Support | Feedback | SSH Home Page | SSH Products ]
Copyright © 2006 SSH Communications Security Corp.
This software is protected by international copyright laws. All rights reserved.
Copyright Notice
|
|
|
