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
I've tried the how-to, and I've run the script. Neither seems to be working for me.
When running the how-to, I can never navigate to the host at 172.16.1.2. I can see the container running but still can't navigate to it via another host on the network.
I reset the FWG to factory settings and tried running the script. It launches the host but repeatedly writes "RTNETLINK answers: File exists" on my screen when trying to configure networks.
Given the deprecation of the Unifi-Controller, I have compiled a comprehensive guide outlining the installation process of the Unified Network Application (UNA) on the Firewalla Gold firewall. Although I do not possess a Purple firewall, I have identified the new database requirements and believe that the Purple firewall does not support UNA.
https://github.com/TheeNawMan/firewalla-docker-scripts/tree/main/unifi-network-application
I'm a noob. What changed today in this doc from previous versions? Is the doc saying that I can run the unfi controller right on my firewalla gold?
For those new, with [ existing / old Unifi AP ]
Best combo currently, i can recommend to ANY layman starting or moving to firewalla
1) Get Gold SE
2) get any u6 or even. better u7p
3) Setup the Gold SE,
4) Use Michael Bierman's AMAZING script, it LITERALLY cuts down the time by 3/4 of this thread.
5) Give it 10mins [ warn your family , 20mins tops ]
6) configure the. controller
7) use https://www.anythingyouwant.com
reboot, and run your ssh optimization tcp connection, and you're literally, pun intended [ Gold ]
Docker + Unifi controller + all the brillant folks
And p.s skip the purple for controller, the ram will die first before anything else......
@Michael Bierman thanks alot for that script./... !
as of 8jan2025 SG
Jus to add on,
anyone who are troubleshooting, do remember to remove the unifi ap from the controller first, followed by the Access Point within Firewalla [ if you have it grouped ]
My Mistake : couldnt see the u7pro even after removing from the controller or resetting the AP to factory default
or even using the uninstaller from Michael Bierman.
The correction : needs to include the removal of grouping and device/ IP address from the Firewalla Gold SE/ and above spec.
Hi Jen I’m not sure I understand the issue can you describe in more detail?
@Michael Bierman,
nothing of your fault, its on me.
Your great Github works for both uninstall and install.
The problem [ me ] ,was that :
- ive unplugged the power from FW gold SE. [ so my ISP dhcp changed IP]
- after 10mins, wifi still works, but [ Unifi Controller ] couldnt directly manage it , basically theres 2 entries with the old u7pro AP " not found "
- tried, uninstallation , reinstallation of the [ Unifi Docker Controller] , resetting of the u7 pro AP, nothing worked.
Until ive gotten into the FW app, delete the [ u7pro ] device as i grouped it under me
Seems either its a bug or something else, but just putting it out should someone with similar setup to mine, just to run through the checklist :
If DHCP from ISP changed
or
power down / interrupted.
Make sure to just do a clean :
- AP physical Hard reset
- Deletion of AP from Unifi controller [ if its seen ]
- Removal of AP [ the ip address from grouping if any ]
- Re-adding back the same way.
And for extra ease of mind , redid the Docker using your curl scripts .
20mins, at most, which is a fairly a huge down time for my family
Works great, but I have to run this command after every restart of the Gold SE to bring back access to the Unifi App. Is there any way to automate this once the docker has self-launched?
Shaun Sommer Parker Yes, you can use a script I wrote that will take care of this github.com/mbierman/unifi-installer-for-Firewalla
This is also described help.firewalla.com/hc/en-us/articles/360054056754-Customized-Scripting
Michael Bierman I started with the help article instructions before finding this script. Thanks for that. Will is safely overwrite the instructions in the script? Specifically, the IP routes and firewall rules? I don't want to over expose myself.
Also, any chance of adding a monthly cron job to update the controller? Do you have any tips on connecting to the Controller remotely via a Site-to-Site VPN over a 2nd Firewalla?
Jen Fox what do you mean:
>reboot, and run your ssh optimization tcp connection, and you're literally, pun intended [ Gold ]
What optimizations are needed and why? Reboot to test to ensure it comes back after power failure? Thanks
gregory my script pretty much follows what's here so you don't have to do it manually. Should be no conflicts. Not sure about what you mean—these are internal IPs and you don't have anything to worry about.
I have an update script but I don't run it via cron. You could, but they only come out like every 3-4 months so I'd rather be cautious and do it myself.
Ok so I'm not running unifi but I am running an nginx container on port 8080. When I add the ip commands, I am able to access the webserver from the internet which isn't something I want, I want my docker network to only be internally accessible.
ip commands:
sudo ip route add 172.17.0.0/16 dev br-685f37528676 table lan_routable
sudo ip route add 172.17.0.0/16 dev br-685f37528676 table wan_routable
sudo ip -4 rule add from all iif br-685f37528676 lookup lan_routable priority 5003
The problem I have is after adding the lan_routable and priority, my container can no longer access the internet. I am able to access it on the internal network which is great. I just don't want the risk of internet traffic being able to get to anything on my docker network.
Any ideas of what ip commands I should run to allow the container access to the internet?
Hi Jeff Whiting,
Here’s a summary of the steps to troubleshoot your container connectivity issue:
Remove the
ipcommandsIf you added any
iprules, please remove them. The easiest way is to reboot the Firewalla if the commands weren’t made persistent.Test internet accessibility
After rebooting, check if the container is accessible from the internet. Make sure to test from outside your network (for example, using your phone’s cellular data). Testing from inside your network, even with your WAN IP, can give a false positive due to “hairpin NAT,” where your router loops the traffic back internally.
Impact of the
ip ruleyou addedThe command you used:
unintentionally blocked all outbound traffic from the container. It forced container traffic to use the
lan_routabletable, which doesn’t have routes to the internet. While this blocked outbound traffic, it did not solve the original inbound access issue.Here’s why this differed from the Firewalla guide:
Interface selection: The guide dynamically detects the correct Docker bridge interface, while your command used a hardcoded interface. If the interface changes, the rule can misroute traffic. Even if that wasn't the problem for now, it isn't a good practice.
Traffic affected: The guide affects only the UniFi container traffic; your version affected all traffic from the interface, which blocked internet access.
Routing table: In the guide,
lan_routableis properly configured to allow both LAN and internet access. In your case, the table likely lacked the proper routes.Bottom line: The Firewalla method works because it targets the correct interface and has the right table configuration. The rule you applied accidentally blocked outbound traffic.
Check for existing rules allowing traffic
If your container is still accessible from the internet after reboot, it’s likely due to a pre-existing Firewalla rule, such as a port forwarding or “Allow” rule.
Michael thanks for the response. The commands I posted were the same ones from the guide, I just resolved the dynamic part `$(sudo docker network ls | awk '$2 == "unifi_default" {print $1}')` before posting. The problem I was trying to fix was not allowing access to the app from my public ip address.
Ok I think I figured out what I was doing differently than the guide. My problem was that I used port mappings in my docker compose file.
what this did was open up port 80 on my firewalla that was accessible from my public ip address. So I was trying to figure out what ip rules I should use to prevent that. However the correct answer is to not use port mappings / bindings in docker. I'm now realizing the guide was having me use the internal docker ip address of the app (172.16.1.2) and the ip routing tables above made it so it knew how to route to this internal docker network.
Christopher Anderson I was also having the same issue of not having remote management capabilities despite it being enabled. Today I realized that when I disabled DoH services filtering (in Family Protect) it started to work again.
I am having an issue with Cameras, etc not showing for adoption. I think it’s a NAT or VLAN issue. Has anyone seen this? I have the Firewalla -> UI USW Pro Max Switch -> UI cameras but the controller doesn’t see the cameras to adopt them.
gregory
not sure if its worth a shot.
My previous problems, when adopting the u7pro , after re-setting up the controller, can still be used but i cant actually administer it.
aka , its plugged in, its usable , but cant change any of the settings.
Solution : factory reset the u7pro, and re-adopt it.
might wana try that ?
@jen thanks but I’m not sure that’s the issue. I think the controller is on a different subnet (172.x) while the cameras are on 192.168.x and I’m not exactly sure how to resolve it as the 172. Subnet doesn’t seem like it can be bridged to the cameras? Unless I’m missing something else. Thanks
First off, love the Firewalla and big thank you to this group Mickael Bierman and Ethernet Blueprint! I have a FW Gold running on the current box version 1.981 and app version 1.66(103) for iOS.
I ran Michael Bierman script to install the docker and unifi controller on the box.
This all seemed to go fine and the docker says its running and "healthy" when I check is with 'sudo docker ps'
I also set the custom DNS rule in the app to
Domain = unifi IP Address = 172.16.1.2
and
created VLAN network "Docker" with ID 111 and IP Address 172.16.1.1
I cannot get the controller interface to load. Tried multiple browsers and they say the page took too long to respond. I don't know what I'm doing wrong or what could be wrong. Any help is appreciated.
Hi Justin Dewey,
You shouldn't have to create. VLAN. The script does everything you need.
If you do
on the same machine (or the equivalent command) does it resolve?
If you did anything not listed in the steps above (or in the script instructions) then I'd try to either check through each step and see if the instructions were followed and undo any extra steps or uninstall everything and try again.
Hello, Noob here.. sorry... if my current LAN is 10.0.0.0/24 network. do i need to move it to the 172. network or can i just change 172.16.1.0 /24 to 10.0.0.1/24?
thanks,
James
James Bishop This guide does not assume you are using 172.16.x.x (in fact it probably assumes you are. not) My advice is to keep to the guide here exactly unless you know a lot about setting this up.
if it is of any interest, I created an installation script to make this easier based on this guide. github.com/mbierman/unifi-installer-for-Firewalla
Justin Dewey gregory, sorry I didn't see your posts. Did you get things resolved?
Michael Bierman all good, thanks!
Please sign in to leave a comment.