From 510251252ba4b2ec70a7b80be4c60a035df86ce5 Mon Sep 17 00:00:00 2001 From: davidnewhall2 Date: Sat, 14 Dec 2019 19:37:41 -0800 Subject: [PATCH] update docs --- examples/MANUAL.md | 34 +++++++++++++++------------------- examples/up.conf.example | 30 +++++++++++++++--------------- examples/up.json.example | 18 ++++++++++-------- examples/up.xml.example | 20 +++++++++----------- examples/up.yaml.example | 19 ++++++++++--------- pkg/poller/config.go | 1 + pkg/poller/start.go | 24 ++++++++++++++++-------- 7 files changed, 76 insertions(+), 70 deletions(-) diff --git a/examples/MANUAL.md b/examples/MANUAL.md index 8df5e733..0b1a8860 100644 --- a/examples/MANUAL.md +++ b/examples/MANUAL.md @@ -65,14 +65,6 @@ 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. @@ -136,35 +128,39 @@ is provided so the application can be easily adapted to any environment. 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 + >>> 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. - unifi_user default: influxdb + 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 + user 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 + 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 + 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. - 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. diff --git a/examples/up.conf.example b/examples/up.conf.example index a403f5b7..31713a84 100644 --- a/examples/up.conf.example +++ b/examples/up.conf.example @@ -2,10 +2,6 @@ # commented lines are defaults, uncomment to change. # ######################################################## -# 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. -sites = ["all"] # The UniFi Controller only updates traffic stats about every 30 seconds. # Setting this to something lower may lead to "zeros" in your data. @@ -51,18 +47,22 @@ influx_db = "unifi" # If your InfluxDB uses an invalid SSL cert, set this to true. influx_insecure_ssl = false -# Make a read-only user in the UniFi Admin Settings. -unifi_user = "influx" -# 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" +# You may repeat the following section to poll additional controllers. -# Some controllers or reverse proxy configurations do not allow cookies to be -# re-user on every request (every interval). This setting provides a workaround -# That causes the poller to re-auth (login) to the controller on every interval. -# Only enable this if you get login errors after 30 seconds. This will generate -# a few more requests to your controller every interval. -reauthenticate = false +[[controller]] +# Friendly name used in dashboards. +name = "" + +url = "https://127.0.0.1:8443" +# Make a read-only user in the UniFi Admin Settings. +user = "influx" +# You may also set env variable UNIFI_PASSWORD instead of putting this in the config. +pass = "4BB9345C-2341-48D7-99F5-E01B583FF77F" + +# 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. +sites = ["all"] # Enable collection of Intrusion Detection System Data (InfluxDB only). # Only useful if IDS or IPS are enabled on one of the sites. diff --git a/examples/up.json.example b/examples/up.json.example index 7842987f..07ecd509 100644 --- a/examples/up.json.example +++ b/examples/up.json.example @@ -1,5 +1,4 @@ { - "sites": ["all"], "interval": "30s", "debug": false, "quiet": false, @@ -10,11 +9,14 @@ "influx_pass": "unifi", "influx_db": "unifi", "influx_insecure_ssl": false, - "unifi_user": "influx", - "unifi_pass": "", - "unifi_url": "https://127.0.0.1:8443", - "save_ids": false, - "save_sites": true, - "reauthenticate": false, - "verify_ssl": false + "controller": [{ + "name": "", + "user": "influx", + "pass": "", + "url": "https://127.0.0.1:8443", + "sites": ["all"], + "save_ids": false, + "save_sites": true, + "verify_ssl": false + }] } diff --git a/examples/up.xml.example b/examples/up.xml.example index e4523e3a..551ff8b7 100644 --- a/examples/up.xml.example +++ b/examples/up.xml.example @@ -7,7 +7,6 @@ --> - all 60s false @@ -21,14 +20,13 @@ http://127.0.0.1:8086 unifi false - - influx - - https://127.0.0.1:8443 - false - false - - false - true - + + all + influx + + https://127.0.0.1:8443 + false + false + true + diff --git a/examples/up.yaml.example b/examples/up.yaml.example index 0eac5a24..b076feb4 100644 --- a/examples/up.yaml.example +++ b/examples/up.yaml.example @@ -3,8 +3,6 @@ # provided values are defaults. See up.conf.example! # ######################################################## --- -sites: - - all interval: "30s" debug: false @@ -19,10 +17,13 @@ influx_pass: "unifi" influx_db: "unifi" influx_insecure_ssl: false -unifi_user: "influx" -unifi_pass: "" -unifi_url: "https://127.0.0.1:8443" -reauthenticate: false -verify_ssl: false -save_ids: false -save_sites: true +controller: + - name: "" + user: "influx" + pass: "" + url: "https://127.0.0.1:8443" + sites: + - all + verify_ssl: false + save_ids: false + save_sites: true diff --git a/pkg/poller/config.go b/pkg/poller/config.go index b0266405..04d3f1a4 100644 --- a/pkg/poller/config.go +++ b/pkg/poller/config.go @@ -61,6 +61,7 @@ type Controller struct { VerifySSL bool `json:"verify_ssl" toml:"verify_ssl" xml:"verify_ssl" yaml:"verify_ssl"` SaveIDS bool `json:"save_ids" toml:"save_ids" xml:"save_ids" yaml:"save_ids"` SaveSites bool `json:"save_sites,omitempty" toml:"save_sites,omitempty" xml:"save_sites" yaml:"save_sites"` + Name string `json:"name" toml:"name" xml:"name,attr" yaml:"name"` User string `json:"user,omitempty" toml:"user,omitempty" xml:"user" yaml:"user"` Pass string `json:"pass,omitempty" toml:"pass,omitempty" xml:"pass" yaml:"pass"` URL string `json:"url,omitempty" toml:"url,omitempty" xml:"url" yaml:"url"` diff --git a/pkg/poller/start.go b/pkg/poller/start.go index 54dc0731..154f0395 100644 --- a/pkg/poller/start.go +++ b/pkg/poller/start.go @@ -17,13 +17,6 @@ import ( func New() *UnifiPoller { return &UnifiPoller{ Config: &Config{ - Controllers: []Controller{{ - Sites: []string{"all"}, - User: defaultUnifiUser, - Pass: "", - URL: defaultUnifiURL, - SaveSites: true, - }}, InfluxURL: defaultInfluxURL, InfluxUser: defaultInfluxUser, InfluxPass: defaultInfluxPass, @@ -65,6 +58,17 @@ func (u *UnifiPoller) Start() error { if _, err := config.ParseENV(u.Config, ENVConfigPrefix); err != nil { return err } + + if len(u.Config.Controllers) < 1 { + u.Config.Controllers = []Controller{{ + Sites: []string{"all"}, + User: defaultUnifiUser, + Pass: "", + URL: defaultUnifiURL, + SaveSites: true, + }} + } + if u.Flag.DumpJSON != "" { return u.DumpJSONPayload() } @@ -99,7 +103,11 @@ func (f *Flag) Parse(args []string) { // 2. Run the collector one time and report the metrics to influxdb. (lambda) // 3. Start a web server and wait for Prometheus to poll the application for metrics. func (u *UnifiPoller) Run() error { - for _, c := range u.Config.Controllers { + for i, c := range u.Config.Controllers { + if c.Name == "" { + u.Config.Controllers[i].Name = c.URL + } + switch err := u.GetUnifi(c); err { case nil: u.Logf("Polling UniFi Controller at %s v%s as user %s. Sites: %v",