Unifi-poller step-by-step – a basic guide
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 pi
, password raspberry
. Change the password using the passwd
command.
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 unifipoller
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 choosePollerPASSWORD
) 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
users
interface (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:latest
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
(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 grafana:
section.)
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
docker-compose up
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
/ 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!
This is an excellent piece of work. Thank you so much. I have been looking for a solution to getting the stats for so long and am excited top now have it.
Glad to hear it was useful. Enjoy the stats!
Thank you for putting this guide together. It has saved me hours of headache trying to work it out for myself and I do appreciate the effort that you have put into it. I also want to say that I do enjoy the articles you put together.
Glad to hear that you found it helpful. Really appreciate the feedback, thanks.
I have been running this for a couple of weeks and it is excellent so thank you for the guide. Does anyone have a link to a page where I can learn more about how to adjust the retention? It does bog down the PI after two weeks or so. I cloned the SDCard so I can just flash it again to get things running again, but if the database did a cleanup maybe I wouldn’t need to do that. My Google search for an answer doesn’t seem to work with a Docker version. EVen if I knew how to create the database all over again with a 2 week retention while setting this up that would be fine.
Retention policies are on my to-do kist. I’ll let you know …
Hi Mark – here’s the page – https://docs.influxdata.com/influxdb/v1.8/query_language/manage-database/#create-retention-policies-with-create-retention-policy
So basically, access influx with the command
influx
, delete and recreate the dbase, then enterCREATE RETENTION POLICY retention_policy ON unifi DURATION 32d REPLICATION 1
(or however many days you can cope with) and then you’re donePingback: Unifi-poller Setup and Configuration - JohnMinadeo.com