mirror of
https://github.com/checktheroads/hyperglass
synced 2024-05-11 05:55:08 +00:00
125 lines
6.1 KiB
Plaintext
125 lines
6.1 KiB
Plaintext
---
|
|
id: logging
|
|
title: Logging & Webhooks
|
|
sidebar_label: Logging & Webhooks
|
|
keywords: [hyperglass, logging, webhook, hooks, syslog]
|
|
description: hyperglass Logging
|
|
---
|
|
|
|
hyperglass supports multiple types of logging, for both application troubleshooting and general reporting.
|
|
|
|
<div class="table--full-width" />
|
|
|
|
## File Logging
|
|
|
|
By default, hyperglass writes all log messages to a log file located at `/tmp/hyperglass.log`. This behavior and other file logging parameters may be overridden if needed:
|
|
|
|
| Parameter | Type | Default | Description |
|
|
| :---------- | :----: | :------- | :------------------------------------------------- |
|
|
| `directory` | String | `'/tmp'` | Valid directory where the log file can be written. |
|
|
| `format` | String | `'text'` | Log format - may be either `'text'` or `'json'`. |
|
|
| `max_size` | String | `'50MB'` | Maximum log file size before logs are rotated. |
|
|
|
|
The `logging` subsection contains additional subsections of its own for configuring other logging methods:
|
|
|
|
| Section | Description | All Options |
|
|
| :------- | :-------------------- | :------------------------------------: |
|
|
| `syslog` | Syslog settings | <PageLink to="#syslog">➡️</PageLink> |
|
|
| `http` | HTTP webhook settings | <PageLink to="#webhooks">➡️</PageLink> |
|
|
|
|
:::note
|
|
You do not have to set `enable: false` to disable syslogging or webhooks - if there is no configuration under the `syslog` or `http` subsections, it the option is disabled by default. The `enable` option exists for easy toggling without having to delete the other settings.
|
|
:::
|
|
|
|
## Syslog
|
|
|
|
If syslogging is enabled, all of the same log messages written to the file and/or stdout will be forwarded to the syslog server.
|
|
|
|
| Parameter | Type | Default | Description |
|
|
| :-------- | :-----: | :------ | :------------------------------------------------ |
|
|
| `enable` | Boolean | `true` | Optionally disable syslogging even if configured. |
|
|
| `host` | String | | Syslog target IP address or hostname. |
|
|
| `port` | Integer | `514` | Syslog target UDP port number. |
|
|
|
|
## Webhooks
|
|
|
|
If http logging is enabled, an HTTP POST will be sent to the configured target every time a query is submitted, _after_ it is validated.
|
|
|
|
| Parameter | Type | Default | Description |
|
|
| :----------- | :-----: | :---------- | :-------------------------------------------------------------------------------------------------------- |
|
|
| `enable` | Boolean | `true` | Optionally disable webhooks even if configured. |
|
|
| `host` | String | | HTTP URL to webhook target. |
|
|
| `headers` | Mapping | | Any arbitrary mappings, which will be sent as HTTP headers. |
|
|
| `params` | Mapping | | Any arbitrary mappings, which will be sent as URL parameters (e.g. `http://example.com/log?param=value`). |
|
|
| `verify_ssl` | Boolean | `true` | Verify SSL certificate of target. |
|
|
| `timeout` | Integer | `5` | Time in seconds before request times out. |
|
|
| `provider` | String | `'generic'` | Webhook provider. |
|
|
|
|
### Supported Providers
|
|
|
|
| Provider | Parameter Value |
|
|
| :--------------------------------------------------------------------------------------------------- | --------------: |
|
|
| Generic | `'generic'` |
|
|
| [Microsoft Teams](https://www.microsoft.com/en-us/microsoft-365/microsoft-teams/group-chat-software) | `'msteams'` |
|
|
| [Slack](https://slack.com/) | `'slack'` |
|
|
|
|
### Authentication
|
|
|
|
Basic and API key authentication are supported.
|
|
|
|
| Parameter | Type | Default | Description |
|
|
| :--------- | :----: | :-------- | :------------------------------------------------------------------------ |
|
|
| `mode` | String | `'basic'` | Authentication mode. Must be `'basic'` or `'api_key'` |
|
|
| `username` | String | | Username for basic authentication. |
|
|
| `password` | String | | Password for basic authentication, or API Key for API key authentication. |
|
|
|
|
:::important
|
|
If `api_key` is used, the header `X-API-Key: {key}` is added to the request, where `{key}` is the password.
|
|
:::
|
|
|
|
### Webhook Data Structure
|
|
|
|
If the `provider` field is set to `'generic'`, the webhook will POST JSON data in the following format:
|
|
|
|
```json
|
|
{
|
|
"query_location": "router01",
|
|
"query_type": "bgp_route",
|
|
"query_vrf": "default",
|
|
"query_target": "1.1.1.0/24",
|
|
"headers": {
|
|
"user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.163 Safari/537.36",
|
|
"referer": "http://lg.example.com/",
|
|
"accept-encoding": "gzip, deflate, br",
|
|
"accept-language": "en-US,en;q=0.9,fr;q=0.8,lb;q=0.7,la;q=0.6"
|
|
},
|
|
"source": "192.0.2.1",
|
|
"network": {
|
|
"prefix": "192.0.2.0/24",
|
|
"asns": ["64496"]
|
|
}
|
|
}
|
|
```
|
|
|
|
## Full example
|
|
|
|
```yaml title="hyperglass.yaml"
|
|
logging:
|
|
directory: /var/log
|
|
format: json
|
|
max_size: 10 MB
|
|
syslog:
|
|
host: syslog.example.com
|
|
http:
|
|
host: "https://example.com/logs"
|
|
authentication:
|
|
mode: basic
|
|
username: your username
|
|
password: your password
|
|
headers:
|
|
X-Special-Header: your header value
|
|
params:
|
|
app: hyperglass # URL would be https://example.com/logs?app=hyperglass
|
|
verify_ssl: false
|
|
```
|