update docs and examples

examples/README.md

@@ -8,6 +8,7 @@ file with `.json`, and YAML with `.yaml`. The default
 format is always TOML and may have any _other_ suffix.
 
 #### Dashboards
-This folder used to contain Grafana Dashboards.
-**They are now located at [Grafana.com](https://grafana.com/dashboards?search=unifi-poller).**
-Also see [Grafana Dashboards](https://github.com/unifi-poller/unifi-poller/wiki/Grafana-Dashboards) Wiki.
+
+-   This folder used to contain Grafana Dashboards.
+-   **They are now located at [Grafana.com](https://grafana.com/dashboards?search=unifi-poller).**
+-   [Grafana Dashboards Wiki](https://github.com/unifi-poller/unifi-poller/wiki/Grafana-Dashboards)

examples/up.conf.example

@@ -53,7 +53,9 @@
 # The following section contains the default credentials/configuration for any
 # dynamic controller (see above section), or the primary controller if you do not
 # provide one and dynamic is disabled. In other words, you can just add your
-# controller here and delete the following section.
+# controller here and delete the following section. The internal defaults are
+# shown below. Any missing values will assume these displayed defaults, except
+# the role; if omitted the role is set to the url. See comments below for details.
 [unifi.defaults]
   #role       = "main controller"
   url        = "https://127.0.0.1:8443"
@@ -63,21 +65,27 @@
   save_ids   = false
   save_dpi   = false
   save_sites = true
+  hash_pii   = false
   verify_ssl = false
 
 # The following is optional and used for configurations with multiple controllers.
 
 # You may repeat the following section to poll multiple controllers.
+# Any ommitted variables will have their values taken from the defaults, above.
 #[[unifi.controller]]
-  # Friendly name used in dashboards. Uses URL if left empty; which is fine.
+  # Role is a friendly name used in dashboards. Uses URL if left empty; which is fine.
   # Avoid changing this later because it will live forever in your database.
   # Multiple controllers may share a role. This allows grouping during scrapes.
-  #role = ""
+  # --- This will be deprecated in a future version of UniFi Poller. ---
+  #role = "https://127.0.0.1:8443"
+
+  # URL for the UniFi Controller. Do not add any paths after the host:port.
+  # Do not use port 8443 if you have a UDM.
   #url = "https://127.0.0.1:8443"
 
   # Make a read-only user in the UniFi Admin Settings, allow it access to all sites.
   #user = "unifipoller"
-  #pass = "4BB9345C-2341-48D7-99F5-E01B583FF77F"
+  #pass = "unifipoller"
 
   # 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.
@@ -100,6 +108,10 @@
   # It's not valuable to everyone and setting this to false will save resources.
   #save_sites = true
 
+  # Hash, with md5, client names and MAC addresses. This attempts to protect
+  # personally identifiable information. Most users won't want to enable this.
+  #hash_pii = false
+
   # If your UniFi controller has a valid SSL certificate (like lets encrypt),
   # 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.

examples/up.json.example

@@ -32,6 +32,7 @@
       "save_ids":   false,
       "save_dpi":   false,
       "save_sites": true,
+      "hash_pii":   false,
       "verify_ssl": false
     },
     "controllers": [
@@ -41,9 +42,10 @@
        "pass": "unifipoller",
        "url": "https://127.0.0.1:8443",
        "sites": ["all"],
-       "save_dpi": false,
        "save_ids": false,
+       "save_dpi": false,
        "save_sites": true,
+       "hash_pii":   false,
        "verify_ssl": false
       }
     ]

examples/up.xml.example

@@ -6,7 +6,7 @@
 # See up.conf.example!         v2           #
 #############################################
 
-<plugin> and <site> are lists of strings and may be repeated.
+NOTE: <plugin> and <site> are lists of strings and may be repeated.
 -->
 <poller debug="false" quiet="false">
   <!-- plugin></plugin -->
@@ -31,10 +31,11 @@
       <user>unifipoller</user>
       <pass>unifipoller</pass>
       <url>https://127.0.0.1:8443</url>
-      <verify_ssl>false</verify_ssl>
       <save_ids>false</save_ids>
       <save_dpi>false</save_dpi>
       <save_sites>true</save_sites>
+      <hash_pii>false</hash_pii>
+      <verify_ssl>false</verify_ssl>
     </default>
 
     <!-- Repeat this stanza to poll additional controllers. -->
@@ -43,10 +44,11 @@
       <user>unifipoller</user>
       <pass>unifipoller</pass>
       <url>https://127.0.0.1:8443</url>
-      <verify_ssl>false</verify_ssl>
       <save_ids>false</save_ids>
       <save_dpi>false</save_dpi>
       <save_sites>true</save_sites>
+      <hash_pii>false</hash_pii>
+      <verify_ssl>false</verify_ssl>
     </controller>
 
   </unifi>

examples/up.yaml.example

@@ -33,10 +33,11 @@ unifi:
     url:  "https://127.0.0.1:8443"
     sites:
       - all
-    verify_ssl: false
     save_ids:   false
     save_dpi:   false
     save_sites: true
+    hash_pii:   false
+    verify_ssl: false
 
 
   controllers:
@@ -47,7 +48,8 @@ unifi:
       url:  "https://127.0.0.1:8443"
       sites:
         - all
-      verify_ssl: false
       save_ids:   false
       save_dpi:   false
+      hash_pii:   false
       save_sites: true
+      verify_ssl: false