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 [protocol/][localhost:]port:host:hostport ] [-R [protocol/][localhost:]port:host:hostport ] [+g ] [-g ] [+C ] [-C ] [-4 ] [-6 ] [-1 [ti] ] [-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 non-trusted hosts over an insecure network. X11 connections and arbitrary TCP/IP ports can also be forwarded over the secure channel.

Ssh2 connects and logs into the specified hostname. The user must prove his identity to the remote machine using some authentication method.

Public-key authentication is based on the use of digital signatures. Each user creates a public / private key pair for authentication purposes. The server knows the user's public key, and only the user has the private key. The filenames of private keys that are used in authentication are set in $HOME/.ssh2/identification. When the user tries to authenticate himself, the server checks $HOME/.ssh2/authorization for filenames of matching public keys and sends a challenge to the user end. The user is authenticated by signing the challenge using the private key. See the FILES section below for more information on identification and authorization files.

Private / public key pairs can be created with ssh-keygen2(1). See ssh-agent2(1) for information on how to use public-key authentication in conjunction with an authentication 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 transparent and can be used to reliably transfer binary data.

The session terminates when the command or shell in on the remote machine exits and all X11 and TCP/IP connections have been closed. The exit status of the remote program is returned as the exit status of ssh2.

If the user is using X11 (the DISPLAY environment variable is set), the connection to the X11 display is automatically forwarded to the remote side in such a way that any X11 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 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 traversing firewalls. See ENVIRONMENT.

OPTIONS

-l login_name
    Specifies the user for login to the remote machine.

-n  Redirect input from /dev/null, that is, 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)

-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, options specified here will be used in addition to those.

-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".

-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 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 configuration file. (default: ~)

-c cipher
    Select the encryption algorithm. Multiple -c options are allowed and a single -c flag can have only one cipher. This option can also be specified in the configuration file. You can use aes, blowfish, twofish, cast, arcfour, 3des, and des.

-m MAC
    Select the MAC (Message Authentication Code) algorithm. 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  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
    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. 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 remote machine. Port forwarding can also be specified in the configuration file. Only root can forward privileged ports. Giving the argument protocol enables the protocol-specific forwarding. The protocols implemented are tcp (default, no special processing) and ftp (temporary forwarding is created for ftp data channels, effectively securing the whole ftp session). 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 listened. Parameters localhost and host can optionally be enclosed to brackets [] allowing semicolons in the parameters.

-R [protocol/][localhost:]port:host:hostport
    Specifies that the given port on the remote (server) host is to be forwarded to the given host and port on the local side. This works by allocating a socket to listen to port on the remote side, and whenever a 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. Giving the argument protocol enables the protocol-specific forwarding. See the section for option -L for a list of possible protocols. 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 listened. Parameters localhost and host can optionally be enclosed to brackets [] allowing semicolons in the parameters.

+g  Gateway ports, i.e. also remote hosts may connect to locally forwarded ports.

-g  Don't gateway ports.

+C  Enable compression.

-C  Disable compression. (default)

-4  Use IPv4 to connect.

-6  Use IPv6 to connect.

-1 [ti]
    Choose ssh1-protocol fallback type. Mandatory argument 'i' specifies internal emulation, 't' specifies traditional fallback mechanism.

-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. (Egrep regex format is used with these options (where applicable))

-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. For format of ssh2_config, see ssh2_config(5).

ESCAPE SEQUENCES

Ssh2
    supports escape sequences that enable you to have some manageability with the session. In order for any escape sequences to take effect, you have enter a newline character (read: press enter before actually doing any of these operations). After that, manually enter the characters (for example, a newline, a tilde ~, and the appropriate character for the appropriate task). 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 all sorts of statistics on the connection, including server and client version, compression, 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 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 systems using this variable.

MAIL
    Set to point the user's mailbox.

PATH
    Set to the default PATH, as specified when compiling ssh2 or, on some systems, /etc/environment or /etc/default/login.

SSH_SOCKS_SERVER
    If SOCKS is used, it is configured with this variable. The format of the variable is socks://username@socks_server:port/network/netmask,network/netmask ... for example by setting environment variable SSH_SOCKS_SERVER to socks://mylogin@socks.ssh.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 networks 203.123.0.0 (16 bit domain) and 198.74.23.0 (8 bit domain) which are connected directly. A default value for SSH_SOCKS_SERVER variable can be specified at compile time by specifying --with-socks-server=VALUE on the configure command line when 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 the SSH_SOCKS_SERVER variable is set, it should almost always contain local loopback network (127.0.0.0/8) as network that is connected directly.

SSH2_AUTH_SOCK
    If 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
    Set to the name of the user logging in.

Additionally, ssh2 reads /etc/environment and $HOME/.ssh2/environment, and adds lines of the format VARNAME=value to the environment. Some systems may have still additional mechanisms for setting up the environment, such as /etc/default/login on Solaris.

FILES

$HOME/.ssh2/random_seed
    Used for seeding the random number generator. This file contains sensitive data and its permissions should be 'read/write' for the user and 'not accessible' for others. This file is created the first time the program is run and 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 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 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 are 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 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.

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 here the new key. (But do not do that, unless you can be sure the key is valid, that is, 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 automatically.

$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 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 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 permitted to log in without a password, provided that they have the same user name on both machines. The host name may also be followed by a user name; such users are permitted to log in as any user on this machine (except root). Additionally, the syntax +@group can be used to specify netgroups. Negated entries start with '-'. If the client host/user is successfully matched in this file, login is automatically permitted, provided 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 negative entries. Note that this warning also applies to rsh/rlogin.

/etc/shosts.equiv
    This is processed exactly as /etc/hosts.equiv. However, this file may be useful in environments that want to run both rsh/rlogin and ssh2.

$HOME/.ssh2/knownhosts/xxxxyyyy.pub
    These are the public host keys 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 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 hostname (FQDN) and yyyy the public-key algorithm of the key. For example, zappa.foo.fi's host-key algorithm is ssh-dss. The host key would be named "zappa.foo.fi.ssh-dss.pub" in the knownhosts directory. Possible names for public-key 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.

PUBLIC-KEY OPTIONS
Options are specified as a comma-separated list.

allow-from and deny-from
    Specifies that in addition to public-key authentication, the canonical name of the remote host must match the pattern(s). These parameters follow the logic of {Allow,Deny}Hosts, described in detail in sshd2_config(5). Specify one pattern per keyword, and 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. A quote may be included in the command by quoting it with a backslash. This option might be useful for restricting certain public keys to perform just a specific operation. An example might be a key that permits remote backups but nothing else. Notice that the client may specify TCP/IP and/or X11 forwarding, unless they are explicitly prohibited.

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 have been idle (all channels) for that long time the connection is closed down.

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 might be used, for example, in connection 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"

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)