• Support
  • Articles
  • Resources
  • Products

SSH2 - secure shell client

Moderator: boris

1 postPage 1 of 1

Moderator, LogMeTT and TTLEditor developer

Joined: Sat Jan 08, 2005 2:52 pm
by boris » Tue May 10, 2005 3:43 am

Since there are lots of postings about SSH, I decided to publish here the description of Secure Shell taken from http://www.ssh.com/documents/32/ssh2.txt

Code: Select all

SSH2(1)                              SSH2                             SSH2(1)

  ssh2 - secure shell client (remote login program)

  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 ]


  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 pub-
  lic 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 con-
  junction 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 com-
  mand 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 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 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 com-
  mand 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 fire-
  walls.  See ENVIRONMENT.  Note that the SOCKS5 support does not include
  support for the SOCKS authentication methods.


  -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 "Mod-
       ulePattern=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.

       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, blow-
       fish, 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_con-
       fig(5) for a list of known algorithms).

  -p port
       Port to connect to on the remote host.  This option can also be speci-
       fied in the configuration file.

  -S   Do not request a session channel.  This can be used with port-forward-
       ing 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 connec-
       tion will not be secure, it is a normal TCP connection).  Port for-
       warding 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 ses-
       sion), 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 adminis-
       trator 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 option-
       ally be enclosed in square brackets [] to allow semicolons in the

  -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 allo-
       cates a listener port port on the remote side, and whenever a connec-
       tion is made to this port, the connection is forwarded over the secure
       channel and further to host:hostport from the local machine (this lat-
       ter 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

  +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 fur-
       ther 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.

       Fall back to SSH1 protocol.  Additional letter is mandatory: 'i' means
       internal emulation, 't' means traditional mechanism (call to ssh1 exe-


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


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

  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 new-
  line 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, pack-
       ets in, packets out, compression, key exchange algorithms, public-key
       algorithms, and symmetric ciphers.

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


  Ssh2 will normally set the following environment variables:

       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 run-
       ning, and n is an integer >= 1.  Ssh2 uses this special value to for-
       ward X11 connections over the secure channel.  The user should nor-
       mally not set DISPLAY explicitly, as that will render the X11 connec-
       tion insecure (and will require the user to manually copy any required
       authorization cookies).

  HOME The user's home directory.

       Synonym for USER; set for compatibility with systems using this vari-

  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.

       If SOCKS is used, it is configured with this variable.  The format of
       the variable is socks://username@socks_server:port/network/net-
       mask,network/netmask ...

       For instance, by setting SSH_SOCKS_SERVER to socks://mylo-
       gin@socks.ssh.com:1080/,, host
       socks.ssh.com and port 1080 are used as your SOCKS server for connec-
       tions outside of networks (16 bit domain) and
       (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 ( as a network
       that is connected directly.

       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

       Identifies the client end of the connection.  The variable contains
       three space-separated values: client IP address, client port number,
       and server port number.

       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.

       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.


       Used for seeding the random number generator.  This file contains sen-
       sitive 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.

       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 recom-
       mended permissions are 'read/write' for the user, and 'not accessible'
       for others.

       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 configura-
       tion files.  The following keywords may be used:

       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.

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

       This is followed by the OpenPGP key name of the key in PgpSecretKey-
       File file.

       This is followed by the OpenPGP key fingerprint of the key in PgpSe-
       cretKeyFile file.

       This is followed by the OpenPGP key ID of the key in PgpSecretKeyFile

       Contains information on how the server will verify the identity of an

       The authorization file has the same general syntax as the configura-
       tion 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.

       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.

       This is followed by the OpenPGP key name.

       This is followed by the OpenPGP key fingerprint.

       This is followed by the OpenPGP key ID.

       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.

       This keyword is deprecated (though it still works), use Options

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

       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.

       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.

       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.

       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 fol-
       lowed 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 nor-
       mally 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

       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

       These are the public host keys of hosts that a user wants to log in
       from using "hostbased" authentication (equivalent with ssh1's RhostsR-
       SAAuthentication).  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 known-
       hosts directory.

       Possible names for public-key algorithms are ssh-dss and ssh-rsa.

       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/known-
       hosts directory.

  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_con-
       fig(5).  Specify one pattern per keyword; multiple keywords can be
       used.  See Examples, below.

       This is used to specify a "forced command" that will be executed on
       the server side instead of anything else when the user is authenti-
       cated.  The command supplied by the user (if any) is put in the envi-
       ronment 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 pro-
       hibited (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 over-
       ride other default environment values.  Multiple options of this type
       are permitted.

       Sets idle timeout limit to time in seconds (s or nothing after num-
       ber), 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.

       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.

       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

       Prevents tty allocation (a request to allocate a pty will fail).


  Options allow-from=".*\.niksula\.hut\.fi", deny-from="pc\.niksula\.hut\.fi"

  Options command="echo $SSH2_ORIGINAL_COMMAND $FOO $BAR", environ-
  ment="FOO=zuppa", environment="BAR=zappa", allow-from="kungfoo.org", allow-

  On normal execution, ssh2 exits with the status of the command run. On suc-
  cessful runs this is normally 0 (zero).

  If ssh2 encounters an error, you usually see the reason in an error mes-
  sage. 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.


  SSH Communications Security Corp.

  For more information, see http://www.ssh.com.

  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)
Best regards,

1 postPage 1 of 1

Users browsing this forum: No registered users