unifi-poller is a lightweight program to display data from a Unifi network. It collects stats from a controller of a Unifi network, puts them into a database and then displays time series. It’s basically a way of feeding a geeky data-hoarding habit. This is a unifi-poller step-by-step basic guide to installation.
The developer of unifi-poller, TwitchCaptain, has built it in a manner which is very flexible. So there are multiple methods of installation. The one I describe here is my favoured one – using Docker and docker-compose. (Note that I prefer a config file rather than an environment file, which is suggested in the wiki).
For the purposes of this unifi-poller step-by-step I will walk through installation on a Raspberry Pi 4. But, after the first Step, any instance of Docker should be fine.
Step 1 – Get Docker working
So to get Docker working on a Pi is pretty straightforward. First we install Raspberry Pi OS (the new name for Raspbian) then install Docker! (I’ll skip through this quite quickly, since there are a ton of detailed guides out there.)
Download the latest version of Raspbian from raspberrypi.org. (I always use the Lite version, since I never bother connecting my Pi’s to a screen or keyboard.) Use a tool like balenaEtcher to write the image you just downloaded to an SD card of your choice. Before ejecting the SD card for good make a file (even just an empty file) called
ssh on the
/boot volume (so that you can get in to the Pi using the command line after it has booted).
Put the SD card in to the Pi, apply power/network (or edit
/etc/wpa_supplicant/wpa_supplicant.conf for wifi access) and then find the Pi on your network. Log in to the Pi (use Terminal on OSX or its equivalent) using the credentials – username
raspberry. Change the password using the
So now we need to make sure the Pi is up to date:
sudo apt-get update && sudo apt-get upgrade
Agree to any updates, and wait for them to install. Then the one line command to install Docker is:
curl -sSL https://get.docker.com | sh
Now add the user
pi to the
docker group, so as to avoid permissions issues later. Use
sudo usermod -aG docker pi
Reboot the PI, by running
sudo shutdown -r now. Log back in when it comes back up.
Make sure everything is working by running
docker run hello-world. The output should contain the magic lines:
Hello from Docker! This message shows that your installation appears to be working correctly.
Now that there’s a working version of Docker on the Pi let’s install
docker-compose, which is a nice method of managing docker images, allowing for easy changes to configurations and updates. Install it by first installing some dependencies, and then installing it:
sudo apt install -y python3-pip libffi-dev sudo pip3 install docker-compose
Step 2 – Prepare your controller
Before installing poller, we need to make sure that the Unifi network controller is ready. The preferred way to do this is to create a new user on the controller with read-only access. Let’s call our new user
Log in to the controller and set up a new user –
- On a classic controller, go Settings/Admins, add a read-only user called
unifipoller, give it a complex password (let’s suppose for the purposes of this guide you choose
PollerPASSWORD) and then for each site that you want to use poller on give that user access via the “Invite existing admin” option
- On a UnifiOS controller (like a UDM), go to the
usersinterface (top right, dial-pad icon, face icon), then Add User/Add New User, name “Unifi Poller”, Role – Limited Admin, Account Type – Local Access Only, Local Username –
unifipoller, Local Password –
PollerPASSWORD, Controller Permissions/Unifi Network – Read Only. Then Add
(I you think you will later want to use graphs of DPI statistics then make sure that DPI is enabled on the controller!)
Step 3 – Set up unifi-poller and docker-compose
Since we are going to use
docker-compose to manage our Docker containers, we now need to go back to the PI to set up the infrastructure. We’re going to first set up the config file needed for Poller, then the one for docker-compose.
Log back in to the Pi, and, to keep things tidy, let’s make a working directory in our home directory. And make a sub-directory which we can use for poller, plus two others we will need later:
cd; mkdir docker cd docker mkdir unifi-poller mkdir grafana mkdir influxdb cd unifi-poller
Now we will make the configuration file for poller in this folder. Run
nano unifi-poller.conf and enter the following, amended as necessary for the two IP addresses. Delete
:8443 from the first
url line if you are using a UnifiOS device (eg UDM, UDM-Pro, UXG) for your controller. (Use control-x, y, RETURN to write the file when done):
[unifi.defaults] url = "https://THE_IP_ADDRESS_OF_YOUR_CONTROLLER:8443" user = "unifipoller" pass = "PollerPASSWORD" save_dpi = true [influxdb] url = "http://THE_IP_ADDRESS_OF_YOUR_PI:8086"
Go back up a level (to the
/home/pi/docker folder, using
cd ..) then let’s add the configuration for docker-compose by using
nano docker-compose.yaml and entering the following (with the same control-x, y, RETURN when done):
version: "3" services: influxdb: container_name: up_influxdb restart: unless-stopped image: influxdb:1.8 ports: - '8086:8086' volumes: - /home/pi/docker/influxdb:/var/lib/influxdb environment: - INFLUXDB_DB=unifi - INFLUXDB_ADMIN_USER=unifi - INFLUXDB_ADMIN_PASSWORD=unifi grafana: container_name: up_grafana image: grafana/grafana restart: unless-stopped user: 1000:1000 ports: - '3000:3000' volumes: - /home/pi/docker/grafana:/var/lib/grafana depends_on: - influxdb environment: - GF_SECURITY_ADMIN_USER=admin - GF_INSTALL_PLUGINS=grafana-clock-panel,natel-discrete-panel,grafana-piechart-panel unifi-poller: container_name: up-poller restart: unless-stopped image: golift/unifi-poller:latest depends_on: - influxdb - grafana volumes: - /home/pi/docker/unifi-poller:/config
Edit Mar 2021 – updated to specify v1.8 of Influx, as
latest now points at v2, which poller does not support
(In this file, if you are not using a Pi but your own Docker then change
/home/pi/docker to your preferred local storage in the three places it occurs. Also, you should delete or amend the
user: line in the
This defines the three containers we will be running – an influxdb to store the data, a Grafana to extract from the data and display it, and a unifi-poller to get the data from the controller and write it to the database.
Step 4 – Get it all to work
Download and start the containers by running
This first time it will take a little while to get everything down and installed, so be patient. If all is good you will start seeing lines looking like this every 30 secs (as well as other messages):
unifi-poller | 2020/06/18 12:08:50 [INFO] UniFi Metrics Recorded. Sites: 1, Clients: 67, UAP: 6, USG/UDM: 1, USW: 5, IDS Events: 0, Points: 1837, Fields: 11307, Errs: 0, Elapsed: 599ms
This means the data is being retrieved from the controller and written to the database. If you don’t see this kind of message then go back and re-trace your steps. If poller is not running properly then nothing else will work.
If all is well, you can use your favourite web browser to go to
http://THE_IP_ADDRESS_OF_YOUR_PI:3000. Log in to Grafana with the credentials
admin and choose a password.
Now we need to set up the link between Grafana and influx, where the data is being written to. Choose Configuration on the left hand side, then “Data Sources”. “Add data source”, choose InfluxDB then fill in the details of the URL (http://THE_IP_ADDRESS_OF_YOUR_PI:8086), and the InfluxDB Details (database – unifi, User – unifi, Password – unifi), then Save & Test.
Finally, you need to import the default dashboards that use the poller data. Go to the + sign and choose Import. The id’s to use are the following: 10414, 10415, 10416, 10417, 10418 and 10419. Do each in turn by clicking Load, then the number, then at the bottom choose the InfluxDB source (which we just created) under Unifi Poller, then Import.
You should now be able to see some data!
The final step is to get the docker containers to start automatically, Go back to the Pi command line and control-c the docker-compose we started earlier. Make it start automatically by running:
docker-compose up -d
Step 5 – Enjoy!
Now that it is all up and running you can customise the dashboards as you like. And play with the configuration and generally have fun. That’s all there is to this basic unifi-poller step-by-step.
I’d suggest that if you are going to leave this on a Pi then you look to investigate retention periods on the influx database – things will start to slow down and maybe even break when the databases get too big.
To clean up if you don’t want this any more just stop docker-compose by
docker-compose down, and deleting all the data files you have collected by
rm -r /home/pi/docker/*
And do let me know what you think of this unifi-poller step-by-step!