UniFi security gateways, cloud controllers and VLAN-tagged WANs, oh my!

UniFi security gateways, cloud controllers and VLAN-tagged WANs, oh my!

or Adopting a UniFi Security Gateway from a cloud controller

Recently I have been doing some work with Ubiquiti's awesome UniFi range of devices. Namely, installing gateways and access points for a few clients and friends.

The UniFi hardware is solid, and most of the features are handled in software by what they call a hybrid cloud controller (which is nothing more than a Java app with a nice web frontend). You can buy a little computer stick (called a Cloud Key) with the software pre-installed, install it on a personal computer inside your network (Mac, Windows or Linux), or take my approach: install it on a cloud instance on Digital Ocean (any cloud provider is supported).

However, if you choose to install it outside of your local network, you'll find that it makes adopting devices a little trickier (at least for the initial connection) because you can't make use of Layer 2 adopting (what I like to call "magical wavey adoption funtimes").

Note: this post assumes you have a working cloud controller already set up.

The problem

For a couple of sites where I installed UniFi kit, I had to configure a UniFi Security Gateway (USG) on a fibre broadband connection provided by Vodafone NZ. But...

  • These connections (2 sites, remember?) are presented as DHCP-assigned addresses inside tagged VLAN 10 on one of the Optical Network Terminal's ports.
  • The USG's initial setup page did not (as of this posting) support assigning a VLAN ID to the WAN port
  • Without a working internet connection, the UniFi devices cannot see the cloud controller, thus being "unadoptable" and "unprovisionable"

The solution

After many hours of head-desking, I managed to assemble a reliable set of instructions for configuring a factory-reset USG to appear in a cloud controller.

Starting from a factory-reset controller (or one straight out of the box), plug a network cable between your computer's network port (yes, you'll need one of these) and the USG's LAN1 port. Wait for the USG to assign you an IP address, then open an SSH connection to the USG's LAN IP address (normally under the user ubnt (default password is ubnt).

Then type the following commands, pressing [ENTER] after each line:

edit interfaces ethernet eth0
delete address
delete firewall
set vif 10 address dhcp
set vif 10 firewall in name WAN_IN
set vif 10 firewall local name WAN_LOCAL

Note: Replace the three 10 above with the VLAN ID your ISP uses.

From here, you should be able to ping or similar. Then it's just a matter of setting the right inform URL.

That is easily done via the SSH connection too. You'll need to run the command below twice, pausing in between runs to click Adopt on your cloud controller's Devices page.

set-inform http://your-controller-address:8080/inform

Note: Replace your-controller-address accordingly.

Once you start adopting, your USG will reboot a couple of times, meaning you'll be offline for maybe 5 minutes or so. Don't freak out. If it doesn't work, try again, making sure to follow the steps above to the letter (it took me a few tries to get it just right).



Professional site reliability engineer, amateur chef, practicing traveller.

View Comments
Next Post

Cloud-Init doesn't execute commands in runcmd section? There's a fix for that...

Previous Post

Tread lightly, a love letter to a bag

Success! Your membership now is active.