Preface
- This is a technical doc for advanced users. 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 in Router Mode only.
- Installing Unifi Controller on Firewalla Purple series and Firewalla Orange boxes is not recommended due to memory limitations. You can use Unifi switches and APs with Purple series and Orange boxes. If you have a Firewalla Purple or Orange 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/unifiNote 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'
environment:
JVM_MAX_HEAP_SIZE: '512M'
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 5003This 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
cd /home/pi/.firewalla/run/docker/unifi/
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 run the script:
/home/pi/.firewalla/config/post_main.d/start_unifi.shWhich will restart docker 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 pruneImportant 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
145 comments
Hi Jen I’m not sure I understand the issue can you describe in more detail?
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".
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.
@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.
@Blake to upgrade the controller you update the docker container. Updating devices happensmfrom the controller software.
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
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?
@Chris, I am not sure how you have configured your guest network. If it is a different VLAN then you can make a rule on Firewalla preventing the guest VLAN from reaching the LAN.
Ran into an issue that I think is related to the controller setup and the googles has let me down.
I created a separate network from my LAN for my WFH computers. When I try to assign the “Work” port profile to the switch uplink in my office the switch disconnects from the controller. I suspect that the controller can’t reach it on that network? Any ideas?
Thanks for asking this @Blake. I was thinking about moving the management to another vlan but hadn’t taken the time to sort out the steps involved.
So here is what I was thinking (and apparently this isn't an easy thing to do based on my research). I want to create a separate network for my Unifi network equipment. This involves 2 switchs, the controller and the APs when I get them. Currently my controller is in docker and it has an IP of 172.16.1.2. I can also access it from 192.168.30.1, but I'm not sure why. I've created a MGMT VLAN in the FWG (192.168.20.1/24). I also made this a corporate network in the controller.
I first set the Management Network on the Flex Mini switch to MGMT VLAN and it disconnected from the controller. After fiddling a bit I discovered and checked the box in the controller settings for "make controller discoverable on L2 network" and after a few minutes the switch changed from Disconnected to Adding. It was stuck in Adding for a while and then surprisingly it finished provisioning and showed as connected in the controller. It has an IP address in my MGMT VLAN, and the connected devices still have IPs in their correct subnets. Sometime this weekend I'm going to attempt to move my main switch over as well. But I still don't know how to move my controller to that network yet. I also would love to know why I can access my controller from both the 172 and the 192 networks.
If anyone is interested, I wrote a script that I run on my firewalla (via cron) to turn on/off the LEDs of my Unifi APs every day. (One of the APs is in a bedroom.)
During step 1, when I try
I get the following error:
Error response from daemon: No such container: docker-compose@unifi
Error: failed to start containers: docker-compose@unifi
I have the file created, but it almost seems like Docker is not installed. Is it not installed on the Gold out of the box? I created the directories and saved the .yaml file, but I am wondering if I needed to install docker before starting this. Any help is appreciated, I'm pretty new to this.
To see if Docker is installed , you can check
or see what containers are running!
You could also have a look at https://github.com/oznu/docker-homebridge/wiki/Running-Homebridge-on-Firewalla-Gold although it is for a different Docker container.
Thank you for your help on this, I got through step 3 and everything appears to be working correctly, but when I try to access the controller through a browser I can't reach anything. So, a couple of questions here:
Step 2 says to Create the following file
/home/pi/.firewalla/run/docker/unifi/docker-compose.yaml
If I try to type "nano /home/pi/.firewalla/run/docker/unifi/docker-compose.yaml" and then pste the contents in it, then when I try to save, it says the file doesnt exists.
If I manually mkdir the unif folder in /home/pi/.firewalla/run/docker/ and then try to "nano docker-compose.yaml" , I get a permissions dnied error
@Abbas, if you are using nano you have to use the, “write out” command before exiting.
The controller runs fine but I see my devices as disconnected, do you have to set the controller ip under Settings > Controller > Controller Settings or leave it blank? and tick the "Override inform host with controller hostname/IP" box?
@StackIOI do not tick the, "Override inform host"
The IP for Controller Hostname/IP will be the Firewalla.
If you have never adopted the devices before you may need to the device where the controller is.
https://community.ui.com/questions/What-is-correct-command-to-set-inform-url-and-also-to-factory-reset-via-SSH/9d219587-76d5-4c8e-bc81-63a70a8bb212
Thanks @Michael Bierman, for some reason it seems that the devices are not finding the controller... I double checked my UniFi dnsmasq_local entry and is correct, also reconfigured the controller from scratch, as the previous time I restored the configuration from a backup of the working controller (running in my computer) into this new one... Which is why I saw the devices as disconnected... now, with the new controller running (the one in my computer is off) I can't see any of the devices, so obviously, I can't adopt them into this new controller.
Did reboot them manually hoping for a refresh, but still can't reach them. Any suggestions? I can reach them from the FWG, I can ping them just fine.
Please sign in to leave a comment.