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
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.shAnd 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
144 comments
Lammiwinks, tha ks for the response. Two part answer, yes I did. Second part, before I added this though, it would show up in the console and let me adopt it. The problem is the adopting never succeeded. It would start and then eventually the device would go offline in the console and never come back. Every time that happens, I forget the device and I have to wait hours for the device to show back up. The I try to adopt again and it fails... I really am baffled.
Interesting! One of the problems I found running Unifi in docker on the Firewalla itself was the lack of visibility of the "flows" and ports. I also found that it opened ports on the Firewalla outside so I since moved it onto my Raspberry Pi (and just let my Firewalla be a Firewalla).
Since doing this I've been able to follow Unifi's guide for needed ports / mixed with flows I've seen the devices make: https://help.ui.com/hc/en-us/articles/218506997-UniFi-Network-Required-Ports-Reference - I wonder if there's a restriction here you don't have visibility of. To be more specific I've allowed the following ports inbound to my RPI running Unifi on Docker from the network my unifi devices live on: 3478, 5514, 6789, 8080, 8443, 8843, 8880,1000. You should enable these in the docker compose file. On that note it's worth restarting the container also while you're there (sudo docker-compose down && docker-compose up -d)
The other thing I'd try doing is Rebooting the Firewalla. This should re-apply the route tables you "persist" in the instructions above as the devices typically need internet connectivity to adopt and perhaps your docker container isn't "wan" routable.
Try factory resetting the switch. I’ve had to do that before when the adoption failed.
Great suggestions guys! Unfortunately, still no luck. I may contact ubiquiti support and see if they can help. I may just also bite the bullet and buy a cloud key. That is assuming it fixes my issues.
Don't assume cloud key is the solution. I recently had a UNVR which I couldn't register with Unifi Cloud although pretty much everything else worked. I reset it and tried multiple things but nothing helped. I assumed it had something to do with not having a proper hosted Unifi OS (but rather installed in a container on Firewalla). However I contacted support and they RMA'd the unit saying something was wrong with it. I was doubtful but the replacement arrived and worked without a hitch. I think they must use some type of cryptographic chip to prevent emulating their hardware and that chip fails sometimes.
Ephraim, thanks for that tip! I started a support ticket with them and we will see what comes of it.
I don't want to move to a cloud key, just an extra cost for little benefit (to me).
@josiah,
A cloudkey won't solve anything. If I understand the issue it is probably a common one. https://lazyadmin.nl/home-network/unifi-adoption-failed/
Looks like jacobalberty hasn't posted some recent Unifi updates, including their new V8 version, has anyone either in the Firewalla team or users looked into using a different docker source?
I tried and got all of the UI working, here is my docker-compose.yaml file. Followed all of the steps above but also created another folder in /data called mongo for the separate DB that V8 Unifi seems to require now
I trust the jacobalberty distro. Yes, there is a little lag between when unifi releases something and when it gets into this docker image. But at the same time, it has been very stable. I think they are careful about pushing out the distro Personally I value stability more than living on the edge in this case.
Normally I'd agree but so far jacobalberty docker instances are behind by 2 versions. In any case all working for me on v8.0.24 😁
I was just looking at the image and thinking about changing to a different one. Is the jacobalberty distro still active?
Has anyone had success with enabling remote access on the unifi controller? I keep getting this error:
"There was an error enabling Remote Access. UniFi's remote access service cannot be reached. Please check your network connection and try again."
Wondering if anyone has updated the Unifi OS that sits on the docker from 7.5.16 to 8.0.24 or even something not as new? I saw that there was someone that did, but can't seem to figure out how to upgrade the OS.
@Pat, You should update the container as a whole. People who build the dockers do a lot testing about the configuration and generally, should be trusted. To update the container, Fiewalla has included instructions.
https://help.firewalla.com/hc/en-us/articles/360053441074-Guide-How-to-run-UniFi-Controller-on-the-Firewalla-Gold-Series-Boxes#h_01HN3THHC2XV0EZWHQZYHH66QD
Thank you @Michael for the link. Will definitely look into that today.
https://github.com/mbierman/unifi-installer-for-Firewalla
This worked for me nicely. I am not responsible for anything by offering this information.
+1 https://github.com/mbierman/unifi-installer-for-Firewalla this has consolidated all the required steps including docker prune as well at the end. mine is 8.1.113 now. Additionally I've created a unifi account and added the firewalla hosted unifi controller to the site manager. with that I could manage the configurations at https://unifi.ui.com/ instead of https://172.16.1.2:8443, I could manage most of the configurations via the iOS App Unifi.
I've automated the updates via a new cron (monthly). I've commented the user input to continue in the updatedocker.sh.
Looks like jacobalberty repo has gone stale again :(
Hi Lewis what do you mean?
No further updates for 2-3months, someone has already forked the repo and pushing out fresh Unifi updates
I've re-done everything after reset on the gold-pro... revised the IP/Subnet and appear to have things working...
I am getting started with Unifi Controller on my Gold Plus. I followed these instructions and am able to install the controller successfully. However, I cannot access the controller remotely from https://unifi.ui.com/. I have 'Remote Management' enabled in the controller.
In the Unifi server logs on the Firewalla, I see entries such as `[2024-09-10T15:18:44,226Z] <check-iot-certificate> WARN sdn - failed to get connectivity details: config.ubnt.com: Temporary failure in name resolution` almost as if the Docker container can't access DNS properly.
Anyone else see this issue? Is there a way to open a shell within the Docker container and validate it can correctly communicate outside to the external internet?
Thank you.
How do I get the inform URL of 8080 to work even off-site? As the gateway itself is the host I'm not sure how to configure the port forwarding for this. And if I manually change the information URL to this I would like to make sure it doesn't interfere with also adopting devices locally.
@Ephrayim,
What do you mean offsite? Are you using a cloud hosted controller?
set-inform http://cloud.example.com:8080/inform
Should work. Is that what you are asking?
@Michael Bierman I mean using the Unifi controller hosted on the Firewalla for the management of APs that are not on the local network sometimes as part of a different site and sometimes as part of the same site as the the APs on the local network. You can call this a cloud controller but I am trying to use controller I have installed on Firewalla in this capacity and I would like to know how to properly open up and redirect the remote ports to the Unifi controller.
@Ephrayim,
If you are are using the instructions here, I think the command would be:
or you should be able to use:
as well. I believe that this is the unifi default so you might not need to change anything if you have followed this guide.
I didn't quite follow the other part of what you said. You are trying to use this for unifi devices at another location, I haven't done that, but I think you would need to:
Yes you have the right format for the inform URL. The problem is that port 8080 is closed and I am running the Unifi controller on the firewalls itself. Are you suggesting that I need to port forward to the internal IP address of 172.16.1.2?
Yes, that should work.
You may want to restrict access to port 8080 so that it is only accessible from the IPs (or a region) where the other unifi devices are.
@Michael Bierman Doesn't work. When I try to setup port forwarding on Firewalla to a specific IP it gives me an error that the IP address must be within the DHCP range of the local network. So, to repeat the question how do I get the Unifi controller to work with managing access points outside of the local network? Maybe someone from @Firewalla can chime in.
Please sign in to leave a comment.