# ssh

## NAME



           **ssh** — OpenSSH remote login client
    


## SYNOPSIS



           **ssh**[**-46AaCfGgKkMNnqsTtVvXxYy**] [**-B** _bind_interface_] [**-b**
           _bind_address_] [**-c** _cipher_spec_] [**-D**[_bind_address_ :]_port_] [**-E**
           _log_file_] [**-e** _escape_char_] [**-F** _configfile_] [**-I** _pkcs11_] [**-i**
           _identity_file_] [**-J** _destination_] [**-L** _address_] [**-l** _login_name_] [**-m**
           _mac_spec_] [**-O** _ctl_cmd_] [**-o** _option_] [**-P** _tag_] [**-p** _port_] [**-R** _address_]
           [**-S** _ctl_path_] [**-W** _host_ :_port_] [**-w** _local_tun_[:_remote_tun_]]
           _destination_ [_command_ [_argument ..._]] **ssh**[**-Q** _query_option_]
    


## DESCRIPTION



           **ssh**(SSH client) is a program for logging into a remote machine
           and for executing commands on a remote machine.  It is intended to
           provide secure encrypted communications between two untrusted
           hosts over an insecure network.  X11 connections, arbitrary TCP
           ports and Unix-domain sockets can also be forwarded over the
           secure channel.
    
           **ssh** connects and logs into the specified _destination_ , which may be
           specified as either [user@]hostname or a URI of the form
           ssh://[user@]hostname[:port].  The user must prove their identity
           to the remote machine using one of several methods (see below).
    
           If a _command_ is specified, it will be executed on the remote host
           instead of a login shell.  A complete command line may be
           specified as _command_ , or it may have additional arguments.  If
           supplied, the arguments will be appended to the command, separated
           by spaces, before it is sent to the server to be executed.
    
           The options are as follows:
    
           **-4** Forces **ssh** to use IPv4 addresses only.
    
           **-6** Forces **ssh** to use IPv6 addresses only.
    
           **-A** Enables forwarding of connections from an authentication
                   agent such as _ssh-agent_(1).  This can also be specified on
                   a per-host basis in a configuration file.
    
                   Agent forwarding should be enabled with caution.  Users
                   with the ability to bypass file permissions on the remote
                   host (for the agent's Unix-domain socket) can access the
                   local agent through the forwarded connection.  An attacker
                   cannot obtain key material from the agent, however they
                   can perform operations on the keys that enable them to
                   authenticate using the identities loaded into the agent.
                   A safer alternative may be to use a jump host (see **-J**).
    
           **-a** Disables forwarding of the authentication agent
                   connection.
    
           **-B** _bind_interface_
                   Bind to the address of _bind_interface_ before attempting to
                   connect to the destination host.  This is only useful on
                   systems with more than one address.
    
           **-b** _bind_address_
                   Use _bind_address_ on the local machine as the source
                   address of the connection.  Only useful on systems with
                   more than one address.
    
           **-C** Requests compression of all data (including stdin, stdout,
                   stderr, and data for forwarded X11, TCP and Unix-domain
                   connections).  The compression algorithm is the same used
                   by _gzip_(1).  Compression is desirable on modem lines and
                   other slow connections, but will only slow down things on
                   fast networks.  The default value can be set on a host-by-
                   host basis in the configuration files; see the **Compression**
                   option in _ssh_config_(5).
    
           **-c** _cipher_spec_
                   Selects the cipher specification for encrypting the
                   session.  _cipher_spec_ is a comma-separated list of ciphers
                   listed in order of preference.  See the **Ciphers** keyword in
                   _ssh_config_(5) for more information.
    
           **-D**[_bind_address_ :]_port_
                   Specifies a local “dynamic” application-level port
                   forwarding.  This works by allocating a socket to listen
                   to _port_ on the local side, optionally bound to the
                   specified _bind_address_.  Whenever a connection is made to
                   this port, the connection is forwarded over the secure
                   channel, and the application protocol is then used to
                   determine where to connect to from the remote machine.
                   Currently the SOCKS4 and SOCKS5 protocols are supported,
                   and **ssh** will act as a SOCKS server.  Only root can forward
                   privileged ports.  Dynamic port forwardings can also be
                   specified in the configuration file.
    
                   IPv6 addresses can be specified by enclosing the address
                   in square brackets.  Only the superuser can forward
                   privileged ports.  By default, the local port is bound in
                   accordance with the **GatewayPorts** setting.  However, an
                   explicit _bind_address_ may be used to bind the connection
                   to a specific address.  The _bind_address_ of “localhost”
                   indicates that the listening port be bound for local use
                   only, while an empty address or ‘*’ indicates that the
                   port should be available from all interfaces.
    
           **-E** _log_file_
                   Append debug logs to _log_file_ instead of standard error.
    
           **-e** _escape_char_
                   Sets the escape character for sessions with a pty
                   (default: ‘~’).  The escape character is only recognized
                   at the beginning of a line.  The escape character followed
                   by a dot (‘.’) closes the connection; followed by control-
                   Z suspends the connection; and followed by itself sends
                   the escape character once.  Setting the character to
                   “none” disables any escapes and makes the session fully
                   transparent.
    
           **-F** _configfile_
                   Specifies an alternative per-user configuration file.  If
                   a configuration file is given on the command line, the
                   system-wide configuration file (_/etc/ssh/ssh_config_) will
                   be ignored.  The default for the per-user configuration
                   file is _~/.ssh/config_.  If set to “none”, no configuration
                   files will be read.
    
           **-f** Requests **ssh** to go to background just before command
                   execution.  This is useful if **ssh** is going to ask for
                   passwords or passphrases, but the user wants it in the
                   background.  This implies **-n**.  The recommended way to
                   start X11 programs at a remote site is with something like
                   **ssh -f host xterm**.
    
                   If the **ExitOnForwardFailure** configuration option is set to
                   “yes”, then a client started with **-f** will wait for all
                   remote port forwards to be successfully established before
                   placing itself in the background.  Refer to the
                   description of **ForkAfterAuthentication** in _ssh_config_(5)
                   for details.
    
           **-G** Causes **ssh** to print its configuration after evaluating
                   **Host** and **Match** blocks and exit.
    
           **-g** Allows remote hosts to connect to local forwarded ports.
                   If used on a multiplexed connection, then this option must
                   be specified on the master process.
    
           **-I** _pkcs11_
                   Specify the PKCS#11 shared library **ssh** should use to
                   communicate with a PKCS#11 token providing keys for user
                   authentication.
    
           **-i** _identity_file_
                   Selects a file from which the identity (private key) for
                   public key authentication is read.  You can also specify a
                   public key file to use the corresponding private key that
                   is loaded in _ssh-agent_(1) when the private key file is not
                   present locally.  The default is _~/.ssh/id_rsa_ ,
                   _~/.ssh/id_ecdsa_ , _~/.ssh/id_ecdsa_sk_ , _~/.ssh/id_ed25519_ and
                   _~/.ssh/id_ed25519_sk_.  Identity files may also be
                   specified on a per-host basis in the configuration file.
                   It is possible to have multiple **-i** options (and multiple
                   identities specified in configuration files).  If no
                   certificates have been explicitly specified by the
                   **CertificateFile** directive, **ssh** will also try to load
                   certificate information from the filename obtained by
                   appending _-cert.pub_ to identity filenames.
    
           **-J** _destination_
                   Connect to the target host by first making an **ssh**
                   connection to the jump host described by _destination_ and
                   then establishing a TCP forwarding to the ultimate
                   destination from there.  Multiple jump hops may be
                   specified separated by comma characters.  IPv6 addresses
                   can be specified by enclosing the address in square
                   brackets.  This is a shortcut to specify a **ProxyJump**
                   configuration directive.  Note that configuration
                   directives supplied on the command-line generally apply to
                   the destination host and not any specified jump hosts.
                   Use _~/.ssh/config_ to specify configuration for jump hosts.
    
           **-K** Enables GSSAPI-based authentication and forwarding
                   (delegation) of GSSAPI credentials to the server.
    
           **-k** Disables forwarding (delegation) of GSSAPI credentials to
                   the server.
    
           **-L**[_bind_address_ :]_port_ :_host_ :_hostport_
           **-L**[_bind_address_ :]_port_ :_remote_socket_
           **-L** _local_socket_ :_host_ :_hostport_
           **-L** _local_socket_ :_remote_socket_
                   Specifies that connections to the given TCP port or Unix
                   socket on the local (client) host are to be forwarded to
                   the given host and port, or Unix socket, on the remote
                   side.  This works by allocating a socket to listen to
                   either a TCP _port_ on the local side, optionally bound to
                   the specified _bind_address_ , or to a Unix socket.  Whenever
                   a connection is made to the local port or socket, the
                   connection is forwarded over the secure channel, and a
                   connection is made to either _host_ port _hostport_ , or the
                   Unix socket _remote_socket_ , from the remote machine.
    
                   Port forwardings can also be specified in the
                   configuration file.  Only the superuser can forward
                   privileged ports.  IPv6 addresses can be specified by
                   enclosing the address in square brackets.
    
                   By default, the local port is bound in accordance with the
                   **GatewayPorts** setting.  However, an explicit _bind_address_
                   may be used to bind the connection to a specific address.
                   The _bind_address_ of “localhost” indicates that the
                   listening port be bound for local use only, while an empty
                   address or ‘*’ indicates that the port should be available
                   from all interfaces.
    
           **-l** _login_name_
                   Specifies the user to log in as on the remote machine.
                   This also may be specified on a per-host basis in the
                   configuration file.
    
           **-M** Places the **ssh** client into “master” mode for connection
                   sharing.  Multiple **-M** options places **ssh** into “master”
                   mode but with confirmation required using _ssh-askpass_(1)
                   before each operation that changes the multiplexing state
                   (e.g. opening a new session).  Refer to the description of
                   **ControlMaster** in _ssh_config_(5) for details.
    
           **-m** _mac_spec_
                   A comma-separated list of MAC (message authentication
                   code) algorithms, specified in order of preference.  See
                   the **MACs** keyword in _ssh_config_(5) for more information.
    
           **-N** Do not execute a remote command.  This is useful for just
                   forwarding ports.  Refer to the description of **SessionType**
                   in _ssh_config_(5) for details.
    
           **-n** Redirects stdin from _/dev/null_ (actually, prevents reading
                   from stdin).  This must be used when **ssh** is run in the
                   background.  A common trick is to use this to run X11
                   programs on a remote machine.  For example, **ssh -n**
                   **shadows.cs.hut.fi emacs & **will start an emacs on
                   shadows.cs.hut.fi, and the X11 connection will be
                   automatically forwarded over an encrypted channel.  The
                   **ssh** program will be put in the background.  (This does not
                   work if **ssh** needs to ask for a password or passphrase; see
                   also the **-f** option.)  Refer to the description of
                   **StdinNull** in _ssh_config_(5) for details.
    
           **-O** _ctl_cmd_
                   Control an active connection multiplexing master process.
                   When the **-O** option is specified, the _ctl_cmd_ argument is
                   interpreted and passed to the master process.  Valid
                   commands are: “check” (check that the master process is
                   running), “forward” (request forwardings without command
                   execution), “cancel” (cancel forwardings), “proxy”
                   (connect to a running multiplexing master in proxy mode),
                   “exit” (request the master to exit), and “stop” (request
                   the master to stop accepting further multiplexing
                   requests).
    
           **-o** _option_
                   Can be used to give options in the format used in the
                   configuration file.  This is useful for specifying options
                   for which there is no separate command-line flag.  For
                   full details of the options listed below, and their
                   possible values, see _ssh_config_(5).
    
                         AddKeysToAgent
                         AddressFamily
                         BatchMode
                         BindAddress
                         CanonicalDomains
                         CanonicalizeFallbackLocal
                         CanonicalizeHostname
                         CanonicalizeMaxDots
                         CanonicalizePermittedCNAMEs
                         CASignatureAlgorithms
                         CertificateFile
                         CheckHostIP
                         Ciphers
                         ClearAllForwardings
                         Compression
                         ConnectionAttempts
                         ConnectTimeout
                         ControlMaster
                         ControlPath
                         ControlPersist
                         DynamicForward
                         EnableEscapeCommandline
                         EscapeChar
                         ExitOnForwardFailure
                         FingerprintHash
                         ForkAfterAuthentication
                         ForwardAgent
                         ForwardX11
                         ForwardX11Timeout
                         ForwardX11Trusted
                         GatewayPorts
                         GlobalKnownHostsFile
                         GSSAPIAuthentication
                         GSSAPIDelegateCredentials
                         HashKnownHosts
                         Host
                         HostbasedAcceptedAlgorithms
                         HostbasedAuthentication
                         HostKeyAlgorithms
                         HostKeyAlias
                         Hostname
                         IdentitiesOnly
                         IdentityAgent
                         IdentityFile
                         IPQoS
                         KbdInteractiveAuthentication
                         KbdInteractiveDevices
                         KexAlgorithms
                         KnownHostsCommand
                         LocalCommand
                         LocalForward
                         LogLevel
                         MACs
                         Match
                         NoHostAuthenticationForLocalhost
                         NumberOfPasswordPrompts
                         PasswordAuthentication
                         PermitLocalCommand
                         PermitRemoteOpen
                         PKCS11Provider
                         Port
                         PreferredAuthentications
                         ProxyCommand
                         ProxyJump
                         ProxyUseFdpass
                         PubkeyAcceptedAlgorithms
                         PubkeyAuthentication
                         RekeyLimit
                         RemoteCommand
                         RemoteForward
                         RequestTTY
                         RequiredRSASize
                         SendEnv
                         ServerAliveInterval
                         ServerAliveCountMax
                         SessionType
                         SetEnv
                         StdinNull
                         StreamLocalBindMask
                         StreamLocalBindUnlink
                         StrictHostKeyChecking
                         TCPKeepAlive
                         Tunnel
                         TunnelDevice
                         UpdateHostKeys
                         User
                         UserKnownHostsFile
                         VerifyHostKeyDNS
                         VisualHostKey
                         XAuthLocation
    
           **-P** _tag_  Specify a tag name that may be used to select
                   configuration in _ssh_config_(5).  Refer to the **Tag** and
                   **Match** keywords in _ssh_config_(5) for more information.
           **-p** _port_
                   Port to connect to on the remote host.  This can be
                   specified on a per-host basis in the configuration file.
    
           **-Q** _query_option_
                   Queries for the algorithms supported by one of the
                   following features: _cipher_ (supported symmetric ciphers),
                   _cipher-auth_ (supported symmetric ciphers that support
                   authenticated encryption), _help_ (supported query terms for
                   use with the **-Q** flag), _mac_ (supported message integrity
                   codes), _kex_ (key exchange algorithms), _key_ (key types),
                   _key-ca-sign_ (valid CA signature algorithms for
                   certificates), _key-cert_ (certificate key types), _key-plain_
                   (non-certificate key types), _key-sig_ (all key types and
                   signature algorithms), _protocol-version_ (supported SSH
                   protocol versions), and _sig_ (supported signature
                   algorithms).  Alternatively, any keyword from
                   _ssh_config_(5) or _sshd_config_(5) that takes an algorithm
                   list may be used as an alias for the corresponding
                   query_option.
    
           **-q** Quiet mode.  Causes most warning and diagnostic messages
                   to be suppressed.
    
           **-R**[_bind_address_ :]_port_ :_host_ :_hostport_
           **-R**[_bind_address_ :]_port_ :_local_socket_
           **-R** _remote_socket_ :_host_ :_hostport_
           **-R** _remote_socket_ :_local_socket_
           **-R**[_bind_address_ :]_port_
                   Specifies that connections to the given TCP port or Unix
                   socket on the remote (server) host are to be forwarded to
                   the local side.
    
                   This works by allocating a socket to listen to either a
                   TCP _port_ or to a Unix socket on the remote side.  Whenever
                   a connection is made to this port or Unix socket, the
                   connection is forwarded over the secure channel, and a
                   connection is made from the local machine to either an
                   explicit destination specified by _host_ port _hostport_ , or
                   _local_socket_ , or, if no explicit destination was
                   specified, **ssh** will act as a SOCKS 4/5 proxy and forward
                   connections to the destinations requested by the remote
                   SOCKS client.
    
                   Port forwardings can also be specified in the
                   configuration file.  Privileged ports can be forwarded
                   only when logging in as root on the remote machine.  IPv6
                   addresses can be specified by enclosing the address in
                   square brackets.
    
                   By default, TCP listening sockets on the server will be
                   bound to the loopback interface only.  This may be
                   overridden by specifying a _bind_address_.  An empty
                   _bind_address_ , or the address ‘*’, indicates that the
                   remote socket should listen on all interfaces.  Specifying
                   a remote _bind_address_ will only succeed if the server's
                   **GatewayPorts** option is enabled (see _sshd_config_(5)).
    
                   If the _port_ argument is ‘0’, the listen port will be
                   dynamically allocated on the server and reported to the
                   client at run time.  When used together with **-O forward** ,
                   the allocated port will be printed to the standard output.
    
           **-S** _ctl_path_
                   Specifies the location of a control socket for connection
                   sharing, or the string “none” to disable connection
                   sharing.  Refer to the description of **ControlPath** and
                   **ControlMaster** in _ssh_config_(5) for details.
    
           **-s** May be used to request invocation of a subsystem on the
                   remote system.  Subsystems facilitate the use of SSH as a
                   secure transport for other applications (e.g. _sftp_(1)).
                   The subsystem is specified as the remote command.  Refer
                   to the description of **SessionType** in _ssh_config_(5) for
                   details.
    
           **-T** Disable pseudo-terminal allocation.
    
           **-t** Force pseudo-terminal allocation.  This can be used to
                   execute arbitrary screen-based programs on a remote
                   machine, which can be very useful, e.g. when implementing
                   menu services.  Multiple **-t** options force tty allocation,
                   even if **ssh** has no local tty.
    
           **-V** Display the version number and exit.
    
           **-v** Verbose mode.  Causes **ssh** to print debugging messages
                   about its progress.  This is helpful in debugging
                   connection, authentication, and configuration problems.
                   Multiple **-v** options increase the verbosity.  The maximum
                   is 3.
    
           **-W** _host_ :_port_
                   Requests that standard input and output on the client be
                   forwarded to _host_ on _port_ over the secure channel.
                   Implies **-N** , **-T** , **ExitOnForwardFailure** and
                   **ClearAllForwardings** , though these can be overridden in the
                   configuration file or using **-o** command line options.
    
           **-w** _local_tun_[:_remote_tun_]
                   Requests tunnel device forwarding with the specified
                   _tun_(4) devices between the client (_local_tun_) and the
                   server (_remote_tun_).
    
                   The devices may be specified by numerical ID or the
                   keyword “any”, which uses the next available tunnel
                   device.  If _remote_tun_ is not specified, it defaults to
                   “any”.  See also the **Tunnel** and **TunnelDevice** directives in
                   _ssh_config_(5).
    
                   If the **Tunnel** directive is unset, it will be set to the
                   default tunnel mode, which is “point-to-point”.  If a
                   different **Tunnel** forwarding mode it desired, then it
                   should be specified before **-w**.
    
           **-X** Enables X11 forwarding.  This can also be specified on a
                   per-host basis in a configuration file.
    
                   X11 forwarding should be enabled with caution.  Users with
                   the ability to bypass file permissions on the remote host
                   (for the user's X authorization database) can access the
                   local X11 display through the forwarded connection.  An
                   attacker may then be able to perform activities such as
                   keystroke monitoring.
    
                   For this reason, X11 forwarding is subjected to X11
                   SECURITY extension restrictions by default.  Refer to the
                   **ssh -Y** option and the **ForwardX11Trusted** directive in
                   _ssh_config_(5) for more information.
    
           **-x** Disables X11 forwarding.
    
           **-Y** Enables trusted X11 forwarding.  Trusted X11 forwardings
                   are not subjected to the X11 SECURITY extension controls.
    
           **-y** Send log information using the _syslog_(3) system module.
                   By default this information is sent to stderr.
    
           **ssh** may additionally obtain configuration data from a per-user
           configuration file and a system-wide configuration file.  The file
           format and configuration options are described in _ssh_config_(5).
    


## AUTHENTICATION



           The OpenSSH SSH client supports SSH protocol 2.
    
           The methods available for authentication are: GSSAPI-based
           authentication, host-based authentication, public key
           authentication, keyboard-interactive authentication, and password
           authentication.  Authentication methods are tried in the order
           specified above, though **PreferredAuthentications** can be used to
           change the default order.
    
           Host-based authentication works as follows: If the machine the
           user logs in from is listed in _/etc/hosts.equiv_ or
           _/etc/shosts.equiv_ on the remote machine, the user is non-root and
           the user names are the same on both sides, or if the files
           _~/.rhosts_ or _~/.shosts_ exist in the user's home directory on the
           remote machine and contain a line containing the name of the
           client machine and the name of the user on that machine, the user
           is considered for login.  Additionally, the server _must_ be able to
           verify the client's host key (see the description of
           _/etc/ssh/ssh_known_hosts_ and _~/.ssh/known_hosts_ , below) for login
           to be permitted.  This authentication method closes security holes
           due to IP spoofing, DNS spoofing, and routing spoofing.  [Note to
           the administrator: _/etc/hosts.equiv_ , _~/.rhosts_ , and the rlogin/rsh
           protocol in general, are inherently insecure and should be
           disabled if security is desired.]
    
           Public key authentication works as follows: The scheme is based on
           public-key cryptography, using cryptosystems where encryption and
           decryption are done using separate keys, and it is unfeasible to
           derive the decryption key from the encryption key.  The idea is
           that each user creates a public/private key pair for
           authentication purposes.  The server knows the public key, and
           only the user knows the private key.  **ssh** implements public key
           authentication protocol automatically, using one of the ECDSA,
           Ed25519 or RSA algorithms.
    
           The file _~/.ssh/authorized_keys_ lists the public keys that are
           permitted for logging in.  When the user logs in, the **ssh** program
           tells the server which key pair it would like to use for
           authentication.  The client proves that it has access to the
           private key and the server checks that the corresponding public
           key is authorized to accept the account.
    
           The server may inform the client of errors that prevented public
           key authentication from succeeding after authentication completes
           using a different method.  These may be viewed by increasing the
           **LogLevel** to **DEBUG** or higher (e.g. by using the **-v** flag).
    
           The user creates their key pair by running _ssh-keygen_(1).  This
           stores the private key in _~/.ssh/id_ecdsa_ (ECDSA),
           _~/.ssh/id_ecdsa_sk_ (authenticator-hosted ECDSA), _~/.ssh/id_ed25519_
           (Ed25519), _~/.ssh/id_ed25519_sk_ (authenticator-hosted Ed25519), or
           _~/.ssh/id_rsa_ (RSA) and stores the public key in
           _~/.ssh/id_ecdsa.pub_ (ECDSA), _~/.ssh/id_ecdsa_sk.pub_
           (authenticator-hosted ECDSA), _~/.ssh/id_ed25519.pub_ (Ed25519),
           _~/.ssh/id_ed25519_sk.pub_ (authenticator-hosted Ed25519), or
           _~/.ssh/id_rsa.pub_ (RSA) in the user's home directory.  The user
           should then copy the public key to _~/.ssh/authorized_keys_ in their
           home directory on the remote machine.  The _authorized_keys_ file
           corresponds to the conventional _~/.rhosts_ file, and has one key
           per line, though the lines can be very long.  After this, the user
           can log in without giving the password.
    
           A variation on public key authentication is available in the form
           of certificate authentication: instead of a set of public/private
           keys, signed certificates are used.  This has the advantage that a
           single trusted certification authority can be used in place of
           many public/private keys.  See the CERTIFICATES section of
           _ssh-keygen_(1) for more information.
    
           The most convenient way to use public key or certificate
           authentication may be with an authentication agent.  See
           _ssh-agent_(1) and (optionally) the **AddKeysToAgent** directive in
           _ssh_config_(5) for more information.
    
           Keyboard-interactive authentication works as follows: The server
           sends an arbitrary "challenge" text and prompts for a response,
           possibly multiple times.  Examples of keyboard-interactive
           authentication include BSD Authentication (see _login.conf_(5)) and
           PAM (some non-OpenBSD systems).
    
           Finally, if other authentication methods fail, **ssh** prompts the
           user for a password.  The password is sent to the remote host for
           checking; however, since all communications are encrypted, the
           password cannot be seen by someone listening on the network.
    
           **ssh** automatically maintains and checks a database containing
           identification for all hosts it has ever been used with.  Host
           keys are stored in _~/.ssh/known_hosts_ in the user's home
           directory.  Additionally, the file _/etc/ssh/ssh_known_hosts_ is
           automatically checked for known hosts.  Any new hosts are
           automatically added to the user's file.  If a host's
           identification ever changes, **ssh** warns about this and disables
           password authentication to prevent server spoofing or man-in-the-
           middle attacks, which could otherwise be used to circumvent the
           encryption.  The **StrictHostKeyChecking** option can be used to
           control logins to machines whose host key is not known or has
           changed.
    
           When the user's identity has been accepted by the server, the
           server either executes the given command in a non-interactive
           session or, if no command has been specified, logs into the
           machine and gives the user a normal shell as an interactive
           session.  All communication with the remote command or shell will
           be automatically encrypted.
    
           If an interactive session is requested, **ssh** by default will only
           request a pseudo-terminal (pty) for interactive sessions when the
           client has one.  The flags **-T** and **-t** can be used to override this
           behaviour.
    
           If a pseudo-terminal has been allocated, the user may use the
           escape characters noted below.
    
           If no pseudo-terminal has been allocated, the session is
           transparent and can be used to reliably transfer binary data.  On
           most systems, setting the escape character to “none” will also
           make the session transparent even if a tty is used.
    
           The session terminates when the command or shell on the remote
           machine exits and all X11 and TCP connections have been closed.
    


## ESCAPE CHARACTERS



           When a pseudo-terminal has been requested, **ssh** supports a number
           of functions through the use of an escape character.
    
           A single tilde character can be sent as **~~** or by following the
           tilde by a character other than those described below.  The escape
           character must always follow a newline to be interpreted as
           special.  The escape character can be changed in configuration
           files using the **EscapeChar** configuration directive or on the
           command line by the **-e** option.
    
           The supported escapes (assuming the default ‘~’) are:
    
           **~.** Disconnect.
    
           **~^Z** Background **ssh**.
    
           **~#** List forwarded connections.
    
           **~ &      **Background **ssh** at logout when waiting for forwarded
                   connection / X11 sessions to terminate.
    
           **~?** Display a list of escape characters.
    
           **~B** Send a BREAK to the remote system (only useful if the peer
                   supports it).
    
           **~C** Open command line.  Currently this allows the addition of
                   port forwardings using the **-L** , **-R** and **-D** options (see
                   above).  It also allows the cancellation of existing port-
                   forwardings with **-KL**[_bind_address_ :]_port_ for local,
                   **-KR**[_bind_address_ :]_port_ for remote and
                   **-KD**[_bind_address_ :]_port_ for dynamic port-forwardings.
                   **!**_command_ allows the user to execute a local command if the
                   **PermitLocalCommand** option is enabled in _ssh_config_(5).
                   Basic help is available, using the **-h** option.
    
           **~R** Request rekeying of the connection (only useful if the
                   peer supports it).
    
           **~V** Decrease the verbosity (**LogLevel**) when errors are being
                   written to stderr.
    
           **~v** Increase the verbosity (**LogLevel**) when errors are being
                   written to stderr.
    


## TCP FORWARDING



           Forwarding of arbitrary TCP connections over a secure channel can
           be specified either on the command line or in a configuration
           file.  One possible application of TCP forwarding is a secure
           connection to a mail server; another is going through firewalls.
    
           In the example below, we look at encrypting communication for an
           IRC client, even though the IRC server it connects to does not
           directly support encrypted communication.  This works as follows:
           the user connects to the remote host using **ssh** , specifying the
           ports to be used to forward the connection.  After that it is
           possible to start the program locally, and **ssh** will encrypt and
           forward the connection to the remote server.
    
           The following example tunnels an IRC session from the client to an
           IRC server at “server.example.com”, joining channel “#users”,
           nickname “pinky”, using the standard IRC port, 6667:
    
               $ ssh -f -L 6667:localhost:6667 server.example.com sleep 10
               $ irc -c '#users' pinky IRC/127.0.0.1
    
           The **-f** option backgrounds **ssh** and the remote command “sleep 10” is
           specified to allow an amount of time (10 seconds, in the example)
           to start the program which is going to use the tunnel.  If no
           connections are made within the time specified, **ssh** will exit.
    


## X11 FORWARDING



           If the **ForwardX11** variable is set to “yes” (or see the description
           of the **-X** , **-x** , and **-Y** options above) and 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 **ssh** will point to the server machine, but
           with a display number greater than zero.  This is normal, and
           happens because **ssh** creates a “proxy” X server on the server
           machine for forwarding the connections over the encrypted channel.
    
           **ssh** 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 **ForwardAgent** variable is set to “yes” (or see the
           description of the **-A** and **-a** options above) and the user is using
           an authentication agent, the connection to the agent is
           automatically forwarded to the remote side.
    


## VERIFYING HOST KEYS



           When connecting to a server for the first time, a fingerprint of
           the server's public key is presented to the user (unless the
           option **StrictHostKeyChecking** has been disabled).  Fingerprints can
           be determined using _ssh-keygen_(1):
    
                 **$ ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key**
    
           If the fingerprint is already known, it can be matched and the key
           can be accepted or rejected.  If only legacy (MD5) fingerprints
           for the server are available, the _ssh-keygen_(1) **-E** option may be
           used to downgrade the fingerprint algorithm to match.
    
           Because of the difficulty of comparing host keys just by looking
           at fingerprint strings, there is also support to compare host keys
           visually, using _random art_.  By setting the **VisualHostKey** option
           to “yes”, a small ASCII graphic gets displayed on every login to a
           server, no matter if the session itself is interactive or not.  By
           learning the pattern a known server produces, a user can easily
           find out that the host key has changed when a completely different
           pattern is displayed.  Because these patterns are not unambiguous
           however, a pattern that looks similar to the pattern remembered
           only gives a good probability that the host key is the same, not
           guaranteed proof.
    
           To get a listing of the fingerprints along with their random art
           for all known hosts, the following command line can be used:
    
                 **$ ssh-keygen -lv -f ~/.ssh/known_hosts**
    
           If the fingerprint is unknown, an alternative method of
           verification is available: SSH fingerprints verified by DNS.  An
           additional resource record (RR), SSHFP, is added to a zonefile and
           the connecting client is able to match the fingerprint with that
           of the key presented.
    
           In this example, we are connecting a client to a server,
           “host.example.com”.  The SSHFP resource records should first be
           added to the zonefile for host.example.com:
    
                 $ ssh-keygen -r host.example.com.
    
           The output lines will have to be added to the zonefile.  To check
           that the zone is answering fingerprint queries:
    
                 **$ dig -t SSHFP host.example.com**
    
           Finally the client connects:
    
                 $ ssh -o "VerifyHostKeyDNS ask" host.example.com
                 [...]
                 Matching host key fingerprint found in DNS.
                 Are you sure you want to continue connecting (yes/no)?
    
           See the **VerifyHostKeyDNS** option in _ssh_config_(5) for more
           information.
    


## SSH-BASED VIRTUAL PRIVATE NETWORKS



           **ssh** contains support for Virtual Private Network (VPN) tunnelling
           using the _tun_(4) network pseudo-device, allowing two networks to
           be joined securely.  The _sshd_config_(5) configuration option
           **PermitTunnel** controls whether the server supports this, and at
           what level (layer 2 or 3 traffic).
    
           The following example would connect client network 10.0.50.0/24
           with remote network 10.0.99.0/24 using a point-to-point connection
           from 10.1.1.1 to 10.1.1.2, provided that the SSH server running on
           the gateway to the remote network, at 192.168.1.15, allows it.
    
           On the client:
    
                 # ssh -f -w 0:1 192.168.1.15 true
                 # ifconfig tun0 10.1.1.1 10.1.1.2 netmask 255.255.255.252
                 # route add 10.0.99.0/24 10.1.1.2
    
           On the server:
    
                 # ifconfig tun1 10.1.1.2 10.1.1.1 netmask 255.255.255.252
                 # route add 10.0.50.0/24 10.1.1.1
    
           Client access may be more finely tuned via the
           _/root/.ssh/authorized_keys_ file (see below) and the
           **PermitRootLogin** server option.  The following entry would permit
           connections on _tun_(4) device 1 from user “jane” and on tun device
           2 from user “john”, if **PermitRootLogin** is set to
           “forced-commands-only”:
    
             tunnel="1",command="sh /etc/netstart tun1" ssh-rsa ... jane
             tunnel="2",command="sh /etc/netstart tun2" ssh-rsa ... john
    
           Since an SSH-based setup entails a fair amount of overhead, it may
           be more suited to temporary setups, such as for wireless VPNs.
           More permanent VPNs are better provided by tools such as
           _ipsecctl_(8) and _isakmpd_(8).
    


## ENVIRONMENT



           **ssh** will normally set the following environment variables:
    
           DISPLAY               The DISPLAY variable indicates the location
                                 of the X11 server.  It is automatically set
                                 by **ssh** 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.  **ssh** 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 that use this variable.
    
           MAIL                  Set to the path of the user's mailbox.
    
           PATH                  Set to the default PATH, as specified when
                                 compiling **ssh**.
    
           SSH_ASKPASS           If **ssh** needs a passphrase, it will read the
                                 passphrase from the current terminal if it
                                 was run from a terminal.  If **ssh** does not
                                 have a terminal associated with it but
                                 DISPLAY and SSH_ASKPASS are set, it will
                                 execute the program specified by SSH_ASKPASS
                                 and open an X11 window to read the
                                 passphrase.  This is particularly useful
                                 when calling **ssh** from a _.xsession_ or related
                                 script.  (Note that on some machines it may
                                 be necessary to redirect the input from
                                 _/dev/null_ to make this work.)
    
           SSH_ASKPASS_REQUIRE   Allows further control over the use of an
                                 askpass program.  If this variable is set to
                                 “never” then **ssh** will never attempt to use
                                 one.  If it is set to “prefer”, then **ssh**
                                 will prefer to use the askpass program
                                 instead of the TTY when requesting
                                 passwords.  Finally, if the variable is set
                                 to “force”, then the askpass program will be
                                 used for all passphrase input regardless of
                                 whether DISPLAY is set.
    
           SSH_AUTH_SOCK         Identifies the path of a Unix-domain socket
                                 used to communicate with the agent.
    
           SSH_CONNECTION        Identifies the client and server ends of the
                                 connection.  The variable contains four
                                 space-separated values: client IP address,
                                 client port number, server IP address, and
                                 server port number.
    
           SSH_ORIGINAL_COMMAND  This variable contains the original command
                                 line if a forced command is executed.  It
                                 can be used to extract the original
                                 arguments.
    
           SSH_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.
    
           SSH_TUNNEL            Optionally set by _sshd_(8) to contain the
                                 interface names assigned if tunnel
                                 forwarding was requested by the client.
    
           SSH_USER_AUTH         Optionally set by _sshd_(8), this variable may
                                 contain a pathname to a file that lists the
                                 authentication methods successfully used
                                 when the session was established, including
                                 any public keys that were used.
    
           TZ                    This variable is set to indicate the present
                                 time zone if it was set when the daemon was
                                 started (i.e. the daemon passes the value on
                                 to new connections).
    
           USER                  Set to the name of the user logging in.
    
           Additionally, **ssh** reads _~/.ssh/environment_ , and adds lines of the
           format “VARNAME=value” to the environment if the file exists and
           users are allowed to change their environment.  For more
           information, see the **PermitUserEnvironment** option in
           _sshd_config_(5).
    


## FILES



           _~/.rhosts_
                   This file is used for host-based authentication (see
                   above).  On some machines this file may need to be world-
                   readable if the user's home directory is on an NFS
                   partition, because _sshd_(8) reads it as root.
                   Additionally, this file must be owned by the user, and
                   must not have write permissions for anyone else.  The
                   recommended permission for most machines is read/write for
                   the user, and not accessible by others.
    
           _~/.shosts_
                   This file is used in exactly the same way as _.rhosts_ , but
                   allows host-based authentication without permitting login
                   with rlogin/rsh.
    
           _~/.ssh/_
                   This directory is the default location for all user-
                   specific configuration and authentication information.
                   There is no general requirement to keep the entire
                   contents of this directory secret, but the recommended
                   permissions are read/write/execute for the user, and not
                   accessible by others.
    
           _~/.ssh/authorized_keys_
                   Lists the public keys (ECDSA, Ed25519, RSA) that can be
                   used for logging in as this user.  The format of this file
                   is described in the _sshd_(8) manual page.  This file is not
                   highly sensitive, but the recommended permissions are
                   read/write for the user, and not accessible by others.
    
           _~/.ssh/config_
                   This is the per-user configuration file.  The file format
                   and configuration options are described in _ssh_config_(5).
                   Because of the potential for abuse, this file must have
                   strict permissions: read/write for the user, and not
                   writable by others.
    
           _~/.ssh/environment_
                   Contains additional definitions for environment variables;
                   see “ENVIRONMENT”, above.
    
           _~/.ssh/id_ecdsa_
           _~/.ssh/id_ecdsa_sk_
           _~/.ssh/id_ed25519_
           _~/.ssh/id_ed25519_sk_
           _~/.ssh/id_rsa_
                   Contains the private key for authentication.  These files
                   contain sensitive data and should be readable by the user
                   but not accessible by others (read/write/execute).  **ssh**
                   will simply ignore a private key file if it is accessible
                   by others.  It is possible to specify a passphrase when
                   generating the key which will be used to encrypt the
                   sensitive part of this file using AES-128.
    
           _~/.ssh/id_ecdsa.pub_
           _~/.ssh/id_ecdsa_sk.pub_
           _~/.ssh/id_ed25519.pub_
           _~/.ssh/id_ed25519_sk.pub_
           _~/.ssh/id_rsa.pub_
                   Contains the public key for authentication.  These files
                   are not sensitive and can (but need not) be readable by
                   anyone.
    
           _~/.ssh/known_hosts_
                   Contains a list of host keys for all hosts the user has
                   logged into that are not already in the systemwide list of
                   known host keys.  See _sshd_(8) for further details of the
                   format of this file.
    
           _~/.ssh/rc_
                   Commands in this file are executed by **ssh** when the user
                   logs in, just before the user's shell (or command) is
                   started.  See the _sshd_(8) manual page for more
                   information.
    
           _/etc/hosts.equiv_
                   This file is for host-based authentication (see above).
                   It should only be writable by root.
    
           _/etc/shosts.equiv_
                   This file is used in exactly the same way as _hosts.equiv_ ,
                   but allows host-based authentication without permitting
                   login with rlogin/rsh.
    
           _/etc/ssh/ssh_config_
                   Systemwide configuration file.  The file format and
                   configuration options are described in _ssh_config_(5).
    
           _/etc/ssh/ssh_host_ecdsa_key_
           _/etc/ssh/ssh_host_ed25519_key_
           _/etc/ssh/ssh_host_rsa_key_
                   These files contain the private parts of the host keys and
                   are used for host-based authentication.
    
           _/etc/ssh/ssh_known_hosts_
                   Systemwide list of known host keys.  This file should be
                   prepared by the system administrator to contain the public
                   host keys of all machines in the organization.  It should
                   be world-readable.  See _sshd_(8) for further details of the
                   format of this file.
    
           _/etc/ssh/sshrc_
                   Commands in this file are executed by **ssh** when the user
                   logs in, just before the user's shell (or command) is
                   started.  See the _sshd_(8) manual page for more
                   information.
    


## EXIT STATUS



           **ssh** exits with the exit status of the remote command or with 255
           if an error occurred.
    


## STANDARDS



           S. Lehtinen and C. Lonvick, _The Secure Shell (SSH) Protocol_
           _Assigned Numbers_ , RFC 4250, January 2006.
    
           T. Ylonen and C. Lonvick, _The Secure Shell (SSH) Protocol_
           _Architecture_ , RFC 4251, January 2006.
    
           T. Ylonen and C. Lonvick, _The Secure Shell (SSH) Authentication_
           _Protocol_ , RFC 4252, January 2006.
    
           T. Ylonen and C. Lonvick, _The Secure Shell (SSH) Transport Layer_
           _Protocol_ , RFC 4253, January 2006.
    
           T. Ylonen and C. Lonvick, _The Secure Shell (SSH) Connection_
           _Protocol_ , RFC 4254, January 2006.
    
           J. Schlyter and W. Griffin, _Using DNS to Securely Publish Secure_
           _Shell (SSH) Key Fingerprints_ , RFC 4255, January 2006.
    
           F. Cusack and M. Forssen, _Generic Message Exchange Authentication_
           _for the Secure Shell Protocol (SSH)_ , RFC 4256, January 2006.
    
           J. Galbraith and P. Remaker, _The Secure Shell (SSH) Session_
           _Channel Break Extension_ , RFC 4335, January 2006.
    
           M. Bellare, T. Kohno, and C. Namprempre, _The Secure Shell (SSH)_
           _Transport Layer Encryption Modes_ , RFC 4344, January 2006.
    
           B. Harris, _Improved Arcfour Modes for the Secure Shell (SSH)_
           _Transport Layer Protocol_ , RFC 4345, January 2006.
    
           M. Friedl, N. Provos, and W. Simpson, _Diffie-Hellman Group_
           _Exchange for the Secure Shell (SSH) Transport Layer Protocol_ , RFC
           4419, March 2006.
    
           J. Galbraith and R. Thayer, _The Secure Shell (SSH) Public Key File_
           _Format_ , RFC 4716, November 2006.
    
           D. Stebila and J. Green, _Elliptic Curve Algorithm Integration in_
           _the Secure Shell Transport Layer_ , RFC 5656, December 2009.
    
           A. Perrig and D. Song, _Hash Visualization: a New Technique to_
           _improve Real-World Security_ , 1999, International Workshop on
           Cryptographic Techniques and E-Commerce (CrypTEC '99).
    


* * *