Preface
- This is a technical doc for Pros. 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
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
Run the following commands to map Gold's IP to Unifi controller in dnsmasq.
echo address=/unifi/172.16.1.2 > ~/.firewalla/config/dnsmasq_local/unifi # Restart DNS Service sudo systemctl restart firerouter_dns
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 dnsmasq config to the right domain.
Step 4: Access Unifi Controller from Gold managed network
Access the following URL and login to check for Devices in your network. If you have any trouble reaching the device try these links to access your Unifi Controller.
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.
Known Issue
On ubuntu 22.04 and later, when docker starts up, it may load a kernel module br_netfilter which conflicts with ubuntu 22.04 if you are using Smart Queue. Dockers managed by Firewalla will automatically handle this, but if you create docker instance, you may need to run:
sudo rmmod br_netfilter
after starting docker service or the firewalla routing function may break.
This is due to a Linux Kernel bug which we plan to fix in our 1.976 release.
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
97 comments
Neither of those are options unfortunately, seems to be running fine currently. I'll keep an eye on it.
I can confirm Mariusz' experience. I had the UniFi controller running on my Purple for a little over a month. The first week went okay, but as I moved additional devices to my UniFi setup, the Purple froze more and more often. At the end I had to restart once a day. Since I moved the controller to a Cloud Key a week ago, the Purple has been stable again.
So while it is possible to run the UniFi controller on the Purple, I would not recommend it.
I was able to get this running just fine (with the caveat that it seems to only listen to http://www.unifi:8080 and not http://unifi:8080/.) The github page for jacobalberty/unifi recommends running it in user mode by setting the docker run flag
--usertounifi.This is my first time going anywhere near Docker. How do we do that in Firewalla? Or does Firewalla already handle this for us by default?Trying to remove as many devices as I can and finally got around to moving the UniFi controller on my FWG.
I have set up and moved all my UniFi devices and its all working great. But at step 5, I get an error. It can't create that file.
~/.firewalla/config/post_main.d/start_unifi.sh" E212: Can't open file for writing
Try creating the file using a text editor on your computer, and then dropping it into that folder using an FTP client. I found that method much easier since I don't really know linux well at all.
A youtube tutorial of this would be super helpful
@Abbass did you create the directory first?
@Stephen I don’t have a video, but I created a script that does pretty much everything for you. /github.com/mbierman/unifi-installer-for-Firewalla
@michael, that made it way too easy. Thank you
@Michael Bierman - I did but that didn't help. I've just left that last bit hoping I never have to restart my FWG. And if I do, then I'll manually start the UniFi controller. Not related but I've been eyeing the new Eero POE points. Who knows- I might replace my UniFi devices with that.
@abbas, there is an uninstall script too. No reason not to run it properly.
honestly, Unifi is so much better than eero, I don’t know why someone would switch in that direction.
I am not able to access the Unifi GUI in a browser, and pings from my computer time out. I can ping 172.16.1.2 from my Firewalla with no issues and I've added the routing rules as prescribed.
I also tried uninstalling and reinstalling using your script and everything comes up just as before, but still no access to the Unifi controller from the network.
My main network is 192.168.1.0/24 .... Should I use that as the docker's network instead of the one used in this tutorial?
Any help is appreciated
@Aaron,
Try ssh to firewalla and then run this:
that will tell you if unifi is really running. If it is, try
You need to specify the port. You will probably see a message about it not being secure and you have to accept that.
If you haven't put any rules in place, this should work.
Did you specify the port like this: https://172.16.1.2:8443/
@Blake yes, I entered the IP and port exactly like that. I also tried http://172.16.1.2:8080/ and https://unifi:8443/ and http://unifi:8080. No hosts on my network are able to ping anything on Docker's 172.16.1.0/24 subnet. Only the FWG can reach it.
I was able to use the Unifi controller when deployed to a portainer instance running on another server in the network. In that use case, the web app is accessed through Portainer's IP and :8443.
Does this suggest something wrong with my application of the "ip route" command after the docker has been launched?
@aaron did you modify the yaml file at all or use it asis?
@michael I copy/pasted your yaml as well as trying the uninstall/install scripts when it didn’t work the first time. In any case, ‘sudo docker ps’ shows unifi running with the correct IP.
Just in case I had a rule in place preventing access, I ungrouped the PC im using to configure this, enabled emergency access in it, and am connected to the management vlan.
Still unable to access it unfortunately. I’m currently running the controller from my portainer server but would definitely prefer to use the FWG for this if I can figure it out
Yeah, this is currently broken. The iptables set explicitly drop traffic from the docker network (it looks like).
@Granme,
I just installed unifi on my purple from scratch (github.com/mbierman/unifi-installer-for-Firewalla) and it seems fine. What issues are you seeing ?
@Aaron,
I updated the script to try to make it more robust. It does take a few minutes to get started... I updated the script to try to do more checking on each step. Did you try using my script to step through each step manually and see each step is working ?
@Michael, thanks for replying, I was able to figure it out (in part due to the info provided here), to enable the default docker bridge:
@Graeme, curious. Why did you change the IP range?
Ignore me, I wasn't actually trying to install the UniFi stuff, I was using this implementation as a guide to get the default docker bridge network routing correctly.
With the new Firewalla Gold FW (1.975) and App (1.52) releases, setting the DNS for `unifi` can be done via Custom DNS Entry Rules. You might have to confirm you want a DNS entry w/o a domain, but besides that, it's straightforward with the UI. The workaround via the shell isn't necessary any more.
@Firewalla: Maybe you would want to update this guide for Step 3 accordingly?
Good point, Johann. From a scripting perspective I think I'll leave it as is because it makes installation seamless. But you are right people could accomplish that step through the UI now.
I have this installed on a FWG. Recently I added a Unifi UNVR to run Protect and I am having trouble configuring it for remote access. By default it uses the controller's local IP. I set it to static and configured it for Google and Cloudflare DNS but it is still not working. I think it has something to do with remote access to the Docker hosted controller. I need to setup Unifi Cloud access to the controller which requires:
How do I setup the port forwarding to the Unifi controller hosted in Docker?
Update:
I added the port forwarding to the Docker yaml file. Do I still need to configure port forwarding on the Firewalla side? Firewalla is the gateway so I would think that no further port forwarding is necessary.
Personally, I would just access over VPN. I wouldn't feel comfortable allowing external access myself.
Michael, different strokes for different folks. My concern for proactive monitoring of my home is more important to me than the possibility that someone might try to hack into my network or cameras. I'm more concerned for the safety of my family and physical property than someone trying to take advantage of me through hacking my network. Limiting access to the local network would mean that 1, I wouldn't get push notifications from Unifi Protect 2. I'm unlikely to view the cameras proactively if I need to turn on the VPN tunnel to do it.
Is anybody here able to manage their Unifi OS through unifi.ui.com? I can only see my network on the legacy site network.unifi.ui.com.
Came here for the same question as you Ephrayim. No I can't access it through unifi.ui.com however the IoS app works fine.
You would need to add firewall rules to "forward the ports" to the docker network which of course doesn't appear in the Firewalla gui so these will need to be done via CLI - which I don't know how to do ;).
As mentioned however this is opening up direct ports to the internet so you'd want to limit it to the one internal IP (and then you'd need to map the ports in the docker compose file also). The main question is how much do you trust the unifi software to be directly exposed to the internet?
The other option is you can install the iPad app on a Mac ;)
This has been running great for me for many months. Just purchased a USW Lite POE 8 Port switch and it will not adopt. For the status I continue to get server reject and then unable to resolve. Any insight? I have updated firmware on switch and controller.
Hey Josiah - quick one - have you added the DNS rule for "unifi"? Wondering if the switch can't find the "host".
Sounds like an issue with the device finding the controller.
Note: You can now do this directly in DNS Service > Custom DNS rules - create a rule to resolve 'unifi' to your docker containers IP.
Please sign in to leave a comment.