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
===
## 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 <config-file>] [-j <filter>] [-h] [-v]`
-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
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)

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

2
examples/up.json.example
View File

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

42
examples/up.xml.example
View File

@ -1,58 +1,66 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
########################################################
#######################################################
# unifi-poller primary configuration file. XML FORMAT #
# provided values are defaults #
########################################################
# provided values are defaults #
#######################################################
-->
<unifi-poller>
<!--
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.
# If the controller has more than one site, specify which sites to poll here.
# 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.
Add more sites by adding additional lines:
<sites>site1</sites>
<sites>site2</sites>
-->
<sites>default</sites>
<sites>all</sites>
<!--
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.
# 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</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>
<!--
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</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
# 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.
-->
<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_pass>unifi</influx_pass>
<influx_url>http://127.0.0.1:8086</influx_url>
<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_pass></unifi_pass>
<unifi_url>https://127.0.0.1:8443</unifi_url>
<!--
If your Unifi controller has a valid SSL certificate, you can enable
this option to validate it. Otherwise, any SSL certificate is valid.
# 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</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 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