unifi-poller(1) -- Utility to poll UniFi Controller Metrics and store them in InfluxDB === SYNOPSIS --- `unifi-poller -c /etc/unifi-poller.conf` This daemon polls a UniFi controller at a short interval and stores the collected measurements in an Influx Database. The measurements and metrics collected belong to every available site, device and client found on the controller. Including UniFi Security Gateways, Access Points, Switches and possibly more. Dashboards for Grafana are available. Find them at [Grafana.com](https://grafana.com/dashboards?search=unifi-poller). DESCRIPTION --- UniFi Poller is a small Golang application that runs on Windows, macOS, Linux or Docker. It polls a UniFi controller every 30 seconds for measurements and stores the data in an Influx database. See the example configuration file for more examples and default configurations. * See the example configuration file for more examples and default configurations. OPTIONS --- `unifi-poller [-c ] [-j ] [-h] [-v]` -c, --config Provide a configuration file (instead of the default). -v, --version Display version and exit. -j, --dumpjson This is a debug option; use this when you are missing data in your graphs, and/or you want to inspect the raw data coming from the controller. The filter accepts three options: devices, clients, other. This will print a lot of information. Recommend piping it into a file and/or into jq for better visualization. This requires a valid config file that contains working authentication details for a UniFi Controller. This only dumps data for sites listed in the config file. The application exits after printing the JSON payload; it does not daemonize or report to InfluxDB with this option. The `other` option is special. This allows you request any api path. It must be enclosed in quotes with the word other. Example: unifi-poller -j "other /stat/admins" -h, --help Display usage and exit. CONFIGURATION --- * Config File Default Location: * Linux: `/etc/unifi-poller/up.conf` * macOS: `/usr/local/etc/unifi-poller/up.conf` * Windows: `C:\ProgramData\unifi-poller\up.conf` * Config File Default Format: `TOML` * Possible formats: `XML`, `JSON`, `TOML`, `YAML` The config file can be written in four different syntax formats. The application decides which one to use based on the file's name. If it contains `.xml` it will be parsed as XML. The same goes for `.json` and `.yaml`. If the filename contains none of these strings, then it is parsed as the default format, TOML. This option is provided so the application can be easily adapted to any environment. `Config File Parameters` sites default: ["all"] This list of strings should represent the names of sites on the UniFi controller that will be polled for data. Pass `all` in the list to poll all sites. On startup, the application prints out all site names found in the controller; they're cryptic, but they have the human-name next to them. The cryptic names go into the config file `sites` list. The controller's first site is not cryptic and is named `default`. interval default: 30s How often to poll the controller for updated client and device data. The UniFi Controller only updates traffic stats about every 30 seconds. debug default: false This turns on time stamps and line numbers in logs, outputs a few extra lines of information while processing. quiet default: false Setting this to true will turn off per-device and per-interval logs. Only errors will be logged. Using this with debug=true adds line numbers to any error logs. mode default: "influx" * Value: influx This default mode runs this application as a daemon. It will poll the controller at the configured interval. Providing an invalid value will run in this default mode. * Value: influxlambda - (the only other available option right now) Setting this value will invoke a run-once mode where the application immediately polls the controller and reports the metrics to InfluxDB. Then it exits. This mode is useful in an AWS Lambda or a crontab where the execution timings are controlled. This mode may also be adapted to run in other collector scripts and apps like telegraf or diamond. This mode can also be combined with a "test database" in InfluxDB to give yourself a "test config file" you may run ad-hoc to test changes. max_errors default: 0 If you restart the UniFI controller, the poller will lose access until it is restarted. Specifying a number greater than -1 for max_errors will cause the poller to exit when it reaches the error count specified. This problematic condition can be triggered by InfluxDB having issues too. Generally only 1 error per interval is created, but if more than one backend is having issues > 1 error could be generated per interval. Once the poller exits, it is expected that something will restart it automatically so it gets back in line; something is usually systemd, docker or launchd. The default setting of 0 will cause an exit after just 1 error. Recommended values are 0-5. influx_url default: http://127.0.0.1:8086 This is the URL where the Influx web server is available. influx_user default: unifi Username used to authenticate with InfluxDB. influx_pass default: unifi Password used to authenticate with InfluxDB. influx_db default: unifi Custom database created in InfluxDB to use with this application. On first setup, log into InfluxDB and create access: $ influx -host localhost -port 8086 CREATE DATABASE unifi CREATE USER unifi WITH PASSWORD 'unifi' WITH ALL PRIVILEGES GRANT ALL ON unifi TO unifi unifi_url default: https://127.0.0.1:8443 This is the URL where the UniFi Controller is available. unifi_user default: influxdb Username used to authenticate with UniFi controller. This should be a special service account created on the control with read-only access. unifi_user no default ENV: UNIFI_PASSWORD Password used to authenticate with UniFi controller. This can also be set in an environment variable instead of a configuration file. collect_ids default: false Setting this parameter to true will enable collection of Intrusion Detection System data. IDS and IPS are the same data set. This is off by default because most controllers do not have this enabled. It also creates a lot of new metrics from controllers with a lot of IDS entries. reauthenticate default: false Setting this parameter to true will make UniFi Poller send a new login request on every interval. This generates a new cookie. Some controller or reverse proxy configurations require this. Do not enable it unless your configuration causes the poller to be logged out after some time. verify_ssl default: false If your UniFi controller has a valid SSL certificate, you can enable this option to validate it. Otherwise, any SSL certificate is valid. GO DURATION --- This application uses the Go Time Durations for a polling interval. The format is an integer followed by a time unit. You may append multiple time units to add them together. A few valid time units are: ms (millisecond) s (second) m (minute) Example Use: `35s`, `1m`, `1m30s` AUTHOR --- * Garrett Bjerkhoel (original code) ~ 2016 * David Newhall II (rewritten) ~ 4/20/2018 * David Newhall II (still going) ~ 6/7/2019 LOCATION --- * UniFi Poller: [https://github.com/davidnewhall/unifi-poller](https://github.com/davidnewhall/unifi-poller) * UniFi Library: [https://github.com/golift/unifi](https://github.com/golift/unifi) * Grafana Dashboards: [https://grafana.com/dashboards?search=unifi-poller](https://grafana.com/dashboards?search=unifi-poller)