ssh2(1)ssh2(1)NAME
ssh2, ssh - Secure Shell client remote login and command execution
application
SYNOPSISssh2 [-l login_name] hostname [command]
ssh2 [-l login_name] [-n] [+a] [-a] [+x] [+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 [protocol/]port:host:hostport] [-L socks/port]
[-R [protocol/]port:host:hostport] [-g] [+g] [+C] [-C] [-E provider]
[-I initstring] [-4] [-6] [-1 [ti]] [-o option] [-h] [login_name@]
hostname [port#] [command]
OPTIONS
Specifies the user for login to the remote system. Redirects input
from /dev/null (i.e., do not read stdin). This option also can be spec‐
ified in the configuration file. Enables authentication agent forward‐
ing (default). Disables authentication agent forwarding. Enables X11
connection forwarding (default). If the X11 SECURITY extension is com‐
piled, you treat the client applications as untrusted. See the
TrustX11Applications section in ssh2_config(4) for additional details.
Similar to +x, but the client applications are treated as trusted.
Disables X11 connection forwarding. Specifies the identity file for
public key authentication. This option also can be specified in the
configuration file. Specifies an alternative client configuration
file. The default client configuration file is the /etc/ssh2/ssh2_con‐
fig file. Each user can also have their own ssh2_config file in their
$HOME/.ssh2 directory, where $HOME is the name of the user's account.
The /etc/ssh2/ssh2_config file is read first, then the user's copy. The
last obtained value for a keyword is used. For tty allocation. For
example, allocate a tty even if a command is given. This option also
can be specified in the /etc/ssh2/ssh2_config configuration file.
Enables verbose mode. Displays verbose debugging messages. Equal to the
-d 2 option. This option also can be specified in the
/etc/ssh2/ssh2_config configuration file. Prints extensive debug
information to stderr. The debug_level argument is a number from 0 to
99, where 99 specifies that all debug information should be displayed,
or it is a comma-separated list of assignments. This should be the
first argument on the command line. Displays the version string. Dis‐
ables warning messages. This option also can be specified in the
/etc/ssh2/ssh2_config configuration file. Forks into the background
after authentication waiting indefinitely for connections. It must be
killed for it to stop listening. This option implies -S and -n. The o
argument specifies one-shot mode, which means that once all channels
are closed, the ssh2 command exits. This option also can be specified
in the /etc/ssh2/ssh2_config configuration file. Sets the escape char‐
acter. The default escape character is the tilde (~). Use none to dis‐
able the escape character. This option also can be specified in the
/etc/ssh2/ssh2_config configuration file. Specifies the encryption
algorithm to use. See the Ciphers keyword in the /etc/ssh2/sshd2_config
file and in the /etc/ssh2/ssh2_config file for more information. Mul‐
tiple -c options are allowed; a single -c option can specify only one
cipher. Allowed values are aes, blowfish, twofish, cast, arcfour,
3des, and des. Specifies the Message Authentication Code (MAC) algo‐
rithm. See the MACs keyword in the /etc/ssh2/sshd2_config file and in
the /etc/ssh2/ssh2_config file for more information. Multiple -m
options are allowed; a single -m option can have only one MAC. Speci‐
fies the port to connect to on the remote system. This option also can
be specified in the /etc/ssh2/ssh2_config file. Disables requests for
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. Fowards the given port on the local (client) system to the speci‐
fied host and port on the remote system. This allocates a socket to
listen to port on the local system. Whenever a connection is made to
this port, the connection is forwarded over the secure channel, and a
connection is made to the host:hostport argument from the remote sys‐
tem. Only root can forward privileged ports. The argument protocol
enables the protocol-specific forwarding. The protocols implemented are
tcp (default, no special processing) and ftp. Temporary forwardings
are created for ftp data channels, effectively securing the whole ftp
session. This option can also be specified in the /etc/ssh2/ssh2_config
file.
With socks, the Secure Shell client will act as a SOCKS server
for other applications, creating forwards as requested by the
SOCKS transaction. Secure Shell supports both SOCKS4 and SOCKS5,
so you can configure it to use your socks forward by setting an
approriate value for the SocksServer configuration option. See
ssh2_config(4). If the local host 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. Same as
above. Forwards the given port on the remote (server) system to
the specified host and port on the local system. This allocates
a socket to listen to port on the remote system. Whenever a con‐
nection is made to this port, the connection is forwarded over
the secure channel, and a connection is made to the host:host‐
port argument from the local system. Only root can forward
privileged ports on the remote system. The argument protocol
enables the protocol-specific forwarding. The protocols imple‐
mented are tcp (default, no special processing) and ftp. Tempo‐
rary forwardings are created for ftp data channels, effectively
securing the whole ftp session. This option also can be speci‐
fied in the /etc/ssh2/ssh2_config file. Allows gateway ports
(i.e., remote hosts can connect to locally forwarded ports).
Denies gateway ports. Enables compression. Disables compres‐
sion. (default) Uses an external key provider for user authenti‐
cation. This feature is only available when external key support
is included in the software. See ssh-externalkeys(4) for more
information. Uses an initialization string to access an exter‐
nal key provider for user authentication. This feature is
onlyavailable when external key support is included in the soft‐
ware. See ssh-externalkeys(4) for more information. Uses IPv4
to connect. Uses IPv6 to connect. Falls back to the SSH1 pro‐
tocol. An additional argument is mandatory. The i argument sig‐
nifies internal emulation, and the t argument indicates tradi‐
tional mechanism. Specifies an option in the format used in the
/etc/ssh2/ssh2_config file. This is useful for specifying an
option for which there is no command-line option. Comment lines
are not accepted with this option. Where aplication, use the
egrep regex format. Displays help on ssh2 command options.
DESCRIPTION
The ssh2 command creates a secure connection between a Secure Shell
client and server for remote log in and command execution. The ssh2
command is intended as a secure replacement for the rlogin and rsh com‐
mands. A secure connection provides client and server authentication,
user authentication, data encryption, data integrity, and nonrepudia‐
tion. X11 connections and arbitrary TCP/IP ports also can be forwarded
over these secure channels.
A Secure Shell client and server use public host keys to authenticate
each other. When a client connects to a server for the first time, the
user is prompted to accept a copy of the server's public host key. If
the user accepts the key, a copy of the server's public host key is
copied to the user's hostkeys directory on the client. The client uses
this public host key to authenticate the server on subsequent connects.
A Secure Shell server authenticates a user by using password authenti‐
cation, host-based authentication, or public key authentication.
Private and public key pairs can be created with ssh-keygen2. See ssh-
agent2 for information on how to use public-key authentication in con‐
junction with an authentication agent. If other authentication methods
fail, the ssh2 command will prompt for a password. The filenames of
private keys that are used in authentication are stored in
$HOME/.ssh2/identification. When the user tries to authenticate him‐
self, the server checks $HOME/.ssh2/authorization for filenames of
matching public keys and sends a challenge to the user. The user is
authenticated by signing the challenge using the private key.
After the user's identity has been proven, the Secure Shell server exe‐
cutes the given command or logs the user into the system and gives the
user a normal shell on the remote system. All communication with the
remote command or shell will be encrypted automatically and checked for
integrity. If no pseudo-tty was allocated, the session is transparent
and can be used to reliably transfer binary data. The session termi‐
nates when the command or shell on the remote system 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 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 config‐
ured on the command line or in configuration files. The DISPLAY value
set by the ssh2 command 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.
The ssh2 command will also automatically set up the Xauthority data on
the server machine. It will generate a random authentication cookie,
store it in the Xauthority data on the server, and verify that any for‐
warded connections carry this cookie and replace it with the real
cookie when the connection is opened. The real authentication cookie
is never sent to the server.
If the user is using an authentication agent, the connection to the
agent is automatically forwarded to the remote side unless disabled on
the command line or in a configuration file. Forwarding of arbi‐
trary TCP/IP connections over the secure channel can be specified
either on the command line or in a configuration file. TCP/IP forward‐
ing can be used for secure connections to electronic purses or for
going through firewalls.
Ssh2 automatically maintains and checks a database containing the pub‐
lic host keys. When logging in on a host for the first time, the
host's public key is stored in the file 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.
Secure Shell has built-in support for SOCKS versions 4 and 5 for
traversing firewalls. (See the Environment Variables section.) How‐
ever, the SOCKS5 support does not include support for the SOCKS authen‐
tication methods.
See Security Administration for more information about Secure Shell
clients and servers and Secure Shell authentication.
NOTES
The ssh2 command obtains configuration data from the following sources
(in this order):
/etc/ssh2/ssh2_config (system's global configuration file )
$HOME/.ssh2/ssh2_config (user's configuration file) command-line
options
For each parameter, the last obtained value will be effective.
Escape Sequences
The ssh2 command supports the escape sequences that. For any escape
sequences to take effect, you must enter a newline character (press the
Enter key), then enter the characters. For example, a newline, a tilde
(~), and the appropriate character for a task. Following are the escape
sequences: Terminates the connection. Suspends the session. Simultane‐
ously press the Ctrl key and the Z key. Sends the escape character.
Lists forwarded connections. Disables the escape character. Displays
escape sequences. Initiates rekeying manually. Displays statistics
about the connection, including server and client version, compression,
packets in, packets out, compression, key exchange algorithms, public
key algorithms, and symmetric ciphers. Displays the client version
number to stderr (useful for troubleshooting).
EXIT STATUS
On normal execution, the ssh2 command exits with the status of the com‐
mand run. On successful runs this is normally zero. If ssh2 encounters
an error, you usually see the reason in an error message. Some common
exit values for ssh2 include the following: Returned if ssh2 encounters
a fatal signal. For example, 143 would be returned for SIGTERM (signal
number 15). Returned on disconnect, clean or otherwise.
Following are some disconnect codes: host not allowed to connect
protocol error key exchange failed key exchange failed mac error
compression error service not available protocol version not
supported host key not verifiable connection lost by application
too many connections auth cancelled by user no more auth methods
available illegal user name
For example, 74 would mean “Connection lost.” Returned on a
call for ssh_fatal(). Usually means that ssh2 failed to exec(3)
something (generic catch-all in the libraries for failures to
fork(2) or exec(3)). Generic error. Connecting to remote host
failed.
ENVIRONMENT VARIABLES
The ssh2 command will set the following environment variables. Addi‐
tionally, the ssh2 command reads the /etc/environment file and the
$HOME/.ssh2/environment file and adds lines of the format VARNAME=value
to the environment. Indicates the location of the X11 server. It is
automatically set to point to a value of the form hostname:n, where
hostname is the host where the shell runs, and n is an integer >= 1.
The ssh2 command uses this special value to forward X11 connections
over the secure channel. The user should normally not set the DISPLAY
environment variable, as that will render the X11 connection insecure
(and will require the user to manually copy any required authorization
cookies). Points to the user's home directory. Synonym for USER; sets
for compatibility with systems using this variable. Points to the
user's mailbox. Sets the default PATH, as specified when compiling the
ssh2 command or, on some systems, /etc/environment or
/etc/default/login. If SOCKS is used, it is configured with this vari‐
able. The format of the variable is:
socks://username@socks_server:port/network/netmask,network/net‐
mask...
For example, setting the environment variable 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 the SOCKS server if a 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 the SSH_SOCKS_SERVER variable can be speci‐
fied at compile time by specifying --with-socks-server=VALUE on
the configure command line when compiling the ssh2 command. 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 the SSH_SOCKS_SERVER variable is set, it should con‐
tain a local loopback network (127.0.0.0/8) as the network that
is connected directly. Indicates the path of a unix-domain
socket used to communicate with the authentication agent (or its
local representative). Identifies the client of the connection.
The variable contains the following space-separated values:
client ip-address, client port number, host ip-address, and
server port number. The original command given to the ssh2 com‐
mand if a forced command is run. For example, it can be used to
fetch arguments from the other system. This does not have to be
a real command; it can be the name of a file, device, parameters
or anything else. 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. Sets to
the present time zone if it was set when the daemon was started.
The daemon passes the value to new connections. Sets to the
name of the user logging in.
FILES
Specifies Secure Shell client configuration information. Specifies
Secure Shell server configuration information. Seeds the random number
generator. This file is created the first time the program is run and
it is updated automatically. The user should never need to modify this
file. This file contains sensitive data and its permissions should be
set to “read/write” for the user and “not accessible” for others. Con‐
tains per-user configuration information. The format of this file is
described above. This file is used by the Secure Shell client. This
file does not usually contain any sensitive information, but the recom‐
mended permissions are “read/write” for the user, and “not accessible”
for others. Contains information on how the user will be authenticated
when contacting a specific host. The identification file has the same
general syntax as the configuration files. The following keywords can
be used: Precedes the file name of a private key in the $HOME/.ssh2
directory used for identification when contacting a host. If there is
more than one IdKey, they are tried in the order that they appear in
the identification file. Precedes the file name of the user's OpenPGP
private keyring in the $HOME/.ssh2 directory. The OpenPGP keys listed
after this line are expected to be found from this file. The keys iden‐
tified with IdPgpKey*-keywords are used like ones identified with
IdKey-keyword. Preceds the OpenPGP key name of the key in the PgpSe‐
cretKeyFile file. Precedes the OpenPGP key fingerprint of the key in
the PgpSecretKeyFile file. Precedes the OpenPGP key ID of the key in
the PgpSecretKeyFile file. 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: Precedes the file name of a public key in the $HOME/.ssh2
directory used for identification when contacting the host. More than
one key is acceptable for login. Precedes the file name of the user's
OpenPGP public keyring in the $HOME/.ssh2directory. 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. Precedes the OpenPGP key name. Precedes the OpenPGP key
fingerprint. Precedes the OpenPGP key ID. This keyword, if used, must
follow the Key or PgpKey* keyword. The various options are specified as
a comma-separated list. (See the Public Key Options section for more
details.) This keyword is deprecated. Use Options instead. These
files are the public keys of the hosts to which you connect. They are
updated automatically, unless you set the StrictHostKeyChecking parame‐
ter to yes in the ssh2_config file. If a host's key changes, you should
put the key here only if you are sure that the new key is valid (i.e.,
there was no man-in-the-middle attack). The xxxx is the port on the
server, where the sshd2 deamon runs, and the yyyy is the host (speci‐
fied on the command line). If a host key is not found from the user's
$HOME/.ssh2/hostkeys directory, this is the next location to be
checked. These files must be updated manually; no files are put here
automatically. Contains a list of remote users who are not required to
supply a password when they use Secure Shell host-based authentication
with the ssh2 command. The same file is used by rlogind and rshd.
The sshd2 differs from rlogind and rshd in that it requires pub‐
lic host-key authentication from the Secure Shell 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 should not be accessible to 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. The same as $HOME/.rhosts. However, this file is not
used by rlogin and rsh, so using it permits access using ssh2
only. Contains the names of remote hosts and users that are
equivalent to the local host or user. An equivalent host or user
is allowed to use the ssh2 command with Secure Shell host-based
authentication without supplying a password. Additionally, the
syntax +@group can be used to specify netgroups. Negated
entries start with a minus (-) sign. This file must be writable
only by root; it should also be world-readable.
Warning: You should not inlcude user names in hosts.equiv. The
named users could log in as anybody, including bin, daemon, adm,
and other accounts that own critical binaries and directories.
The only valid use for user names should be in negative
entries. This warning also applies to rsh and rlogin. The same
as /etc/hosts.equiv. However, this file is not used by rlogin
and rshd, so using it permits access using ssh2 only. Contains
the public host keys of hosts that users need to log in to when
using host based authentication.
The xxxx is the fully qualified domain name (FQDN) and yyyy is
the public key algorithm. Public key algorithms are ssh-dss and
ssh-rsa. For example, if the FQDN for a host is server1.foo.fi
and it has a key algorithm of ssh-dss, the host key would be
server1.foo.fi.ssh-dss.pub in the knownhosts directory.
A user must add the host name to a $HOME/.shosts file or an
$HOME/.rhosts file. Same as the $HOME/.ssh2/known‐
hosts/xxxxyyyy.pub file, but system-wide. This file is overrid‐
den if the user puts a file with the same name in the
$HOME/.ssh2/knownhosts directory.
PUBLIC KEY OPTIONS
The following options are specified as a comma-separated list:
In addition to public-key authentication, the canonical name of the
remote host must match the given patterns. These parameters follow the
logic of {Allow,Deny}Hosts, described in detail in sshd2_config(4).
You specify one pattern per keyword. Multiple keywords can be used.
Specifies 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 is put in the environment variable SSH2_ORIGI‐
NAL_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 com‐
mand if escaped with backslashes. 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 forwarding, unless
they are explicitly prohibited (see no-port-forwarding). Specifies
that the string is to be added to the environment when logging in using
this key. Environment variables set this way override other default
environment values. Multiple options of this type are permitted. Sets
idle timeout limit to time in seconds (s or nothing after number), in
minutes (m), in hours (h), in days (d), or in weeks (w). If the con‐
nection has been idle (all channels) this long, the connection is
closed. Forbids TCP/IP forwarding when this key is used for authenti‐
cation. Any port forward requests by the client will return an error.
This is useful in combination with the command option. Forbids X11
forwarding when this key is used for authentication. Any X11 forward
requests by the client will return an error. Forbids authentication
agent forwarding when this key is used for authentication. Prevents
tty allocation (a request to allocate a pty will fail).
LEGAL NOTICES
SSH is a registered trademark of SSH Communication Security Ltd.
SEE ALSO
Commands: rlogin(1), rsh(1), scp2(1), sftp(1), ssh-add2(1), ssh-
agent2(1), ssh-keygen2(1), telnet(1), sshd2(8)
Files: hosts.equiv(4), rhosts(4), shosts(4), ssh2_config(4), sshd2_con‐
fig(4)
Guides: Security Administration
ssh2(1)
