UniFi Controller: Add & Fix Devices

Almost every time I upgrade the version of the UniFi Controller, I have to renew the connection to all of the devices on the network. This doesn’t seem to be a one-off, either. It happens across multiple sites.

As annoying as it can be, fixing it is relatively straightforward. But for those that are unfamiliar, let’s review the process.

The adoption process

New devices are ‘adopted’ by the controller, the controller being either a Cloud Key, or the same controller software running on a computer.

To begin the adoption, we tell the device where the controller can be found, and we finish the adoption process in the controller.

Adopting a new device

To start that, find the IP of the device on your network (this should be somewhere in the ‘clients’ page devices should now show up in the devices page, and show ‘ready for adoption’), and then SSH into it (if you don’t have a goto bit of software for this, PuTTY is a good starting place). The host will be the IP of the device you’re setting up (e.g. a USG, access point), and the default username & password will be ubnt / ubnt.

Adopting an existing device

An existing device will have the IP shown in the devices page (not the clients page). Whether the device is not responding, or it’s disconnected following an upgrade shouldn’t make any difference. As long as it was previously managed, it should have picked up the SSH credentials that you set (or were automatically set).

Find existing SSH credentials

If you don’t remember what these details are, you can reveal the password from the settings menu. For the old style interface, just click the settings icon at the bottom of the left menu and look for ‘Device Authentication’ near the bottom:

For the new interface, click the settings icon (bottom of left outer menu), then system (bottom of left inner menu). About two-thirds of the way down the page, look for ‘Network Device SSH Authentication’:

Click the eye icon to reveal your password.

Connect to the device

Now that you have your credentials and the IP of the device, connect using your SSH app of choice. Once connected, you’ll see a prompt ready to receive commands.

set-inform

The set-inform command is one you’ll come back to a few times, so make a note (or hey, bookmark this page. nudge nudge).

# set-inform http://IP-of-your-controller:8080/inform

After running this command, you’ll get the response:

Adoption request sent to 'http://IP-of-your-controller:8080/inform'.
Use the controller to complete the adopt process.

Go back and check the devices page. If all has gone well, you’ll see the the adoption process is continuing and will move onto ‘provisioning’ (or ‘getting ready’ if you’re using the UniFi app).

Troubleshooting

Occasionally, the set-inform might seem to do nothing (this could be down to a number or reasons, but older firmware is a prime reason for this).

Here are a few steps to fix further adoption issues:

Repeat set-inform

I didn’t say these would all be smart suggestions… Trying the same command again will sometimes fix the issue.  To be extra sure, run the second set-inform 10 seconds or so after the first.

# set-inform http://IP-of-your-controller:8080/inform

   * awkward whistling *
   
# set-inform http://IP-of-your-controller:8080/inform

mca command line interface

There doesn’t seem to be any real consensus as to why to try the mca-cli next. It just seems to be the next suggested step when seeking help on the Ubiquiti forums.

If after a factory reset, if set-inform alone doesn’t work, a set-inform within the mca-cli seems to do the trick.

From the first prompt, enter mci-cli and hit enter. You’ll notice that the prompt changes to UniFi#. Now enter the set-inform command as before.

# mca-cli
UniFi# set-inform http://IP-of-your-controller:8080/inform

Adoption request sent to 'http://IP-of-your-controller:8080/inform'.
Use the controller to complete the adopt process.

Factory reset

If that still doesn’t work, a factory reset is the next step. Don’t worry, it’s not as drastic as it sounds (all of the config is stored in the UniFi controller/Cloud Key). After a reset, the devices will be adopted, provisioned and returned to their previous state.

If you’re still in the mca-cli ‘level’, use the exit command to go back to the main prompt, then run the following command:

# syswrapper.sh restore-default

The session will then close as the device reboots. Do not disconnect it from the power while it does this!

Once it’s finished, you should be able to connect via SSH (as if it’s a brand new device, using username & password: ubnt / ubnt), and try the set-inform command again.

Physical factory reset

If all else fails, you can factory reset by holding a paperclip or SIM card tray tool in the reset button for around 10 seconds, depending on the device.

Once it has finished, you’ll be able to connect as above and follow the set-inform procedure.

Summary

Hopefully this helps with UniFi AP, USG and other device adoption issues! If there’s anything I’ve missed, or anything that changes over time, please leave a comment. I’d also be interested to know: Which of the above procedures work best for you?