public_git
/
unpoller_unpoller
mirror of https://github.com/unpoller/unpoller.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Man file and config file updates.

This commit is contained in:
David Newhall II 2019-06-22 19:41:44 -07:00
parent 8de877a4bd
commit 04e6d67489
5 changed files with 117 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

120
cmd/unifi-poller/README.md
View File

@ -1,20 +1,26 @@
unifi-poller(1) -- Utility to poll UniFi Controller Metrics and store them in InfluxDB unifi-poller(1) -- Utility to poll UniFi Controller Metrics and store them in InfluxDB
=== ===
## SYNOPSIS SYNOPSIS
---
`unifi-poller -c /etc/unifi-poller.conf` `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. * See the example configuration file for more examples and default configurations.
* The metrics are then stored in an InfluxDB instance.
* See the example configuration file for help configuring this application.
## OPTIONS
OPTIONS
---
`unifi-poller [-c <config-file>] [-j <filter>] [-h] [-v]` `unifi-poller [-c <config-file>] [-j <filter>] [-h] [-v]`
-c, --config <config-file> -c, --config <config-file>
@ -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 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 lot of information. Recommend piping it into a file and/or into jq for
better visualization. This requires a valid config file that contains 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 data for sites listed in the config file. The application exits after
printing the JSON payload; it does not daemonize or report to InfluxDB printing the JSON payload; it does not daemonize or report to InfluxDB
with this option. The `other` option is special. This allows you request 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 -h, --help
Display usage and exit. 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` `Config File Parameters`
`sites` default: ["default"] sites default: ["all"]
This list of strings should represent the names of sites on the unifi 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 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 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 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. 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. 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 This turns on time stamps and line numbers in logs, outputs a few extra
lines of information while processing. 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 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 errors will be logged. Using this with debug=true adds line numbers to
any error logs. any error logs.
`max_errors` default: 0 max_errors default: 0
If you restart the UniFI controller, the poller will lose access until 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 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. 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 docker or launchd. The default setting of 0 will cause an exit after
just 1 error. Recommended values are 0-5. 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. This is the URL where the Influx web server is available.
`influx_user` default: unifi influx_user default: unifi
Username used to authenticate with InfluxDB. Many servers do not use auth. Username used to authenticate with InfluxDB.
`influx_pass` default: unifi influx_pass default: unifi
Password used to authenticate with InfluxDB. Password used to authenticate with InfluxDB.
`influx_db` default: unifi influx_db default: unifi
Custom database created in InfluxDB to use with this application. 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 unifi_url default: https://127.0.0.1:8443
This is the URL where the Unifi Controller is available. This is the URL where the UniFi Controller is available.
`unifi_user` default: influxdb unifi_user default: influxdb
Username used to authenticate with Unifi controller. This should be a Username used to authenticate with UniFi controller. This should be a
special service account created on the control with read-only access. special service account created on the control with read-only access.
`unifi_user` no default ENV: UNIFI_PASSWORD unifi_user no default ENV: UNIFI_PASSWORD
Password used to authenticate with Unifi controller. This can also be Password used to authenticate with UniFi controller. This can also be
set in an environment variable instead of a configuration file. set in an environment variable instead of a configuration file.
`verify_ssl` default: false verify_ssl default: false
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. 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. This application uses the Go Time Durations for a polling interval.
The format is an integer followed by a time unit. You may append 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) ms (millisecond)
`ns` (nanosecond) s (second)
`ms` (millisecond) m (minute)
`s` (second)
`m` (minute)
`h` (hour)
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 LOCATION
* David Newhall II (rewritten) ~ 4/20/2018 ---
* David Newhall II (still going) ~ 6/7/2019 * 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)
## LOCATION
* https://github.com/davidnewhall/unifi-poller
* UniFi Library: https://github.com/golift/unifi
* previously: https://github.com/dewski/unifi

21
examples/up.conf.example
View File

@ -3,22 +3,24 @@
######################################################## ########################################################
# If the controller has more than one site, specify which sites to poll here. # 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 ["default"] to poll only the first site on the controller.
# Set this to ["all"] to poll all sites, no matter their names. # A setting of ["all"] will poll all sites; this works if you only have 1 site too.
#sites = ["default"] #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. # Setting this to something lower may lead to "zeros" in your data. You've been warned.
#interval = "30s" #interval = "30s"
# Turns on line numbers, microsecond logging, and a per-device log. # 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 #debug = false
# Turns off per-device log and per-interval log. Logs only errors. # Turns off per-interval logs. Only startup and error logs will be emitted.
# Recommend using debug with this setting for better error logging. # Recommend enabling debug with this setting for better error logging.
#quiet = false #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 # 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. # 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. # Recommend setting this between 0 and 5. See man page for more explanation.
@ -31,12 +33,13 @@
# Be sure to create this database. # Be sure to create this database.
#influx_db = "unifi" #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_user = "influxdb"
# You may also set env variable UNIFI_PASSWORD instead of putting this in the config. # You may also set env variable UNIFI_PASSWORD instead of putting this in the config.
unifi_pass = "4BB9345C-2341-48D7-99F5-E01B583FF77F" unifi_pass = "4BB9345C-2341-48D7-99F5-E01B583FF77F"
#unifi_url = "https://127.0.0.1:8443" #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. # 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 #verify_ssl = false

2
examples/up.json.example
View File

@ -1,5 +1,5 @@
{ {
"sites": ["default"], "sites": ["all"],
"interval": "30s", "interval": "30s",
"debug": false, "debug": false,
"quiet": false, "quiet": false,

42
examples/up.xml.example
View File

@ -1,58 +1,66 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<!-- <!--
######################################################## #######################################################
# unifi-poller primary configuration file. XML FORMAT # # unifi-poller primary configuration file. XML FORMAT #
# provided values are defaults # # provided values are defaults #
######################################################## #######################################################
--> -->
<unifi-poller> <unifi-poller>
<!-- <!--
If the controller has more than one site, specify which sites to poll here. # 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 "default" to poll only the first site on the controller.
Set this to ["all"] to poll all sites, no matter their names. # A setting of "all" will poll all sites; this works if you only have 1 site too.
Add more sites by adding additional lines: Add more sites by adding additional lines:
<sites>site1</sites> <sites>site1</sites>
<sites>site2</sites> <sites>site2</sites>
--> -->
<sites>default</sites> <sites>all</sites>
<!-- <!--
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. # Setting this to something lower may lead to "zeros" in your data. You've been warned.
--> -->
<interval>30s</interval> <interval>30s</interval>
<!-- Turns on line numbers, microsecond logging, and a per-device log. --> <!--
# 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</debug> <debug>false</debug>
<!-- <!--
Turns off per-device log and per-interval log. Logs only errors. # Turns off per-interval logs. Only startup and error logs will be emitted.
Recommend using debug with this setting for better error logging. # Recommend enabling debug with this setting for better error logging.
--> -->
<quiet>false</quiet> <quiet>false</quiet>
<!-- <!--
# 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 # 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. # 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. # Recommend setting this between 0 and 5. See man page for more explanation.
--> -->
<max_errors>0</max_errors> <max_errors>0</max_errors>
<!-- InfluxDB does not require auth by default, so the user/password are probably unimportant. --> <!--
# InfluxDB does not require auth by default, so the user/password are probably unimportant.
-->
<influx_db>unifi</influx_db> <influx_db>unifi</influx_db>
<influx_pass>unifi</influx_pass> <influx_pass>unifi</influx_pass>
<influx_url>http://127.0.0.1:8086</influx_url> <influx_url>http://127.0.0.1:8086</influx_url>
<influx_user>unifi</influx_user> <influx_user>unifi</influx_user>
<!-- Make a read-only user in the Unifi Admin Settings. --> <!--
# Make a read-only user in the UniFi Admin Settings.
-->
<unifi_user>influxdb</unifi_user> <unifi_user>influxdb</unifi_user>
<unifi_pass></unifi_pass> <unifi_pass></unifi_pass>
<unifi_url>https://127.0.0.1:8443</unifi_url> <unifi_url>https://127.0.0.1:8443</unifi_url>
<!-- <!--
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. # this option to validate it. Otherwise, any SSL certificate is valid.
--> -->
<verify_ssl>false</verify_ssl> <verify_ssl>false</verify_ssl>

20
examples/up.yaml.example
View File

@ -3,23 +3,25 @@
######################################################## ########################################################
--- ---
# If the controller has more than one site, specify which sites to poll here. # 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 "default" to poll only the first site on the controller.
# Change default to all to poll all sites, no matter their names. # A setting of "all" will poll all sites; this works if you only have 1 site too.
sites: 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. # Setting this to something lower may lead to "zeros" in your data. You've been warned.
interval: "30s" interval: "30s"
# Turns on line numbers, microsecond logging, and a per-device log. # 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 debug: false
# Turns off per-device log and per-interval log. Logs only errors. # Turns off per-interval logs. Only startup and error logs will be emitted.
# Recommend using debug with this setting for better error logging. # Recommend enabling debug with this setting for better error logging.
quiet: false 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 # 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. # 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. # 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. # Be sure to create this database.
influx_db: "unifi" 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_user: "influxdb"
unifi_pass: "" unifi_pass: ""
unifi_url: "https://127.0.0.1:8443" 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. # this option to validate it. Otherwise, any SSL certificate is valid.
verify_ssl: false verify_ssl: false