Recover a bridge

A bridge proves who it is with a private key held in its state directory. nodelets bridge recover gives a bridge a new key under the same bridge ID, so its Nodelets keep their IDs, and retires the old key for good.

When you need it

• You stopped the key. You chose Stop key on the Account page, for example because you suspect someone copied the bridge’s state directory.
• The bridge is refused with an old key. The bridge changes its key once a day. A machine restored from a backup, or a container started from an image with the state directory baked in, holds a key from before the last change. The cloud refuses it as an old key of this bridge.
• The machine was replaced. The new machine has no state directory.

On the Account page, under Bridges, the bridge’s status reads Key stopped or Refused, with the reason and the time, and a notice offers the recover command. nodelets bridge status on the machine shows refused with the reason. The bridge keeps both key files and keeps retrying, so nothing is lost while it waits.

Stop a key first

If you suspect a copy, stop the key before you recover:

1. Open Account.
2. Under Bridges, choose the stop button beside the bridge, and confirm Stop key.

The key is refused at once and the bridge disconnects, so its devices stop responding. The bridge ID, its Nodelets and their IDs stay. A stop always takes effect, even while a key change is under way.

Recover

On the bridge’s own machine, run:

nodelets bridge recover

The command signs you in as the owner. If nodelets login saved a session on this machine, it uses that session and says that it stays on the machine. Otherwise it prints a link and a code to approve in the browser, keeps that sign-in in memory, and ends it when it finishes.

It then makes a new key inside the bridge service, proves the service holds it, and commits it. It prints:

• Bridge recovered and the bridge ID
• the new key fingerprint, which the Account page shows for the same bridge

The bridge reconnects on the new key. The private key never leaves the service, and your session never enters it.

On a replacement machine

Install the bridge on the new machine first. See Install and register a bridge. Then run nodelets bridge recover instead of bridge register. With no bridge identity on the machine, the command lists your bridges and asks which one this machine replaces.

The bridge ID survives, but the Nodelets do not come across: their IDs lived in the old machine’s state. The Account page marks each of the old Nodelets as having no live device yet, and says which keys and connections name it. Add the devices again with nodelets thing add; they become new Nodelets with new IDs.

A machine restored from a backup keeps its Nodelet IDs. A Thing removed since the backup shows as removed in nodelets thing list and cannot return.

What recovery cannot do

• Prove where it ran. Recovery trusts your signed-in session. It cannot tell whether the command ran on the bridge’s machine. Compare the fingerprint it prints with the one on the Account page.
• Prevent a lockout. Someone who copies a key and uses it first can lock out the real bridge. The real bridge is then refused, you see why, and recovery restores it.
• Recover a disabled bridge. A disabled bridge cannot come back. Remove it from the machine with sudo nodelets bridge uninstall --purge and register the machine as a new bridge.

Stops, recoveries and refused attempts appear on the Account record.