If you’ve ever set up a Ubiquiti UniFi access point, such as the UBNT UAP, UBNT UAP-PRO, or UBNT UAP-AC-PRO, you’ve had to run UniFi Controller software required to adopt, configure, and manage your UniFi devices. When I set up a UAP-PRO in our house (see my install guide) I ran the UniFi Controller software full-time on a Windows server in the basement. When I upgraded to a UAP-AC-PRO a few months later, I decided to move the UAP-PRO out to our cabin, and because I don’t have a server running 24/7 out there, I temporarily installed the UniFi software on my laptop so I could set up the access point (UniFi software doesn’t need to be running 24/7 unless you want to run a guest portal or track usage data all the time). But I missed being able to monitor the access point, so I looked into what I’d need to do to set up both locations as separate sites and manage their access points from a single UniFi Controller… and it turns out it’s not very hard to do.

Of course, the reason it’s not very hard is because the Ubiquiti UniFi hardware devices are enterprise-level products, designed for deployment and management of multiple hardware items across multiple locations. A residential user (like me) managing a just couple of UniFi APs at just a couple of locations should be easy.

One option would have been to configure the UAP-PRO at my cabin to communicate with the existing UniFi controller already running at my house, but that would have required tinkering with dynamic DNS and port-forwarding. That’s easy enough to do, and I already do it for a few other devices, but since I own a handful of Linux-based servers running at a colo center (which have vastly superior network uptime compared to a home-based server), I decided to migrate management of both UniFi locations to a self-hosted or “cloud-based” UniFi controller. This article explains how I did it.

Before You Start

Because the Ubiquiti UniFi Controller is a Java app, you have to have Java installed on your system so that it can run .jar files. On a CentOS or RedHat-based system, do this with either:

# yum install java

or

# dnf install java

Step 1: Back Up Your Existing UniFi Controller Data (optional)

If you’re already running a local UniFi Controller (meaning one that sits on the same L2 network subnet as your access points) and you’re using this guide to migrate to a self-hosted or cloud-hosted controller, you can optionally backup your existing local site’s UniFi Controller configuration and usage data. Once you’ve got the hosted controller up and running, you can restore your settings and data on your new controller. This isn’t required, and if your network isn’t complex it’s simple enough to reconfigure everything from scratch on the new controller, but it can speed things up, and it’s never a bad idea to make backups.

If you don’t have an existing controller, go ahead and skip to the next step. But if you do, here’s how to back it up:

1. Log in to your local UniFi Controller’s Web GUI.
2. Go to Settings, then click on Maintenance in the left column.
3. Look for Backup, and select the Backup Data Retention amount you want to keep. I selected All time when I did mine.
4. Save the resulting file on your hard drive, and keep it handy if you want to restore it to your new hosted controller in a few minutes.

Don’t worry if you’re backing up data and settings from an earlier version of the UniFi Controller than the new one you wish to set up. I backed up data from a V3 controller and successfully restored it on a hosted V4 controller… though I did have to massage the admin password a bit after restoring (I’ll address that near the end of this article).

Once you’ve got your existing controller backed up, you’re ready to start setting up your new hosted one.

Step 2: Install the UniFi Controller on the New Host

How you set up your hosted UniFi Controller software will vary depending on the host platform. I recommend using the most current version of the UniFi Controller software as possible, even if you’re migrating from an earlier version. As of the writing of this article, I’m running UniFi Controller version 4.8.18 on a CentOS box, and was able to follow these v3 install instructions on UBNT’s help site. I find the Linux-based controller the easiest to install for a 24/7 hosted server, but it’s also pretty straightforward to run the Controller software as a service on a Windows box, which is what I used to do on my initial UniFi Controller install at home.

It’s also very simple to run the UniFi Controller on an Amazon Web Services Ubuntu AMI. And while the UniFi Controller software is available for Mac OSX users, and I used it successfully on my MacBook Air to initially set up the “hand-me-down” UAP-PRO at my cabin, the UBNT forums have multiple discussions ways to run the controller full-time on OSX… though there’s no “official” right way to do it (yet?). If you’re looking to run a cloud-based or self-hosted UniFi controller, I personally find the Linux-based version the easiest to install, and also the easiest to upgrade when new versions of UniFi Controller are released.

The CentOS UniFi Controller install instructions will walk you through making sure you have Apache and PHP set up on your server, and then help you manually configure the MongoDB repo and install the database. Once that’s all installed with default options, you’ll create a service file that automatically runs the UniFi Controller java software when the system boots. The AWS + Ubuntu instructions will also get you up and running in short order, if that’s your preferred hosting solution.

Whichever platform you choose, follow the appropriate steps to get the UniFi Controller software up and running on a publicly available IP address before moving on.

Step 3: Open Firewall Ports

Assuming you’re following healthy security practices for a publicly-visible server, you’ll need to open up a few ports to allow the UniFi Controller to communicate with remote UniFi access points. The CentOS instructions recommend the following ports:

• TCP 80 (which is probably already open if you’re running a web server)
• TCP 8080 (which will redirect web traffic to secure port 8443)
• TCP 8081
• TCP 8443 (the port that runs the secure UnFi Controller web GUI)
• TCP 8843
• TCP 8880
• TCP 77117

The Amazon AWS instructions for a UniFi Controller running on an Ubuntu AMI are slightly different, and recommend opening these ports:

• TCP 8080
• TCP 8443
• TCP 8843
• TCP 8880
• UDP 3478

Follow whatever steps are necessary to open the required ports for your particular server’s firewall, so that your UAPs will be able to communicate with the UnFi Controller, and you’ll be able to securely access the GUI via a web browser.

Step 4: Run the UniFi Setup Wizard

Once the UniFi Controller is running and the appropriate ports are open, use a web browser to access the controller’s Web GUI on port 8080 on the IP address of your hosted controller:

http://xxx.xxx.xxx.xxx:8080

it will redirect you to the GUI on secure port 8443:

https://xxx.xxx.xxx.xxx:8443

By default, the first time you access the UniFi Controller’s Web GUI, it will start the UnFi Setup Wizard:

UniFi Controller Setup Wizard

Go ahead and select your country and time zone on Step 1 of the Wizard. But when you get to Step 2, the UniFi Controller won’t detect any UniFi devices — because none of the devices will be on the same L2 subnet as the controller. So go ahead and skip the “Discover” step. You can also skip the rest of the steps and deal with them from within the standard GUI, or import your settings later if you made a backup in Step 1.

Once the wizard is done, you’ll be at the login page for the UniFi Controller. Use ubnt as both the username and password. Once you’re into the main page of the UniFi Controller, you can restore your backed up settings, or skip to setting up your site(s).

Step 5: Restore your UniFi Controller Backup

Skip this step if you’re not migrating from an different UniFi Controller or don’t have a UniFi Controller backup.

If you did make a backup, now is the right time to restore it. Login to your hosted controller’s GUI and go to Settings, Maintenance, Restore, then find the backup file you created on your hard drive. The restore also restores existing admin usernames and passwords, so you can test these out by logging out and logging back in with your previously existing credentials.

Step 6: Set up Multiple Sites (optional)

If you have multiple sites you want to manage, it’s best to get them all configured before you start adopting access points (though it’s not difficult to move access points between sites in the GUI).

You can add new sites by clicking the drop-down that shows your default site in the top-left corner of the UniFi Controller GUI, and you can edit any existing site names and options via Settings, Site. You have to select a site from the top-left drop-down in the GUI before changing any of its settings. You can’t change a different site’s settings if it’s not currently “active” in the GUI.

Step 7: Choose Your L3 Adoption Method

Before proceeding, it’s important to understand the difference between a Level 2 (L2) network and a Level 3 (L3) network. There are actually 7 network levels in what’s called the OSI model, but the two we’re dealing with here are L2 (the “Data Link” layer) and L3 (the “Network” layer).

In the simplest terms, devices connected via the L2 network sit on the same subnet — almost always behind the same router. Devices connected via the L3 network sit on different subnets and therefore need routers between them to communicate. Since your UniFi Controller isn’t running on the same subnet as your access point(s), you need to configure your access points to communicate with the controller over the L3 network.

Adopting UBNT access points over an L3 network can sometimes be simple… but sometimes can be a bit frustrating. Depending on your network setup, you may have to jump through a few different hoops to allow your new UniFi Controller to “see” your remote access points.

UBNT has an article that gives an overview of the different methods of L3 adoption, and that’s what I used as a starting point.

It’s also important to remember that the UniFi Controller software doesn’t proactively “go searching” for access points that need adoption. Instead, it’s always reactively “listening” for access points to “talk” to it. Unadopted access points say “Hi! Do you want to adopt me?” while adopted access points say “Let me tell you about what I’ve been doing!” Once you’re running the UniFi Controller software and have the correct ports open so it can “listen,” you’ll need to focus your efforts on telling your access points to “talk” to the new hosted controller.

Using DHCP Option 43 to “Talk” to the UniFi Controller

At the cabin, I use a UBNT EdgeRouter POE-5, which is configured to act as the DHCP server for all my devices there — including the UAP-PRO. If you also have an EdgeRouter acting as the DHCP server for your access point, you can use the EdgeOS GUI to open the DHCP settings and type in the IP address of your hosted UniFI Controller in the UniFi Controller field. Then, when the access point renews its DHCP lease, the DHCP server will set DHCP option 43 as the address of the controller, and the access point will know who to “talk” to.

Use the EdgeRouter’s DHCP settings to set Option 43 to the UniFi Controller’s IP address

Using DNS to “Talk” to the UniFi Controller

At our main house, I also use an EdgeRouter, but because I don’t use it as our DHCP server, I couldn’t follow the same steps for DHCP Option 43. I use a Windows 2008R2 server as both the local DNS server and DHCP server, so I could have set DHCP Option 43 manually, but instead I chose to set up the DNS server to resolve local requests for the hostname “unifi” to the IP address of the controller. A factory-reset UBNT access point will attempt to “talk” to http://unifi:8080/inform, so if your DNS server forwards that request to the hosted controller when that talk attempt occurs, your controller should be able to “hear” it.

As explained in this UBNT forum thread, you can also the set-inform command via the CLI on the access point itself to tell it which controller to “talk” to. Sometimes this works, and sometimes it doesn’t. The easiest way to nudge your access points into “seeing” and “talking” to your new hosted controller is to reset them to factory settings by “forgetting” them in your old controller.

Step 8: Forget the Access Point(s) in the Old UniFi Controller

To prevent your original UniFi Controller from “arguing” with your new hosted controller over who should adopt your access point(s), you should “forget” the access points in your old controller before adopting them from the new one. This will reset your access point to its factory settings, and hopefully your DNS or DHCP options have been properly configured to allow them to “see” the new controller.

IMPORTANT: Wireless clients won’t be able to use access point to access the network between the time it’s forgotten by your old controller and adopted by your new one, so keep this in mind when choosing when to migrate your access points between controllers.

To “forget” an access point, login to your original UniFi Controller’s GUI and click on Devices. Click on an access point to display its Properties, then select Configuration.

“Forget” your access point(s) on your existing UniFi Controller before adopting it on your hosted controller

Find the FORGET THIS AP option, then press the FORGET button (you don’t have to select an option for where to move it). The tab warns you that you’ll lose all configurations and history associated with the access point, but if you backed it up in Step 1 and restored it in Step 5, the configuration and history is already loaded onto the hosted controller.

Once your old controller has “forgotten” your access points, cross your fingers and check to see if they appear a few minutes later (after they reboot themselves) in the Devices screen of your UniFi Controller GUI. If they don’t, you may have to manually reset the access points.

Resetting the Access Point

If you’re unable to access your old controller or can’t reset your access point by “forgetting” it, you can manually reset it via SSH. I did this on the access point at the main house. I ssh’d into the UAP-AC-PRO and reset it to factory settings with:

syswrapper.sh restore-default

When the access point rebooted a few minutes later, it tried to talk to http://unifi:8080/inform by default, and because my Windows-based DNS server resolved it to the IP address of my hosted UniFi controller, the AP appeared in the Devices list on my hosted controller as ready to be adopted.

Manually forcing set-inform on a UAP

If none of the above steps work for you to make your access point appear in your devices list for adoption, you can try manually telling your access point where to “inform” by ssh-ing to the access point and typing the following:

mca-cli
set-inform http://ip-of-controller:8080/inform

If all else fails, try resetting to factory default again, and check your DHCP and/or DNS options, check your UniFi Controller’s firewall settings, etc. Also make sure your access point can ping the IP of your controller. The steps in this UBNT forum thread can help you if things aren’t going right.

Step 9: Adopt your Access Point(s) in the Hosted UniFi Controller

Once your access point(s) show up in your hosted UniFi Controller, go ahead and adopt the appropriate one(s) into the appropriate site(s). If you adopt one into the wrong site, you can use the FORGET feature to move it to a new site, as long as that new site is already configured on your new hosted controller.

If you didn’t restore your settings from backup, go ahead and run through all the configuration steps you’d normally follow to set up your wireless network name and security settings, as well as any other UniFi options.

Step 10: Tweaking some Hosted Controller Options

When your hosted controller is working properly, I recommend doing the following for each site. Go to Settings, then Controller. Put in your hosted controller’s IP address or hostname in the Controller Hostname/IP field and check the Override inform host with Controller Hostname/IP. You should also uncheck the Make controller discoverable on L2 Network option.

Step 11: Fixing the Salted Password Hash Issue

If you set up a new hosted controller from scratch without restoring a backup from a previous controller, you won’t have to worry about this problem. But in some cases, if you restored an older backup onto a newer version of the controller, you’ll get an error if you attempt to change the password of the admin user.

I initially reported this bug on this thread in the UBNT forums, and it turns out the cause of the bug is that newer versions of the software use a salted password hash, while older ones didn’t. The solution to manually overriding the unhashed password with a hashed one is in that thread, along with a number of options for generating the salted password hash on a number of platforms. I suspect later versions of the UniFi Controller will fix this bug, but for now, that thread has the work-around.

Step 12: Connect your Hosted Controller to UniFi Cloud Access (optional)

This is an optional step, but if you want to connect your hosted controller, or even multiple hosted controllers or UBNT Cloud Keys, to Ubiquiti’s free UniFi Cloud Access service, you first need a free UBNT account from https://account.ubnt.com/ (if you already have a UBNT Community Forum account, it’s the same account). In your hosted controller, go to Settings, then Cloud Access, the press the ENABLE CLOUD ACCESS button. Enter your UBNT account credentials (there’s also a link there to set up an account if you don’t have one), and press the green ENABLE CLOUD ACCESS BUTTON. It should show “CONNECTING” and then “CONNECTED.”

You can now log in at https://unifi.ubnt.com/#/ to access your hosted controller(s) via UBNT’s Cloud Access, which will allow you to centrally monitor and manage multiple controllers and Cloud Keys.

Final Steps

With your new hosted UniFi Controller up and running, you can now monitor and manage multiple locations from a single controller. Adding additional sites and devices later will be easy, since you can simply configure the hardware devices to point to the hostname or IP address of your hosted controller, and (fingers crossed) everything should “just work.”

As always, I welcome your questions, comments, and feedback in the comments. However, for support questions, you’re far better off asking in the UBNT forums. I don’t answer support questions here in my blog, but I hang out on the UBNT forums often, and will gladly chime in there on support questions I can help with.

Enjoy your new hosted Ubiquiti UniFi Controller!