SSH2

NAME

SYNOPSIS

ssh2 [-l login_name] [-n] [+a] [-a] [+x] [-x] [-i file] [-F file] [-t] [-v] [-d debug_level] [-V] [-q] [-f] [-e char] [-c cipher] [-p port] [-P] [-S] [-L port:host:hostport] [-R port:host:hostport] [+C] [-C] [-o `option'] [-h] [login_name@]hostname [command]  

DESCRIPTION

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

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

Public key authentication is based on the use of digital signatures. Each user creates a public / private key pair for authentication purposes. The server knows the user's public key, and only the user has the private key. The filenames of private keys that are used in authentication are set in $HOME/.ssh2/identification. When the user tries to authenticate himself, the server checks $HOME/.ssh2/authorization for filenames of matching public keys and sends a challenge to the user end. 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 prompts 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 Xauthority data on the server machine. For this purpose, it will generate a random authorization cookie, store it in Xauthority on the server, and verify that any forwarded connections carry this cookie and replace it by 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 command line or in a configuration file.

Forwarding of arbitrary TCP/IP connections over the secure channel can be specified either on command line or in a configuration file. TCP/IP forwarding can be used for secure connections to electronic purses or going through firewalls.

Ssh2 automatically maintains and checks a database containing public keys of hosts. When logging on to a host for the first time, the host's public key is stored to a file .ssh2/hostkey_PORTNUMBER_HOSTNAME.pub in the user's home directory. If a host's identification changes, ssh2 issues warning and disables password authentication 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, ie. don't read stdin. This option can also be specified in the configuration file.

+a

Enable authentication agent forwarding. (default)

-a

Disable authentication agent forwarding.

+x

Enable X11 connection forwarding. (default)

-x

Disable X11 connection forwarding.

-i file

Specifies the identity file for public key 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 in addition to those.

-t

For tty allocation, ie. allocate a tty even if a command is given. This option can also be specified in the configuration file.

-v

Enable verbose mode. Display verbose debugging 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 doesn't display any warning messages. This option can also be specified in the configuration file.

-f

Fork into background after authentication. This option can also be specified in the configuration file.

-e char

Set escape character. Use ``none'' to disable. This option can also be specified in the configuration file. (default; ~)

-c cipher

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

-p port

Port to connect to on the remote host. This option can also be specified in the configuration file.

-P

Don't use privileged source port. With this you cannot use rhosts or rsarhosts authentications, but it can be used to bypass some firewalls that don't allow privileged source ports to pass. This option can also be specified in the configuration file. (not yet implemented)

-S

Don't request a session channel. This can be used with port-forwarding requests if a session channel (and tty) isn't needed, or the server doesn't give one.

-L port:host:hostport

Specifies that the given port on the local (client) host is to be forwarded to the given host and port on the remote side. This works by allocating a socket to be listened port on the local side, 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 remote machine. Port forwardings can also be specified in the configuration file. Only root can forward privileged ports.

-R port:host:hostport

Specifies that the given port on the remote (server) host is to be forwarded to the given host and port on the local side. This works by 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.

+C

Enable compression.

-C

Disable compression. (default)

-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 currently accepted via this option.

-h

Display 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 command line options. For each parameter, the last obtained value will be effective.

The configuration file has the following format:

`expression:' denotes the start of a per-host configuration block, where `expression' is an arbitrary string which distinguishes this block from others. `expression' can contain wildcards. `expression' will be compared with the hostname obtained from the command-line, and if it matches, the block will be evaluated. Evaluation stops at the next `expression:' statement. If more than one match is found, all will be evaluated and the last obtained values for parameters will be effective. Note that `expression' doesn't have to be a real hostname, as long as the `expression' block contains a "Host" configuration parameter, where the real hostname to connect is defined.

Empty lines and lines starting with '#' are ignored as comments.

Otherwise a line is of the format "keyword arguments". Note that it is possible to enclose arguments in quotes, and use standard C-convention. The possible keywords and their meanings are as follows (note that the configuration files are case-sensitive, but keywords are case-insensitive):

AuthorizationFile

Specifies the name of the user's authorization file.

BatchMode

If set to "yes", passphrase/password querying will be disabled. This option is useful in scripts and other batch jobs where you have no user to supply the password. The argument must be "yes" or "no". (not yet implemented)

Ciphers

Specifies the ciphers to use for encrypting the session. Currently, des, 3des, blowfish, idea, arcfour and twofish are supported, of which des, 3des, arcfour, blowfish and twofish are in all distributions. Multiple ciphers can be specified as a comma-separated list. Special values to this option are any, anystd, that allows only standard (see below) ciphers, and anycipher that allows either any available cipher or excludes nonencrypting cipher mode none but allows all others. anystdcipher is the same as above, but includes only those ciphers mentioned in the IETF-SecSH-draft (excluding 'none').

Compression

Specifies whether to use compression. The argument must be "yes" or "no".

DontReadStdin

Redirect input from /dev/null, ie. don't read stdin. The argument must be "yes" or "no".

EscapeChar

Sets the escape character (default: ~). The escape character can also be set on the command line. The argument should be a single character, '^' followed by a letter, or "none" to disable the escape character entirely (making the connection transparent for binary data).

ForcePTTYAllocation

For tty allocation. Ie. allocate a tty even if a command is given. The argument must be "yes" or "no". (not yet implemented)

ForwardAgent

Specifies whether the connection to the authentication agent (if any) will be forwarded to the remote machine. The argument must be "yes" or "no".

ForwardX11

Specifies whether X11 connections will be automatically redirected over the secure channel and DISPLAY set. The argument must be "yes" or "no".

GatewayPorts

Specifies that also remote hosts may connect to locally forwarded ports. The argument must be "yes" or "no". The default is "no". (not yet implemented)

GoBackground

Requests ssh2 to go to background after authentication is done and forwardings have been established. This is useful if ssh2 is going to ask for passwords or passphrases, but the user wants it in the background. The argument must be "yes" or "no".

Host

Specifies the real host name to log into. With `expression' above, this can be used to specify nicknames or abbreviations for hosts.Default is the name given on the command line. Numeric IP addresses are also permitted (both on the command line and in HostName specifications).

IdentityFile

Specifies the name of the user's identification file.

KeepAlive

Specifies whether the system should send keepalive messages to the other side. If they are sent, death of the connection or crash of one of the machines will be properly noticed. However, this means that connections will die if the route is down temporarily, and some people find it annoying.

The default is "yes" (to send keepalives), and the client will notice if the network goes down or the remote host dies. This is important in scripts, and many users want it too.

To disable keepalives, the value should be set to "no" in both the server and the client configuration files.

LocalForward

Specifies that a TCP/IP port on the local machine be forwarded over the secure channel to given host:port from the remote machine. Argument should be enclosed in double-quotes (""). Argumentformat is port:remotehost:remoteport .

NoDelay

If "yes", enable socket option TCP_NODELAY. The argument must be "yes" or "no". Default is "no".

PasswordPrompt

Sets the password prompt, that the user sees when connecting to a host. Variables '%U' and '%H' can be used to give the user's login name and host, respectively.

Port

Specifies the port number to connect on the remote host. Default is 22.

QuietMode

Quiet mode. Causes all warnings and diagnostic messages to be suppressed. Only fatal errors are displayed. The argument must be "yes" or "no".

RandomSeedFile

Specifies the name of the user's randomseed file.

RemoteForward

Specifies that a TCP/IP port on the remote machine be forwarded over the secure channel to given host:port from the local machine. Argument should be enclosed in double-quotes (""). Argumentformat is port:remotehost:remoteport .

Ssh1AgentCompatibility

Specifies whether to forward also SSH1 agent connection. Legal values for this option are "none", "traditional" and "ssh2". With value "none" (default), SSH1 agent connection is not forwarded at all. With value "traditional", SSH1 agent connection is forwarded transparently like in SSH1. Value "traditional" can always be used, but it constitutes a security risk, because agent does not get the information about the forwarding path. Value "ssh2" makes SSH1 agent forwarding similar to SSH2 agent forwarding and with this mode agent gets the information about the agent forwarding path. Note that value "ssh2" can only be used, if you use ssh-agent2 in SSH1 compatibility mode. "yes" or "no".

Ssh1Compatibility

Specifies whether to use SSH1 compatibility code. With this option, ssh1 is executed when the server supports only SSH 1.x protocols. The argument must be "yes" or "no".

Ssh1Path

Specifies the path to ssh1 client, which is executed if the server supports only SSH 1.x protocols. The arguments for ssh2 are passed to the ssh1 client.

StrictHostKeyChecking

If this flag is set to "yes", ssh2 ssh2 will not automatically add host keys. This provides maximum protection against trojan horse attacks. However, it can be somewhat annoying if you frequently connect on new hosts. If this is set to "no" then new host will automatically be added to the known host files. The host keys of known hosts will be verified automatically in both cases. (not yet implemented)

User

Specifies the user to log in as. This can be useful if you have a different user name in different machines. This saves the trouble of having to remember to give the user name on the command line.

VerboseMode

Verbose mode. Causes ssh2 to print debugging messages about its progress. This is helpful in debugging connection, authentication, and configuration problems.

ENVIRONMENT