Adopt a UniFi USG Router to a Remote Controller

My customer has a UniFi controller running on their Windows server. They’re ready to add a USG router, which I want to configure in my office before going on site. This qualifies as a “remote adoption” or “L3 adoption.” I’ve spent several frustrating hours over a period of many days trying to get this to work. UniFi documents remote adoption for access points here, but there is apparently no documentation on adopting USG devices or switches. Here is what finally worked for me.

Remote Setup

The USG must be able to reach the remote controller on the “inform port,” TCP 8080 by default. On the remote router, forward that port to the computer running the controller. Theoretically you shouldn’t need to open port 8080 in that computer’s Windows firewall. but I’ve seen one instance where I had to open firewall ports explicitly.

If you are using https://unifi.ubnt.com to access the remote controller, you do not need to open TCP port 8443; in fact, this article recommends that, for security reasons, you don’t open that management port.

When I was struggling to get this to work, I updated the controller to version 5.8.24. Not sure if that’s necessary.

Local Setup

In your local office, you’ll need two computers, four network cables, a switch and a router connected to the Internet.

Plug both the WAN and LAN ports of the USG into your local switch, behind your local router:

  • The WAN port must be able to pull (via DHCP) an IP address that lets the USG connect to the Internet.
  • The LAN port is used for configuring the USG.

On the first computer, open a connection to the management interface of the remote controller.

Change the IP address of the second computer to 192.168.1.10. This puts it on the same LAN as the USG. Use Putty to open an SSH connection to the USG at 192.168.1.1 with the default username password “ubnt”/”ubnt”. (Alternatively, you can connect to the USG’s Console port with a console cable like this, then use Putty to establish a Serial connection to the cable’s COM port—check your computer’s Device Manager—at 115000 baud, 8 data bits, 1 stop bit. no parity, XON/XOFF flow control.)

Type show interfaces. You should see eth0 with an IP on your local network and eth1 with the IP address 192.168.1.1.

Type ping 8.8.8.8 to confirm that you have Internet connectivity. Press Ctrl-C to stop the ping.

If you are unsure whether the USG is at its factory default state, run this command to reset it:

sudo syswrapper.sh restore-default

Type info to see the current firmware version. You should probably upgrade the USG to the latest firmware version. Instructions are here. I did this as an offline upgrade, but as long as the USG is connected to the Internet, an Internet upgrade should work. For firmware version 4.4.22, the commands would be:

sudo su
upgrade http://dl.ubnt.com/unifi/firmware/UGW3/4.4.22.5086045/UGW3.v4.4.22.5086045.tar

Remote Adoption

Forget Chrome Adoption

The article on remote adoption lists several methods for doing a remote adoption and recommends the Chrome Web Browser approach. Maybe that works for access points, but I could not find any combination of settings that would get it to work for a USG. Part of the confusion is that the UI has no fewer than three places to set the inform URL, plus four places for username and password, with no explanation of which credentials are required where. Is one the current credentials and another the credentials after adoption? Who knows. No matter what I did, I kept getting the message “There was an error setting inform for <MAC address>”:

USG Adoption 1

Forget Chrome adoption.

Update August 28, 2018 I tried the Chrome adoption technique later with an AP-AC-LR access point and it worked.

Use SSH Adoption

What worked for me was SSH adoption, as described here.

1. SSH into the USG and run this command, substituting the controller’s public URL or IP address (note that it is HTTP, not HTTPS):

set-inform http://remote.mydomain.com:8080/inform

USG Adoption 2

2. Back on the other computer, on the one connected to the controller’s UI, you should see the USG appear with the state “Pending Adoption”. Click on the Adopt link:

USG Adoption 3

The state of the USG should change from “Pending Adoption” to “Adopting”:

USG Adoption 4

3. Now go back to the SSH session connected to the USG and run the same set-inform command again (yes, you must run set-inform twice):

USG Adoption 2

4. Back in the controller UI, you should see the state change to “Provisioning”, then “Connected”:

USG Adoption 5

USG Adoption 6

Your SSH session will disconnect. If you want to log in via SSH again, you’ll need to use the username and password configured in the controller under Settings > Site > Device Authentication.

5. If you see the little yellow triangle as shown above, the USG is probably unable to reach the controller server as a STUN server. (See this article.) If you forward STUN port 3478 (UDP) to the controller and open it in the computer’s firewall, the triangle should go away:

USG Adoption 7

You should now be able to continue configuring the USG through the controller.

Bonus:  Set-Inform on a Switch

If you SSH into a UniFi switch and try to run the set-inform command, you’ll get the error “sh: set-inform: not found”. Very confusing that switches do not work the same way as routers and access points. Thanks to this post, I learned that, “You must run mca-cli first, then set-inform”.

Update 19 January 2019 According to this post, you have to use mca-cli first on an access point as well. Not sure if this is (still) true, since the AP does respond to the set-inform even from the “main” command prompt.

11 thoughts on “Adopt a UniFi USG Router to a Remote Controller

  1. Joost

    Very useful, thank you very much. Have adopted many remote Access Points using the mca-cli set-inform method, but didn’t know the USG would support that as well; neat!

  2. Michael T Parker

    My setup is I have both my parents (divorced) using one Unifi AP each as their own site in the the controller at my home (unifi Cloudkey gen2 +) set-inform is working fine with SSH into both my parents AP’s through my home hosted controller

    for set up I took the AP’s to work to be on a different network than mine and brought them online through that Ubnt link. once online brought them home and made sure they had set-inform set to my external Public ip shipped them to my parent and they popped online and my controller sees them just fine.

    everytime my IP changes I ssh in directly to the AP in their from their laptop (using team viewer) and use set-inform command and it comes back as “connected”

    I started using a DDNS and that works even better (so far)

  3. Brian Christensen

    Great article! I look forward to trying these steps soon! I usually will have the exact same scenario, but there will usually be about a 24 hour delay, between the time I am done offsite configuring (which would be the steps in this article), and the time the offsite configured USG arrives onsite (at its final destination). Do you know what happens to the *existing* UniFi devices already onsite (like a network switch and access points), during that about 24 hour time-frame? Will those existing devices stop working during that about 24 hour time frame (because the offsite configured USG is disconnected in transit to the site)? Or, perhaps because the old router will have the same static LAN IP address, things will keep working fine, until the old router and the new (offsite configured) USG are swapped out onsite? While I continue to have need to do this for my clients, I have never done this yet *because* I don’t have the answer to that question. Thanks again for the great article, and thanks in advance for any reply to this question of mine!

  4. Mark Berry Post author

    @Brian, where is your controller? As long as the existing devices can reach the controller, they should still be manageable whether the USG can be reached or not. In fact, you don’t need a USG at all; you can start with just a switch and/or access points. Also, if the controller is *not* reachable, all devices, including the USG, should continue to function with the last configuration that they downloaded; you just won’t be able to change any settings until they can “phone home” to the controller again.

  5. Brian Christensen

    @Mark…..somehow, I never saw a notification of your reply back from January 27th (probably my fault….sorry!). My controller is in the cloud (HostiFi). However, my question wasn’t about *manageability* of devices during that approximately 24-hour delay (between offsite configuration, and onsite install)…..I knew that would be fine :) My question was related to: 1) A USG has been configured into the UniFi “site,” and then that USG disappears for around 24-hours (again, the usual time between my offsite configuration, and my onsite installation). Therefore, how do the UniFi devices handle their *networking* tasks, given that they’ve been told a USG is present, but a USG is not present (for around that 24-hour period). Perhaps it does not matter, as long as the router that is about to be replaced by the USG has the *same* LAN IP address that the USG has been pre-configured with? Thanks again!!

  6. Mark Berry Post author

    @Brian, that makes sense to me: if you pre-configure an AP to route through gateway 192.168.1.1, and that gateway is initially an old non-UniFi router, it ought to work if you connect the new AP to the old router. But wouldn’t you deploy the new networking equipment all at the same time? So the USG will be there, and the APs will be there, so the APs can find the USG even if you _do_ change the LAN subnet. Your main challenge, I would think, is making sure that the USG gets a new _external_ IP. That’s what will change between your office and the new site. That my require some configuration of the upstream device, e.g. I have to configure my AT&T U-Verse modem to see the new USG as a DMZ device so the USG gets the external IP of the U-Verse modem.

  7. Thomad

    Hi Mark:

    I think I tried all that but maybe my setup is a bit different. I have a usg-3p and it works great, until I try to adopt it to my controller in the cloud (hubox). As soon as I do that, the internet access gets switched off for all devices. From the usg I can ping and it works. Even the configure screen says connected to the internet. And I can access it through my online controler….but…no device on my local net has internet. Any idea what I am doing wrong?

    Thomad

  8. Mark Berry Post author

    @Thomad, I’ve never used a USG-3p, but since you say you can access the USG through your controller, it sounds like you’ve already accomplished the goal of this article, to adopt the device to the controller. If it worked before adoption, then it stopped passing Internet traffic, I’d guess that there is something configured in the controller that is different from the default. Could be a different IP range, or DHCP is not configured at all, or a firewall rule is blocking traffic… There should be some tutorials online about how to configure your first USG network.

  9. Petter Norman

    Thanks a lot!
    This was an easy to follow tutorial. And it works. Had to redo it a few times. Probably I made some mistakes during the process. But after a while I got it running.
    I have set it up at home with the second USG connected to my backup internet connection, while the Cloud Key is running on the net under my primary connection.

    (hope it still works when I move the second USG to another physical location with another service provider)

Leave a Reply

Your email address will not be published. Required fields are marked *

Notify me of followup comments via e-mail. You can also subscribe without commenting.