.. _ssh:

###
SSH
###

:abbr:`SSH (Secure Shell)` is a cryptographic network protocol for operating
network services securely over an unsecured network. The standard TCP port for
SSH is 22. The best known example application is for remote login to computer
systems by users.

SSH provides a secure channel over an unsecured network in a client-server
architecture, connecting an SSH client application with an SSH server. Common
applications include remote command-line login and remote command execution,
but any network service can be secured with SSH. The protocol specification
distinguishes between two major versions, referred to as SSH-1 and SSH-2.

The most visible application of the protocol is for access to shell accounts
on Unix-like operating systems, but it sees some limited use on Windows as
well. In 2015, Microsoft announced that they would include native support for
SSH in a future release.

SSH was designed as a replacement for Telnet and for unsecured remote shell
protocols such as the Berkeley rlogin, rsh, and rexec protocols.
Those protocols send information, notably passwords, in plaintext,
rendering them susceptible to interception and disclosure using packet
analysis. The encryption used by SSH is intended to provide confidentiality
and integrity of data over an unsecured network, such as the Internet.

.. note:: VyOS 1.1 supported login as user ``root``. This has been removed due
   to tighter security in VyOS 1.2.

.. seealso:: SSH :ref:`ssh_key_based_authentication`

Configuration
=============

.. cfgcmd:: set service ssh port <port>

  Enabling SSH only requires you to specify the port ``<port>`` you want SSH to
  listen on. By default, SSH runs on port 22.

.. cfgcmd:: set service ssh listen-address <address>

  Specify IPv4/IPv6 listen address of SSH server. Multiple addresses can be
  defined.

.. cfgcmd:: set service ssh ciphers <cipher>

  Define allowed ciphers used for the SSH connection. A number of allowed
  ciphers can be specified, use multiple occurrences to allow multiple ciphers.

  List of supported ciphers: ``3des-cbc``, ``aes128-cbc``, ``aes192-cbc``,
  ``aes256-cbc``, ``aes128-ctr``, ``aes192-ctr``, ``aes256-ctr``,
  ``arcfour128``, ``arcfour256``, ``arcfour``, ``blowfish-cbc``, ``cast128-cbc``

.. cfgcmd:: set service ssh disable-password-authentication

  Disable password based authentication. Login via SSH keys only. This hardens
  security!

.. cfgcmd:: set service ssh disable-host-validation

  Disable the host validation through reverse DNS lookups - can speedup login
  time when reverse lookup is not possible.

.. cfgcmd:: set service ssh macs <mac>

  Specifies the available :abbr:`MAC (Message Authentication Code)` algorithms.
  The MAC algorithm is used in protocol version 2 for data integrity protection.
  Multiple algorithms can be provided.

  List of supported MACs: ``hmac-md5``, ``hmac-md5-96``, ``hmac-ripemd160``,
  ``hmac-sha1``, ``hmac-sha1-96``, ``hmac-sha2-256``, ``hmac-sha2-512``,
  ``umac-64@openssh.com``, ``umac-128@openssh.com``,
  ``hmac-md5-etm@openssh.com``, ``hmac-md5-96-etm@openssh.com``,
  ``hmac-ripemd160-etm@openssh.com``, ``hmac-sha1-etm@openssh.com``,
  ``hmac-sha1-96-etm@openssh.com``, ``hmac-sha2-256-etm@openssh.com``,
  ``hmac-sha2-512-etm@openssh.com``, ``umac-64-etm@openssh.com``,
  ``umac-128-etm@openssh.com``

.. cfgcmd:: set service ssh access-control <allow | deny> <group | user> <name>

  Add access-control directive to allow or deny users and groups. Directives
  are processed in the following order of precedence: ``deny-users``,
  ``allow-users``, ``deny-groups`` and ``allow-groups``.

.. cfgcmd:: set service ssh client-keepalive-interval <interval>

  Specify timeout interval for keepalive message in seconds.

.. cfgcmd:: set service ssh key-exchange <kex>

  Specify allowed :abbr:`KEX (Key Exchange)` algorithms.

  List of supported algorithms: ``diffie-hellman-group1-sha1``,
  ``diffie-hellman-group14-sha1``, ``diffie-hellman-group14-sha256``,
  ``diffie-hellman-group16-sha512``, ``diffie-hellman-group18-sha512``,
  ``diffie-hellman-group-exchange-sha1``,
  ``diffie-hellman-group-exchange-sha256``,
  ``ecdh-sha2-nistp256``, ``ecdh-sha2-nistp384``, ``ecdh-sha2-nistp521``,
  ``curve25519-sha256`` and ``curve25519-sha256@libssh.org``.

.. cfgcmd:: set service ssh loglevel <quiet | fatal | error | info | verbose>

  Set the ``sshd`` log level. The default is ``info``.

.. cfgcmd:: set service ssh vrf <name>

  Specify name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance.

Operation
=========

.. opcmd:: restart ssh

  Restart the SSH daemon process, the current session is not affected, only the
  background daemon is restarted.

.. opcmd:: generate ssh server-key

  Re-generated the public/private keyportion which SSH uses to secure
  connections.

  .. note:: Already learned known_hosts files of clients need an update as the
     public key will change.

.. opcmd:: generate ssh client-key /path/to/private_key

  Re-generated a known pub/private keyfile which can e.g. used to connect to
  other services (RPKI cache).

  Example:

  .. code-block:: none

    vyos@vyos:~$ generate ssh client-key /config/auth/id_rsa_rpki
    Generating public/private rsa key pair.
    Your identification has been saved in /config/auth/id_rsa_rpki.
    Your public key has been saved in /config/auth/id_rsa_rpki.pub.
    The key fingerprint is:
    SHA256:XGv2PpdOzVCzpmEzJZga8hTRq7B/ZYL3fXaioLFLS5Q vyos@vyos
    The key's randomart image is:
    +---[RSA 2048]----+
    |         oo      |
    |          ..o    |
    |       . o.o.. o.|
    |       o+ooo  o.o|
    |        Eo*  =.o |
    |       o = +.o*+ |
    |        = o *.o.o|
    |       o * +.o+.+|
    |        =.. o=.oo|
    +----[SHA256]-----+

  Two new files ``/config/auth/id_rsa_rpki`` and ``/config/auth/id_rsa_rpki.pub``
  will be created.