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

6.1 KiB
Raw Blame History

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.

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

-c, --config <config-file>
    Provide a configuration file (instead of the default).

-v, --version
    Display version and exit.

-j, --dumpjson <filter>
    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

Additional parameters are added by output packages. Parameters can also be set using environment variables. See the GitHub wiki for more information!

>>> POLLER FIELDS FOLLOW - you may have multiple controllers:

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.

>>> UNIFI CONTROLLER FIELDS FOLLOW - you may have multiple controllers:

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

url                    default: https://127.0.0.1:8443
    This is the URL where the UniFi Controller is available.

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.

pass                   no default
    Password used to authenticate with UniFi controller. This can also be
    set in an environment variable instead of a configuration file.

save_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.
    IDS data does not contain metrics, so this doesn't work with Prometheus.

save_sites             default: true
    Setting this parameter to false will disable saving Network Site data.
    This data populates the Sites dashboard, and this setting affects influx
    and prometheus.

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