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 ] [-v ] [-d debug_level ] [-V ] [-q ] [-f [o ]] [-e char ] [-c cipher ] [-m MAC ] [-p port ] [-S ] [-L [protocol/][localhost:]port:host:hostport ] [-L socks/port ] [-R [protocol/][localhost:]port:host:hostport ] [-g ] [+g ] [+C ] [-C ] [-E provider ] [-I initstring ] [-4 ] [-6 ] [-1 [ti] ] [-o 'option' ] [-h ] [username@]host[#port] [command ]

DESCRIPTION

Ssh2 (Secure Shell) is a program for logging in on a remote machine and executing commands on a remote machine. It is intended to replace rlogin and rsh, and provide secure, encrypted communication channels between two hosts over an insecure network. X11 connections and arbitrary TCP/IP ports can also be forwarded over such secure channels.

Ssh2 connects and logs in on the specified host. The user must prove her 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 herself, 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 authentication 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 transparent 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 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 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 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 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 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 the 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 containing the public host keys. When logging in on 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 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 ENVIRONMENT. Note that the SOCKS5 support does not include support for the SOCKS authentication methods.

OPTIONS

-l username
    Log in on remote machine as user username.

-n  Redirect input from /dev/null (ie. do not 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). If X11 SECURITY extension is compiled in, treat the client applications as untrusted (the effects of this depend on your Xserver's security policy). See TrustX11Applications in ssh2_config(5) for additional details.

+X  As above, but the client applications are treated as trusted.

-x  Disable X11 connection forwarding.

-i file
    Specifies the identity file for public-key authentication. 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, but options specified here will be overridden by file.

-t  For tty allocation, that is, 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 messages. 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". This should be the first argument on the command line.

-V  Display version string.

-q  Make ssh2 quiet, so that it does not 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 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 configuration file (default: ~).

-c cipher
    Select 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
    Select the MAC (Message Authentication Code) algorithm. Multiple -m options are allowed, but a single -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  Do 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 forwarded 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 forwarding. The protocols implemented are tcp (default, no special processing), ftp (temporary forwarding is created for ftp data channels, effectively 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 approriate value for the SocksServer configuration option. See ssh2_config(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 than you). If you are using it to ease traversing a firewall, consult the administrator of the destination network for 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 listener 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, 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  Gateway ports, i.e. also remote hosts may connect to locally forwarded ports.

+g  Do not gateway ports.

+C  Enable compression.

-C  Disable compression (default).

-E provider
    Use 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
    Use initialization string Iinitstring 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  Use IPv4 to connect.

-6  Use IPv6 to connect.

-1[ti]
    Fall back to SSH1 protocol. Additional letter is mandatory: 'i' means internal emulation, 't' means traditional 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 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 accepted. Where applicable, egrep regex format is used.

-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 (typically /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. Commercial packages use a license file (typically /etc/ssh2/license_ssh2.dat) to specify the type of the license. For more information, see SSH Secure Shell Administrator's Guide. For the format of ssh2_config, see ssh2_config(5).

ESCAPE SEQUENCES
Ssh2 supports escape sequences to manage a running session. In order for an escape sequences to take effect, it must be typed directly after a newline character (read: press enter first). The escape sequences are not displayed onscreen during typing.

~.  Terminate the connection.

~^Z Suspend the session (press control-Z, not ^ and Z).

~~  Send the escape character.

~#  List forwarded connections.

~-  Disable the escape character irrevocably.

~?  See a summary of escape sequences.

~r  Initiate rekeying manually.

~s  Give connection statistics, including server and client version, packets in, packets out, compression, key exchange algorithms, public-key algorithms, and symmetric ciphers.

~V  Dump the client version number to stderr (useful for troubleshooting).

ENVIRONMENT
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 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 insecure (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 systems using this variable.

MAIL
    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 instance, by setting SSH_SOCKS_SERVER to socks://mylogin@socks.ssh.com:1080/203.123.0.0/16,198.74.23.0/24, host socks.ssh.com and port 1080 are used as your SOCKS server for connections outside of networks 203.123.0.0 (16 bit domain) and 198.74.23.0 (8 bit domain). Those networks are connected directly. A default value for SSH_SOCKS_SERVER 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 cancelled by setting SSH_SOCKS_SERVER to an empty string, and overridden by setting SSH_SOCKS_SERVER to a new value. If it is set, it should almost always contain the local loopback network (127.0.0.0/8) as a network that is connected 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 and 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 command. If the current session has no tty, this variable is not set.

TZ  The time-zone variable is set to indicate the present time zone if it was set when the daemon was started (the daemon passes the value to new connections).

USER
    The name of the user.

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 it is 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 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 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.

PgpSecretKeyFile
    This is followed by the filename of the user's OpenPGP private key ring in the $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.

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 identification 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 $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 those 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.

Options
    This keyword, if used, must follow the "Key" or "PgpKey*" keyword above. The various options are specified as a comma-separated list. See Section "PUBLIC-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 that unless you can be sure the key is valid, ie. 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 command line).

/etc/ssh2/hostkeys/key_xxxx_yyyy.pub
    If a host key is not found from "$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 whitespace, one per line. The given user is permitted to log in from the given host 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 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 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 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. Additionally, successful host-based 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. Beware 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 user name practically 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 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 with ssh1's RhostsRSAAuthentication). Also, a user has to set up her/his $HOME/.shosts (only used by ssh) or $HOME/.rhosts file (insecure, as it is used by the r*-commands also). If the user name is the same in both hosts, it is adequate to put the public host key to /etc/ssh2/knownhosts and add the host's name 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 zappa.foo.fi's host-key algorithm is ssh-dss, the host key is contained in the file "zappa.foo.fi.ssh-dss.pub" in the knownhosts 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 her $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 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. Quotes may be used in the command 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).

environment="NAME=value"
    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.

idle-timeout=time
    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 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, accommondating 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 number 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), sftp(1), rlogin(1), rsh(1), telnet(1)