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 or exchanged using import.

Supported key types:

rsa
ecdsa

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

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

Example of how to export the existing ECDSA ssh key as base64 encoded text.

example:/#> ssh-host-key export ecdsa

Example of how to import a base64 encoded ECDSA ssh key.

example:/#> ssh-host-key import ecdsa

Generate a SSH host keys on a Linux PC

The underlying SSH host key is in Dropbear format. This means a new key must be generated using the dropbearkey program. The result of this is a binary key which needs to be base64 encoded prior to import.

Example of how to do this from a PC running Ubuntu Linux.

ubuntu:/#> dropbearkey -t rsa -s 4096 -f new_key
ubuntu:/#> base64 new_key

The printed key can then be copy-paste imported using.

example:/#> ssh-host-key import rsa

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