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-60 seconds. Only works if "mode" (below) is "influx" - other modes do not use interval. 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 and report measurements to InfluxDB. Providing an invalid value will run in this default mode. * Value: influxlambda 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. * Value: prometheus In this mode the application opens an http interface and exports the measurements at /metrics for collection by prometheus. Enabling this mode disables InfluxDB usage entirely. http_listen default: 0.0.0.0:9130 This option controls the IP and port the http listener uses when the mode is set to prometheus. This setting has no effect when other modes are in use. Metrics become available at the /metrics URI. 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 influx_insecure_ssl default: false Setting this to true will allow use of InfluxDB with an invalid SSL certificate. 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)