EdgeRouter - How to Use SSH Recovery


Overview


This article describes the process to access an EdgeRouter that is misconfigured or will not boot properly. These instructions are designed for advanced users to allow access to an EdgeRouter in a uncommon state for troubleshooting.

NOTES & REQUIREMENTS: This article applies to all EdgeRouter models with version 1.10.0 and higher.
 
Devices and Tools used in this article:

Table of Contents


  1. Introduction
  2. Frequently Asked Questions
  3. How to Access EdgeRouter Using SSH Recovery
  4. SSH Recovery Service Configuration Options
  5. Testing & Verification
  6. Related Articles

Introduction


Back to Top

These methods can be used to access the EdgeRouter webUI or Command Line Interface (CLI). In cases where an EdgeRouter becomes inaccessible due to a misconfiguration or errors, the SSH Recovery service introduced in firmware 1.10.0 allows access to the EdgeRouter before the configuration is loaded. 


Frequently Asked Questions


Back to Top

1. What is SSH Recovery?

The ssh-recovery feature is an EdgeOS service which provides emergency SSH access to an EdgeRouter from a directly connected IPv6-capable neighbor device. This eliminates the need for a console cable.

2. When should SSH Recovery be used?

The ssh-recovery feature can be used by an admin to access the EdgeRouter via SSH if it is otherwise inaccessible due to misconfiguration or other system failures.

3. When is SSH Recovery accessible?
By default ssh-recovery is started during early boot stages, meaning before the configuration is loaded and system daemons are running. The SSH Recovery service will stop accepting new SSH connections after 60 seconds from first boot. This gives enough time for the admin to log in to the faulty EdgeRouter after a reboot. Once logged in, the SSH session remains active even when ssh-recovery timeout occurs, allowing the admin to continue troubleshooting the device.
4. Can SSH Recovery be accessed from the Internet or a remote IPv6 network?
No, ssh-recovery is accepting incoming requests only from IPv6 link-local addresses (fe80::xxx) which are not routable outside the switch domain. Only locally connected IPv6 devices can reach ssh-recovery.
5. How does SSH Recovery authenticate users?
Authentication is done by Linux PAM which is same authentication method as other SSH sessions authenticate. This means that only users which were present in the configuration before rebooting will be able to authenticate with a password or public-key.
6. How can I reconfigure or disable SSH Recovery?
There are multiple SSH configuration options to expand or limit the capabilities. These are explained in the Steps section below.

How to Access EdgeRouter Using SSH Recovery


Back to Top

Option 1 - Discovery Tool with IPv6 Compatible Device (Recommended Method)


The UBNT Discovery Tool will automatically detect and convert the MAC Address into the format needed to access the EdgeRouter if there is IPv4 connectivity for discovery. If IPv4 discovery is unavailable, please use one of the options below.

1. Connect your IPv6 compatible device to the same network as the failed router.

2. Open UBNT Discovery Tool, Scan, and copy the Rescue IP Address

3. Enter the Recovery IP Address as the address in your favorite SSH client.

4. Reboot the EdgeRouter

5. Within 60 seconds after initial boot connect with SSH using an pre-existing username and password.

ATTENTION: The last few characters of the recovery address indicate the interface the PC has used to discover the EdgeRouter. This interface will also be used to connect to the EdgeRouter. If multiple interfaces are active, ensure that the desired interface is used.

Option 2 - Connecting to Another EdgeRouter (Advanced Users)


This second method entails connecting to EdgeRouter from another EdgeRouter on the same link-local IPv6 Network, this method is for advanced users and was built into firmware 1.1.10+. When two EdgeRouters are connected directly or on the same network like with a switch like in the diagram below, users can recover a remote EdgeRouter as long as they have access to another EdgeRouter on the same IPv6 link-local network.

sshRecovery.png

 

CLI: Access the command line interface (CLI). You can do this using the CLI button in the GUI or by using a program such as PuTTY.

1. Enter this command in the CLI of the accessible EdgeRouter

llssh -m <MAC of connected Ethernet interface> -i <interface of this EdgeRouter that is connected to the failed EdgeRouter -u <Username of EdgeRouter in inaccessible state>

2. Reboot inaccessible EdgeRouter

3. Wait for login prompt to enter the password

ATTENTION: If the faulty EdgeRouter has a default configuration on firmware 1.10.0 the ssh-recovery will be available only for 60 seconds after initial boot on interface eth0. Reboot the faulty EdgeRouter to activate ssh-recovery. See configuration options below to extend this recovery time if needed.

In this example, we will log into the EdgeRouter Infinity in the diagram which is connected to the EdgeRouter 4. Therefore, the command used and following result would look like this:

admin@ER-Infinity:~$ llssh -m 0418d6a082d9 -i eth8 -u admin
Converting S/N to MAC: 0418d6a082d9 -> 04:18:d6:a0:82:d9
Connecting to fe80::0618:d6ff:fea0:82d9%eth5 port 60257 as admin
Welcome to EdgeOS

By logging in, accessing, or using the Ubiquiti product, you
acknowledge that you have read and understood the Ubiquiti
License Agreement (available in the Web UI at, by default,
http://192.168.1.1) and agree to be bound by its terms.

  **************************************************
  * This is SSH recovery shell which is accessible *
  * only from LAN via IPv6 link-local address      *
  **************************************************

admin@fe80::0618:d6ff:fea0:82d9%eth8's password: 

Option 3 - Using llssh on Connected IPv6 Device (Advanced Users)


The third method is to use llssh on a connected IPv6 device to connect to your EdgeRouter. This method is for advanced users.

1. Download llssh script using this download link.

2. In this linux example, load the script and specify the MAC address of the failed EdgeRouter, the interface of the PC, and the username of the failed EdgeRouter.

UserPC:~ User$ /Users/User/Desktop/llssh llssh -m 0418d6a082d9 -i en4 -u admin

 

SSH Recovery Service Configuration Options


Back to Top

A default EdgeRouter configuration will allow ssh-recovery for 60 seconds after first boot on the eth0 interface. To adjust these options, the commands below can be set to fully disable the feature, extend the 60 second lifetime, select interfaces for ssh-recovery to listen on, and specify a port for ssh-recovery.

admin@EdgeRouter4# set service ssh-recovery 
Possible completions:
  disabled      Disable recovery SSH service
  lifetime      Lifetime of recovery SSH service after boot
  listen-on     Listen on Ethernet interface
  port          Listening port for recovery SSH service 

Troubleshooting


Back to Top

1. Network is down

UserPC:~ User$ /Users/User/Desktop/llssh llssh -m 0418d6a082d9 -i en0 -u admin
Converting S/N to MAC: 0418d6a082d9 -> 04:18:d6:a0:82:d9 
Connecting to fe80::0618:d6ff:fea0:82d9%en0 port 60257 as admin 
ssh: connect to host fe80::0618:d6ff:fea0:82d9%en0 port 60257: Network is down

Resolution: Use "ifconfig" on the PC or "show interfaces" on EdgeRouter to ensure the correct interface on the PC is being specified in the command.

2. Connecting hangs and never connects

admin@EdgeRouter:~$ llssh -m 0418d6a082d4 -i eth2 -u admin
Converting S/N to MAC: 0418d6a082d4 -> 04:18:d6:a0:82:d4
Connecting to fe80::0618:d6ff:fea0:82d4%eth2 port 60257 as admin

Resolution: Verify that the correct MAC address of the interface on the faulty EdgeRouter is being used.


Related Articles


Back to Top

EdgeRouter - Last Resort Recovery

EdgeRouter - How to Find Device MAC Address


We're sorry to hear that!