WeOS
5.29.0

# Secure Shell (SSH)

## Introduction

Secure Shell (SSH) is a widely used protocol for establishing a secure channel over a public network. An SSH service is enabled by default in all products to allow safe remote login and access to the command line interface. The service defaults to listening on Internet port 22 for incoming connections, on all interfaces.

All products also come with an SSH client, which can be used to log in to other devices. Useful when debugging remote systems which do not have routing set up or cannot be connected to otherwise. This is sometimes referred to as using a device as a “hop server”.

## Connecting to a Device

To connect to the SSH service you need an SSH client. There are many options available, one of the most useful is the freely available PuTTY client on Windows, which also supports serial console connection. But like Linux and other UNIX systems, Windows 10 today ships with the OpenSSH client ssh, which is a command line program. In the examples below a Linux host with the ssh client is used.

Connecting can be done to the assigned DNS name, the advertised mDNS name, or using the IP address of the remote device:

        operator@example:~$ ssh admin@weos.local
        admin@weos.local's password: *******

Enter the password associated with the admin account and the next text displayed is the remote system’s message of the day (MOTD) and the CLI prompt. Use `logout`, `exit`, or `Ctrl-D` to log out and disconnect.

Note: The first time connecting to a device from a specific host, the SSH client will respond with a warning (similar to):

        The authenticity of host 'weos.local (192.168.122.89)' can't be established.
        ECDSA key fingerprint is SHA256:lhQjYbBcWVZY2Zqmm1HizFx0M2opgTsBFNXmja161KE.
        Are you sure you want to continue connecting (yes/no)?

Answering yes saves the public key of the remote device into a local database (known_hosts) and associates it with the IP address and port (TCP port 22 unless otherwise specified) used to connect. This key is verified every time you connect to the same address and port.

The warning text above comes from OpenSSH. Other SSH implementations may have differently worded warning messages. You may also receive a warning about a possible “man-in-the-middle” attack, which usually occurs when the same address is being used with another device. See the Troubleshooting section for more details.

## Connect from a Device

The built-in SSH client can be used to connect to other devices in a network. A typical use case is to access devices in a private network where only a gateway device is publicly accessible. An operator can SSH into the gateway device and from there initiate another SSH connection to the private part of the topology.

To initiate an SSH connection from the CLI, use the `ssh` command from the top-level admin-exec context:

        admin@example:/#> ssh admin@192.168.122.1:222

The `admin@` part can be changed to a different login name or left out completely if the username on the target device is the same as then one logged in on the originating device. The `:222` part designates the port number, can also be separated by a space, e.g. `admin@192.168.122.1 222`. It can be left out if the standard port (22) is used, this depends on the configuration of the SSH service of the target device. The IP address can also be replaced with a domain name.

The warning messages regarding an new untrusted host is similar to that displayed by OpenSSH:

        Host '192.168.122.1' is not in the trusted hosts file.
        (ecdsa-sha2-nistp256 fingerprint md5 d7:17:86:c7:69:fc:dd:16:f4:4a:62:55:eb:47:6f:43)
        Do you want to continue connecting? (y/n)

The warning message for a changed host key (possible eavesdropping) is also similar to that displayed by OpenSSH:

        WARNING: Host key mismatch for 192.168.122.1!
        Fingerprint is md5 d7:17:86:c7:69:fc:dd:16:f4:4a:62:55:eb:47:6f:43
        Expected       md5 bd:3d:e5:f3:49:24:98:14:22:28:9d:92:0a:12:48:3d
        Continue anyway (y/N)?

Typing y here allows the connection to proceed.

### Syntax

As mentioned above, the `ssh` command is used directly in the top-level admin-exec context.

        admin@example:/#>

Two main formats are supported for the command, where they essentially just differ in how the user is specified.

`ssh [user USER] [force ipv4|ipv6] HOST[:PORT| PORT]`

  Secure shell login to another host.

  This command can be used to log in to another host using the SSH protocol.

  As mentioned, the only difference in this format is that the user is provided using the `user` option, which is a separate option instead of being part of the host specification using the `USER@HOST` format.

  Only one user specification

  A user cannot be specified both by the `user` option and by using the `USER@` syntax. This will result in an error.

  Example

  Connecting to a device as user `admin`:

      admin@example:/#> ssh user admin 192.168.1.1

      admin@example:/#> ssh user admin 2001:db8::1

      admin@example:/#> ssh user admin myhost

  Special case when you want to connect to a device on an IPv6 link-local address, you need to specify the interface as well, e.g. `vlan1`:

      admin@example:/#> ssh user admin fe80::1%vlan1

  Connecting to a device as user `admin` on a specific port, e.g. port 2222:

      admin@example:/#> ssh user admin 192.168.1.1:2222

      admin@example:/#> ssh user admin [2001:db8::1]:2222

      admin@example:/#> ssh user admin myhost:2222

  Using the `force` option to force the use of either IPv4 or IPv6 addresses only:

      admin@example:/#> ssh force ipv4 user admin myhost

      admin@example:/#> ssh force ipv6 user admin myhost

  User specification

  Again, all of these example commands can also be executed using the `USER@HOST` format, while omitting the `user` option.

  user
    The user to log in as. If not specified, the current user is used, e.g. if the user is `admin` on the device, then the user `admin` is used to log in to the remote host.
  force ipv4|ipv6
    Force the use of either IPv4 or IPv6 addresses only. This is useful when the host has both IPv4 and IPv6 addresses, but you want to connect using only one of them.
  HOST
    Should be a valid IPv4 or IPv6 address, or a valid FQDN (Fully Qualified Domain Name).
  PORT
    Optional port number, defaults to 22 if not specified. If a port is specified, it can be separated by a colon `:` or a space.
`ssh [force ipv4|ipv6] [USER@]HOST[:PORT| PORT]`

  As mentioned, the only difference when using this format, i.e. using the `user@host` format, is how the user is specified. Other than that, the command behaves the same as the previous format.

  Therefore, see the previous section for more details on how to use the command.

  Example

  Connecting to a device as user `admin`:

      admin@example:/#> ssh admin@192.168.1.1

      admin@example:/#> ssh admin@2001:db8::1

      admin@example:/#> ssh admin@myhost

## Managing SSH host keys

Two types of SSH host keys are generated the first time a system starts. One or more of these keys can persistently be re-generated.

Supported key types:

- rsa
- ecdsa

NOTE: TPM based devices only support one type of key at a time. The automatically generated key type on first system boot will be ecdsa. The key type can be changed, but only one key type can be active at a time.

Example of how to generate a new 4096-bit RSA ssh key.

    example:/#> ssh-host-key generate rsa size 4096

## Configuration

The SSH service can be configured in several ways:

- It can be deactivated
- It can be restricted to a subset of available interfaces
- The port number can be changed
- Keepalive can be tuned or disabled
- Idle timeout can be configured or disabled
- Fail delay can be changed.
- An optional pre-login banner can be configured.

Warning

Changing the SSH configuration while connected to the device via SSH is risky. If possible, use an alternative management front-end, e.g. the WebUI.

The SSH service is available from the management configuration context in the CLI:

    example:/#> configure
    example:/config/#> management
    example:/config/management/#> ssh
    example:/config/management/ssh/#>

`[no] enable`

  Enable/disable the SSH server. The rest of the configuration is however, saved for when you re-enable the service again.

  The ssh service configuration can be completely reset from the parent `management` configuration context using `no ssh`.

  Warning

  Secure copy (SCP) relies on the SSH service. If SSH is deactivated, it will not be possible for a remote host or device to use scp to copy files to or from this device.

  no
    Disable SSH service completely
`[no] listen IFNAME[,IFNAME]`

  Interfaces on which to allow SSH connections.

  To restrict SSH to only listen on interfaces vlan1 and vlan2:

      listen vlan1 vlan2

  To listen on all interfaces again (default):

      no listen

`[no] port PORT`

  By default, SSH listens on TCP port 22. SSH clients connect to this port unless another port is specified.

  Note

  To connect to an SSH server listening to a non-standard port, the port has to be specified when connecting. For example:

      foo@localhost$ ssh admin@192.168.122.89 -p 222

`[no] keepalive SEC`

  By default, a 60 second keepalive is enabled for SSH connections. Meaning, the server and client exchange control messages every 60 seconds, which has two purposes:

  - Prevent firewalls and routers from closing the connection if there is no data sent over it for a long time
  - Detect a loss of connection
  no
    Disable keepalive messages
  SEC
    Interval in seconds between keepalive probes, default: 60 sec
`[no] idle-timeout SEC`

  This setting is used to automatically disconnect an SSH connection when the connecting user has not been active for a while.

  Keepalive probes should not be counted as user activity, however this is a non-standardised area, subject to implementation differences in both the SSH server and client. It is possible the two mechanisms (keepalive and idle timeout) will interfere with each other if both are enabled.

  no
    Disable idle-timeout completely
  SEC
    Number of seconds (of idle activity) until connection times out
`[no] fail-delay SEC`

  Set a delay to SEC seconds occurring after a failed login attempt.

  The effective delay is not constant but each time randomly generated from a pseudo Gaussian distribution with mean = SEC + 300ms and standard deviation = SEC/6. The effective delay does not exceed +-50% of SEC around the mean. Example: When selected delay SEC = 3s then mean = 3.3s, std. deviation = 0.5s, min = 1.8s, max = 4.8s.

  no
    Set default value.
  SEC
    Fail delay in seconds
`[no] external-access`

  Configure access to secure shell copy (scp) to the device initiated from a remote host.

  If enabled, it is possible to transfer file(s) between a remote host and WeOS device, when the transfer is initiated from the remote host.

  It is always possible to transfer files when the transfer initiated from WeOS device.

  Default: Disabled

  no
    Disable external access.

  Warning

  It is highly discouraged to have this setting persistently enabled. This function allows very permissive file access to the device remotely.

`[no] login-banner [MESSAGE]`

  Configure a banner to be displayed on the ssh console login.

  This is a banner that will be displayed on the ssh console login, before the user has logged in to the device.

  Tip

  For additional general information regarding pre-login banner, refer to the section on Pre-Login Banner on the Management Web configuration page.

  Default: `no login-banner` (Disabled)

  Configuration Example

  A pre-login banner message can be configured in the following manner:

      example:/config/management/ssh/#> login-banner “This is a message.\n\nThis is displayed on a new line.”

  The overview `show` command will try and display the message as it would be when considering the escape characters:

      example:/config/management/ssh/#> show
      […]

      Login Banner
      ▏This is a message.                                                          ▕
      ▏                                                                            ▕
      ▏This is displayed on a new line.                                            ▕
      ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔

  To see how the raw message that was configured the specific `show login-banner` command can be used:

      example:/config/management/ssh/#> show login-banner
      “This is a message.\n\nThis is displayed on a new line.”

  Login Example

  This is how the message would be displayed when trying to access the device over a SSH connection:

      operator@example:~$ ssh admin@192.168.1.1
      This is a message.

      This is displayed on a new line.
      admin@192.168.1.1’s password:

  no
    Remove any configured login-banner and disable it.
  MESSAGE

    Free-form message, remember to enclose the message like this `"MESSAGE"` or `'MESSAGE'`.

    When writing the message certain escape characters can also be included:

    - `\a` => BELL
    - `\b` => Backspace
    - `\t` => Horizontal TAB
    - `\n` => New line
    - `\v` => Vertical TAB
    - `\f` => Form Feed
    - `\r` => Carriage Return
    - `\\` => \

Note

The following options can only be configured via a Console session. It is highly discouraged to have this setting persistently enabled. This function should only be used when specific troubleshooting is needed.

`[no] shell-access`

  Manage remote shell access configuration.

  This command will open a sub-context where the remote shell access configuration is managed.

  no
    Disable remote shell access

    example:/#> configure
    example:/config/#> management
    example:/config/management/#> ssh
    example:/config/management/ssh/#> shell-access
    example:/config/management/ssh/shell-access#>

`[no] enable`

  Enable or disable ‘shell’ access from remote SSH connections

  no
    disable ‘shell’ access from remote SSH connections (default)
`[no] audit-log [interval [VALUE] [seconds|minutes|hours|days]]`

  Enable or disable continuous audit log event when remote shell access is enabled. The continuous audit log event will log a message to the audit log every set interval.

  Default: Enabled with 30 minutes interval.

  interval [VALUE] seconds|minutes|hours|days

    Configure the time interval for logging audit-log messages.

  no
    disable continuous audit log
`[no] warning`

  Enable or disable the persistent warning when remote shell access is enabled.

  no
    disable persistent warning

## Troubleshooting

Occasionally when initiating an SSH connection, you may get a warning like this:

        @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
        @    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
        @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
        IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
        Someone could be eavesdropping on you right now (man-in-the-middle attack)!
        It is also possible that a host key has just been changed.
        The fingerprint for the ECDSA key sent by the remote host is
        SHA256:lhQjYbBcWVZY2Zqmm1HizFx0M2opgTsBFNXmja161KE.
        Please contact your system administrator.
        Add correct host key in /home/foo/.ssh/known_hosts to get rid of this message.
        Offending ECDSA key in /home/foo/.ssh/known_hosts:58
        remove with:
            ssh-keygen -f "/home/foo/.ssh/known_hosts" -R 192.168.122.89

        ECDSA host key for 192.168.122.89 has changed and you have requested strict checking.
        Host key verification failed.

The warning is displayed when the local SSH client tries to look up the SSH server’s public key in the known_hosts database and finds a different key associated with the same IP address + port combination.

This happens for example when:

- The device running WeOS is replaced with another device while the same IP address is retained.
- The IP address is changed to one which was previously associated with a different physical device.
- A factory reset is performed on the WeOS device. This will cause a new key to be generated when the device is restarted.

In any of these valid cases, the solution is to remove the invalid database entry casusing the warning. The command to run was printed as part of the the warning message:

    operator@example:~$ ssh-keygen -f "/home/foo/.ssh/known_hosts" -R 192.168.122.89

If none of the above valid reasons for a mismatch in the “IP address to host key” relation applies, it is possible you are the target of a man-in-the-middle attack where someone is trying to intercept the communication with the WeOS device.

If so, do not invalidate the database entry as explained above. Instead take appropriate action to report the incident and secure communication.

« Previous Next »