Documented hypr-audit sources. (syslog-ng#113)

Documented hypr-audit-trail() and hyper-app-audit-trail() and their
available options.

_data/external_links.yml

@@ -881,6 +881,11 @@ hadoop-rel:
   url: http://hadoop.apache.org/releases.html
   title: [ "Hadoop release page" ]
 
+hypr-audit:
+  id: hypr-audit
+  url: https://apidocs.hypr.com/
+  title: [ "Hypr REST API" ]
+
 jellyfin:
   id: jellyfin
   url: https://jellyfin.org/

doc/_admin-guide/060_Sources/031_Hypr/000_Hypr_options.md

@@ -0,0 +1,68 @@
+---
+title: `hypr-audit-trail()` and `hypr-app-audit-trail()` source options
+id: adm-src-hypr-opt
+---
+
+The `hypr-audit-trail()` and `hypr-app-audit-trail() sources have the following options:
+
+## url()
+
+|  Type:   |      url|
+|  Default:|         |
+
+*Description:* A custom URL for Hypr API access ("https://\<custom domain\>.hypr.com")
+
+## bearer-token()
+
+|  Type:   |    token|
+|  Default:|         |
+
+*Description:* The base64 encoded authentication token from Hypr.
+
+## page-size()
+
+|  Type:   |    number|
+|  Default:|       100|
+
+*Description:* Defines the number of results to return in a single page (optional).
+
+## initial-hours()
+
+|  Type:   |   number(hours)|
+|  Default:|               4|
+
+*Description:* Defines the number of hours to search backward on initial fetch (optional).
+
+## application-skip-list()
+
+|  Type:   |   rpAppId list|
+|  Default:| `HYPRDefaultApplication`, `HYPRDefaultWorkstationApplication`|
+
+*Description:* The list of rpAppIds not to retrieve from Hypr (optional).
+
+## log-level()
+
+|  Type:   |   string|
+|  Default:|   `INFO`|
+
+The following values are available for log-level():
+
+* `DEBUG`
+* `INFO`
+* `WARNING`
+* `ERROR`
+* `CRITICAL`
+
+## flags()
+
+|  Type:   |   string|
+|  Default:|   |
+
+*Description:* The flags passed to the source, can be used for example to disable message parsing with flags(no-parse) (optional).
+
+## ignore-persistence()
+
+|  Type:   |   boolean|
+|  Default:|   `no`|
+
+*Description:* This option can be set to ignore the saved value in the persist file, and start querying from the current time (optional).

doc/_admin-guide/060_Sources/031_Hypr/README.md

@@ -0,0 +1,53 @@
+---
+title: 'Hypr Audit Trail and Hyper App Audit Trail'
+short_title: hypr
+id: adm-src-hypr
+description: >-
+    This source is available in syslog-ng OSE 4.2 and later versions. Using this source syslog-ng OSE can fetch events from the Hypr REST API using the following drivers:
+---
+* `hypr-audit-trail()`: is a source driver that pulls messages from the Hypr API, associated to any RP Application ID.
+* `hypr-app-audit-trail()`: is a source driver that pulls messages from the Hypr API, but only those associated to a specific RP Application ID.
+
+**Note:** Applications that are registered after syslog-ng is started are not recognized.
+{: .notice--info}
+
+## Hyper Audit Trail
+
+The `hypr-audit-trail()` source queries the Hypr API for the list of potential applications at startup, then monitors the audit trail for each of the detected applications.
+
+To follow audit trails restart syslog-ng.
+
+### Example: hypr-audit-trail minimal configuration
+
+```config
+source s_hypr {
+    hypr-audit-trail(
+        url('https://<custom domain>.hypr.com')
+        bearer-token('<base64 encoded bearer token>')
+    );
+};
+```
+
+### Example: hypr-audit-trail detailed configuration
+
+```config
+source s_hypr {
+    hypr-audit-trail(
+        url('https://<custom domain>.hypr.com')
+        bearer-token('<base64 encoded bearer token>')
+        page-size(<number of results to return in a single page>)
+        initial-hours(<number of hours to search backward on initial fetch>)
+        application-skip-list('HYPRDefaultApplication', 'HYPRDefaultWorkstationApplication')
+        log-level('INFO')
+        flags(<optional flags passed to the source>)
+        ignore-persistence(<yes/no>)
+    );
+};
+```
+## Hypr App Audit Trail
+
+The `hypr-app-audit-trail()` monitors the audit trail for one specific RP Application ID. This driver requires the `rp-app-id()` parameter in order to operate.
+
+## Acknowledgements
+
+These chapters are based on hypr-audit-trail() documentation written by Dan Elder and Axoflow.