Preface
- This is a technical doc for advanced user. The purpose is to get the UniFi controller running. Refer to UniFI documentation about adopting devices and other configuration issues.
- This is for Firewalla Gold series boxes n Router Mode only.
- Installing Unifi Controller on Firewalla Purple series boxes is not recommended due to memory limitations. You can use Unifi switches and APs with Purple series boxes. If you have a Firewalla Purple box, just run the controller somewhere else. This can be a computer, Raspberry Pi, NAS, etc.
- Incorrect settings of port forwarding will result in ports being opened on your WAN interface.
See Important Note: Preserve Resources below.
Step 1: Install Unifi Controller docker image
You have to choose:
- A network as your docker network, we will use 172.16.1.0/24 in this tutorial.
- A static IP for your unifi controller instance, we will use 172.16.1.2 in this tutorial.
Use the values recommended in this guide unless you know what you are doing and need to change these.
1. Create folder /data/unifi. This is where your docker container will reside.
sudo mkdir /data/unifi
Note that unifi takes nearly 800Mb of disk space in the current controller release.
2. Create the file, /home/pi/.firewalla/run/docker/unifi/docker-compose.yaml.
# make unifi storage directory mkdir /home/pi/.firewalla/run/docker/unifi/ # change directory cd /home/pi/.firewalla/run/docker/unifi/
# edit with your favorite editor
vi /home/pi/.firewalla/run/docker/unifi/docker-compose.yaml
Add the following to docker-compose.yaml
version: "3"
services:
unifi:
container_name: unifi
image: jacobalberty/unifi:latest
volumes:
- '/data/unifi/:/unifi'
restart: unless-stopped
networks:
default:
# static IP address for unifi controller
ipv4_address: 172.16.1.2
networks:
default:
driver: bridge
ipam:
config:
# your chosen docker network here
- subnet: 172.16.1.0/24
For detail, please refer to Unifi Controller docker image guide at https://hub.docker.com/r/jacobalberty/unifi
Also, once you have your YAML file, be sure to validate it with a service like https://www.yamllint.com/. It is very easy to have a small error that causes things to fail.
Note: You may choose your favorite docker image for Unifi Controller or build your own. The overall steps are the same.
3. Start the Unifi docker container.
sudo systemctl start docker-compose@unifi
Step 2: Add routing rule for docker network
Run the following commands:
sudo ip route add 172.16.1.0/24 dev br-$(sudo docker network ls | awk '$2 == "unifi_default" {print $1}') table lan_routable
sudo ip route add 172.16.1.0/24 dev br-$(sudo docker network ls | awk '$2 == "unifi_default" {print $1}') table wan_routable
sudo ip -4 rule add from all iif br-$(sudo docker network ls | awk '$2 == "unifi_default" {print $1}') lookup lan_routable priority 5003
This command may need to be run every time the docker container is started.
If you are using Gold SE, run one more command to add SNAT for the docker network.
sudo iptables -t nat -A POSTROUTING -s 172.16.1.0/16 -o eth0 -j MASQUERADE
Step 3: Add DNS entry for Unifi Controller
Use Firewalla's Custom DNS rules to create a DNS record for "unifi" to 172.16.1.2 and then access the controller at https://unifi:8443 See the Custom DNS rule tutorial.
Note: The default inform URL for Unifi devices is http://unifi:8080. This is the reason why the above entry needs to be added to the dnsmasq configuration so that Unifi devices will inform the unifi controller in docker via this URL. If the inform URL is changed on devices, you may need to set the inform URL back or update the Custom DNS rule to the right domain.
Step 4: Access Unifi Controller from Gold managed network
To access the controller, try https://172.16.1.2:8443/ and login to check for Devices in your network.
You can make it easier to remember how to access the controller using Firewalla's Custom DNS rules. For example, you may create a DNS record for "unifi" to 172.16.1.2 and then access the controller at https://unifi:8443 See the Custom DNS rule tutorial.
You should be able to "adopt" UniFi devices as needed and then see all your devices in both Firewalla and the UniFi Controller.
Step 5: Persisting The Configurations
You must be on firewalla 1.971 or later for this
- If you have installed UniFi controller before 1.971, please change your docker-compose.yaml file accordingly and run the following commands
sudo docker-compose down
create folder /home/pi/.firewalla/config/post_main.d and the following file
/home/pi/.firewalla/config/post_main.d/start_unifi.sh
#!/bin/bash
sudo systemctl start docker sudo systemctl start docker-compose@unifi sudo ipset create -! docker_lan_routable_net_set hash:net sudo ipset add -! docker_lan_routable_net_set 172.16.1.0/24 sudo ipset create -! docker_wan_routable_net_set hash:net sudo ipset add -! docker_wan_routable_net_set 172.16.1.0/24
now change the permissions
chmod a+x /home/pi/.firewalla/config/post_main.d/start_unifi.sh
And you are ready to go.
If the docker service doesn't start, please follow this guide to reset your docker service. https://help.firewalla.com/hc/en-us/articles/360060535553
Updating the Unifi Network Application (Controller)
If you need to update the Unifi Network Application you can use these commands after using ssh to access your Firewalla.
cd /home/pi/.firewalla/run/docker/unifi
sudo docker pull jacobalberty/unifi:latest
sudo docker container stop unifi && sudo docker container rm unifi
sudo docker-compose up -d
sudo docker ps
sudo docker system prune
Important Note: Preserve Resources
Docker containers can range from small to fairly large and the upgrade process means downloading a new image before deleting the old container. UniFi Controller is a large docker image. So be sure to use docker prune to get rid of unused containers and images or you may easily run out of space on Firewalla.
All product names, logos, and brands are the property of their respective owners. All company, product and service names used in this website are for identification purposes only. Use of these names, logos, and brands does not imply endorsement.
Comments
124 comments
Is there something that should be done after step 1 and before step 2? I tried running the command in step 2 and got the following error:
Error: No such network: unifi_default
Error: any valid prefix is expected rather than "null".
So I got this figured out today and Unifi Controller is up and running. Here's what I didn't know and the guide didn't make entirely clear. Probably bc this guide is for Pros, which I am not.
After step 1 you need to run the following command: docker-compose up -d
Once the compose file is executed and the container is pulled you can move onto Step 2.
I misinterpreted step 3 as needing to manually create a file containing those 2 commands and place it into a directory. What it really means is just run those 2 commands making sure you replace the GOLD_LAN_IP with your Gold's IP address. Once I did that I was able to get to the Controller setup wizard.
The last hurdle is that I wasn't able to use my Ubiquiti account to create the Site in this controller, so what you have to do is to create a local account. I can't remember what you click to do that, but it's not hard to find.
Now, that I did all of that I was able to get into the controller and my switches were there and adoptable.
If you are a complete n00b like me hopefully this helps.
Thanks, Blake!
I would say step 3 is not a typical way for documentation to show that those are shell commands, so I made many of the same assumptions you did. Something like this might be better.
# Restart DNS Service
Now I have the unifi controller running on FWGold! I'm thinking I may hold off migrating from the controller I have on my Synology to allow FW to harden the release a bit more. But it is great to know I can consolidate if I want to.
@Blake
Updated the doc that you don't have to run command docker-compose up -d, sudo systemctl start docker-compose@unifi will do everything.
@Michael
Updated the doc!
Now that Blue Plus contains docker support, will this become available on those as well?
Yes, there will be a separate doc on Blue Plus.
So I had to reboot my firewalla and attempted to follow this guide again and I can't get the controller functioning. I even removed everything I could find related to unif and run through the process and I can't get to the controller by using my LAN IP. When I try to run the compose command I get this error:
ERROR: for unifi Cannot start service unifi: Invalid address 172.16.1.2: It does not belong to any of this network's subnets
I'm pretty sure you updated the guide since the first time I went through it and I can't figure out what all changed to troubleshoot. Any help would be appreciated.
Did you check steps 2 & 3 which aren't permanent ?
Yes, I completed steps 2 and 3 again. I went through the whole thing, and then when I tried to reach the controller it failed to load the page. It says failed to reach the server.
@Blake Try sudo docker network rm unifi_default and then sudo docker-compose up -d
If not working, sudo docker-compose down and start over again.
That worked! So I ran the first command, then moved to the docker unifi directory and ran the second command. Then I completed step 2 and 3 of the guide again and I can finally get to the controller. I had to setup a new local admin account and couldn't use my UI account but I'm in. Thanks.
Been using this for weeks now, love it !!
If you guys have some time, could you give a shot at "home assistant" ?
Docker install is easy but networking...
Installation on Docker - Home Assistant (home-assistant.io)
@nicolas, Having tried both, I prefer homebridge to home assistant. Here's a guide https://github.com/oznu/docker-homebridge/wiki/Running-Homebridge-on-Firewalla-Gold
@Michael thank you, your guide is great!
Homebridge seems to be more of an interface to HomeKit than a standalone software. I do not have Apple devices so not sure it's a good fit for me.
Nicolas, you are right Homebridge is mostly about homekit. It does have some plugins for Google, zwave, and alexa.
So now that I have 1.971 I've added the new file necessary to kick start the controller after every reboot. However, and forgive me if this is a dumb question, but what does this part of the guide mean:
If you have installed unifi controller before 1.971, please change your docker-compose.yaml file accordingly and run the following commands
In what way would I need to update the compose file?
@Blake If your controller is up and running then you are good. We made a change in network section of docker-compose file. A previous configured docker container might cause conflict with the recommended settings now.
I had the earlier configuration, and am having a hard time updating it to the new instructions.
Is there some easy way to remove the entire docker configuration, without reflashing the router?
Thank you,
Chris Shaker
Try running sudo docker compose down. Then start over. If that works it’s much easier than the method I used.
docker compose down is supposed to remove the container. So running that and then starting over using this guide should work. Also, I found it easier to use Filezilla to connect to the Firewalla to create the directories and upload the yaml file since I don't really have much experience in using commands to do that. Just in case that helps anyone as inexperienced as I am accomplish this.
Thank you for the information
Has anyone tried updating their controller or updating any of the devices? I can't seem to do any firmware updates from the container.
@Blake to upgrade the controller you update the docker container. Updating devices happensmfrom the controller software.
how do you update the container? A link to instructions would suffice.
https://github.com/oznu/docker-homebridge/wiki/Running-Homebridge-on-Firewalla-Gold#updating-homebridge
Thanks @Michael. That did the trick.
You bet @Blake! Glad you are in business.
Could this method be adapted to install TP-Link's Omada Software Controller? I have a few EAP245 and this would save me having to get their hardware controller
I've got this working just fine. One question though.
While testing my Guest network I realised I was able to load Unifi and Pihole - but that network has a block on all local LAN traffic. For instance I am unable to route to a server on the LAN.
I am guessing this must be because in step 2 and 4 we're making the subnet WAN routable? How do I un-do that? I don't really understand why we're using different commands in 2 and 4 (`sudo ip route` vs. `sudo ipset create`).
Is the ip route command with table wan_routable really necessary? I only used the command with lan_routable and cannot see any problems (also I removed the two lines in the start_unifi.sh script).
What's wan_routable doing?
@Chris: Also without the wan_routable command I could connect to the unifi controller from my guest network .. so I add in the firewalla app a custom block rule for my guest network .. block ip range 172.16.1.0/24. It's working fine.
I'm trying to do this on a Firewalla Blue Plus. My controller adopted and provisioned the initialized WAP and it seems to work just fine.
When I run:
sudo ip route add 172.16.1.0/24 dev br-$(sudo docker network ls | awk '$2 == "unifi_default" {print $1}') table lan_routable sudo ip route add 172.16.1.0/24 dev br-$(sudo docker network ls | awk '$2 == "unifi_default" {print $1}') table wan_routableI get this:
My docker-compose file is identical to what is provided in the procedure above. Any advice?
Please sign in to leave a comment.