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 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 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: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 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!