From 04e6d674897f4e9eebedd51339ba3a9aa89b0920 Mon Sep 17 00:00:00 2001 From: David Newhall II Date: Sat, 22 Jun 2019 19:41:44 -0700 Subject: [PATCH] Man file and config file updates. --- cmd/unifi-poller/README.md | 120 +++++++++++++++++++++---------------- examples/up.conf.example | 21 ++++--- examples/up.json.example | 2 +- examples/up.xml.example | 42 +++++++------ examples/up.yaml.example | 20 ++++--- 5 files changed, 117 insertions(+), 88 deletions(-) diff --git a/cmd/unifi-poller/README.md b/cmd/unifi-poller/README.md index a7e4ace5..96d7bfd6 100644 --- a/cmd/unifi-poller/README.md +++ b/cmd/unifi-poller/README.md @@ -1,20 +1,26 @@ unifi-poller(1) -- Utility to poll UniFi Controller Metrics and store them in InfluxDB === -## SYNOPSIS - +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. +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. -## DESCRIPTION +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. -* This application polls a Unifi Controller API for Client and Device Metrics. -* The metrics are then stored in an InfluxDB instance. -* See the example configuration file for help configuring this application. - -## OPTIONS +* See the example configuration file for more examples and default configurations. +OPTIONS +--- `unifi-poller [-c ] [-j ] [-h] [-v]` -c, --config @@ -29,7 +35,7 @@ This daemon polls a Unifi controller at a short interval and stores the collecte 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 + 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 @@ -39,33 +45,42 @@ This daemon polls a Unifi controller at a short interval and stores the collecte -h, --help Display usage and exit. -## CONFIGURATION +CONFIGURATION +--- +* Config File Default Location: `/etc/unifi-poller/up.conf` +* Config File Default Format: `TOML` +* Possible formats: `XML`, `JSON`, `TOML`, `YAML` -* Config File Default Location: /etc/unifi-poller/up.conf +The config file can be written in four different syntax formats. The application +decides which one to used 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: ["default"] - This list of strings should represent the names of sites on the unifi + 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 + 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. + The UniFi Controller only updates traffic stats about every 30 seconds. - `debug` default: false + 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 + 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. - `max_errors` default: 0 + 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. @@ -77,56 +92,57 @@ This daemon polls a Unifi controller at a short interval and stores the collecte 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 + 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. Many servers do not use auth. + influx_user default: unifi + Username used to authenticate with InfluxDB. - `influx_pass` default: unifi + influx_pass default: unifi Password used to authenticate with InfluxDB. - `influx_db` default: unifi + 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_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 + 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 + 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. - `verify_ssl` default: false - If your Unifi controller has a valid SSL certificate, you can enable + 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 - +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. Some valid time units are: +multiple time units to add them together. A few valid time units are: - `us` (microsecond) - `ns` (nanosecond) - `ms` (millisecond) - `s` (second) - `m` (minute) - `h` (hour) + ms (millisecond) + s (second) + m (minute) -Example Use: `1m`, `5h`, `100ms`, `17s`, `1s45ms`, `1m3s` +Example Use: `35s`, `1m`, `1m30s` -## AUTHOR +AUTHOR +--- +* Garrett Bjerkhoel (original code) ~ 2016 +* David Newhall II (rewritten) ~ 4/20/2018 +* David Newhall II (still going) ~ 6/7/2019 -* Garrett Bjerkhoel (original code) ~ 2016 -* David Newhall II (rewritten) ~ 4/20/2018 -* David Newhall II (still going) ~ 6/7/2019 - -## LOCATION - -* https://github.com/davidnewhall/unifi-poller -* UniFi Library: https://github.com/golift/unifi -* previously: https://github.com/dewski/unifi +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) diff --git a/examples/up.conf.example b/examples/up.conf.example index ecbe22c0..3d0bcd1b 100644 --- a/examples/up.conf.example +++ b/examples/up.conf.example @@ -3,22 +3,24 @@ ######################################################## # If the controller has more than one site, specify which sites to poll here. -# If only one site, "default" is likely the correct name. -# Set this to ["all"] to poll all sites, no matter their names. -#sites = ["default"] +# Set this to ["default"] to poll only the first site on the controller. +# A setting of ["all"] will poll all sites; this works if you only have 1 site too. +#sites = ["all"] -# The Unifi Controller only updates traffic stats about every 30 seconds. +# The UniFi Controller only updates traffic stats about every 30 seconds. # Setting this to something lower may lead to "zeros" in your data. You've been warned. #interval = "30s" # Turns on line numbers, microsecond logging, and a per-device log. +# The default is false, but I personally leave this on at home (four devices). +# This may be noisy if you have a lot of devices. It adds one line per device. #debug = false -# Turns off per-device log and per-interval log. Logs only errors. -# Recommend using debug with this setting for better error logging. +# Turns off per-interval logs. Only startup and error logs will be emitted. +# Recommend enabling debug with this setting for better error logging. #quiet = false -# If the poller experiences an error from the Unifi Controller or from InfluxDB +# If the poller experiences an error from the UniFi Controller or from InfluxDB # it will exit. If you do not want it to exit, change max_errors to -1. You can # adjust the config to tolerate more errors by setting this to a higher value. # Recommend setting this between 0 and 5. See man page for more explanation. @@ -31,12 +33,13 @@ # Be sure to create this database. #influx_db = "unifi" -# Make a read-only user in the Unifi Admin Settings. +# Make a read-only user in the UniFi Admin Settings. #unifi_user = "influxdb" # You may also set env variable UNIFI_PASSWORD instead of putting this in the config. unifi_pass = "4BB9345C-2341-48D7-99F5-E01B583FF77F" #unifi_url = "https://127.0.0.1:8443" -# If your Unifi controller has a valid SSL certificate, you can enable +# If your UniFi controller has a valid SSL certificate, you can enable # this option to validate it. Otherwise, any SSL certificate is valid. +# If you don't know if you have a valid SSL cert, then you don't have one. #verify_ssl = false diff --git a/examples/up.json.example b/examples/up.json.example index 2d2c415f..3ce54de4 100644 --- a/examples/up.json.example +++ b/examples/up.json.example @@ -1,5 +1,5 @@ { - "sites": ["default"], + "sites": ["all"], "interval": "30s", "debug": false, "quiet": false, diff --git a/examples/up.xml.example b/examples/up.xml.example index e49f3277..ccd6cf98 100644 --- a/examples/up.xml.example +++ b/examples/up.xml.example @@ -1,58 +1,66 @@ - default + all 30s - + false false 0 - + unifi unifi http://127.0.0.1:8086 unifi - + influxdb https://127.0.0.1:8443 false diff --git a/examples/up.yaml.example b/examples/up.yaml.example index 502745b0..b4685d20 100644 --- a/examples/up.yaml.example +++ b/examples/up.yaml.example @@ -3,23 +3,25 @@ ######################################################## --- # If the controller has more than one site, specify which sites to poll here. -# If only one site, "default" is likely the correct name. -# Change default to all to poll all sites, no matter their names. +# Set this to "default" to poll only the first site on the controller. +# A setting of "all" will poll all sites; this works if you only have 1 site too. sites: - - default + - all -# The Unifi Controller only updates traffic stats about every 30 seconds. +# The UniFi Controller only updates traffic stats about every 30 seconds. # Setting this to something lower may lead to "zeros" in your data. You've been warned. interval: "30s" # Turns on line numbers, microsecond logging, and a per-device log. +# The default is false, but I personally leave this on at home (four devices). +# This may be noisy if you have a lot of devices. It adds one line per device. debug: false -# Turns off per-device log and per-interval log. Logs only errors. -# Recommend using debug with this setting for better error logging. +# Turns off per-interval logs. Only startup and error logs will be emitted. +# Recommend enabling debug with this setting for better error logging. quiet: false -# If the poller experiences an error from the Unifi Controller or from InfluxDB +# If the poller experiences an error from the UniFi Controller or from InfluxDB # it will exit. If you do not want it to exit, change max_errors to -1. You can # adjust the config to tolerate more errors by setting this to a higher value. # Recommend setting this between 0 and 5. See man page for more explanation. @@ -32,11 +34,11 @@ influx_pass: "unifi" # Be sure to create this database. influx_db: "unifi" -# Make a read-only user in the Unifi Admin Settings. +# Make a read-only user in the UniFi Admin Settings. unifi_user: "influxdb" unifi_pass: "" unifi_url: "https://127.0.0.1:8443" -# If your Unifi controller has a valid SSL certificate, you can enable +# If your UniFi controller has a valid SSL certificate, you can enable # this option to validate it. Otherwise, any SSL certificate is valid. verify_ssl: false