164 lines
7.2 KiB
Markdown
164 lines
7.2 KiB
Markdown
[](https://gitlab.com/micro-entreprise/opnsense-prom-exporter/)
|
|
[](https://gitlab.com/micro-entreprise/opnsense-prom-exporter/)
|
|
[](https://pypi.python.org/pypi/opnsense-prom-exporter/)
|
|
[](https://pypi.org/project/opnsense-prom-exporter)
|
|
|
|
# OPNSense Prometheus exporter
|
|
|
|
I've configures OPNSense with High Availability settings using 2 servers.
|
|
|
|
- https://docs.opnsense.org/manual/hacarp.html
|
|
- https://docs.opnsense.org/manual/how-tos/carp.html
|
|
|
|
So I've 2 servers: _MAIN_ and _BACKUP_, in normal situation _MAIN_ server
|
|
is expected to be `active` and the _BACKUP_ server to be in `hot_standby` state.
|
|
|
|
The initial needs was to be able to make sure that _BACKUP_ server is ready (hot standby)
|
|
to get the main server role with the `active` state at any time.
|
|
|
|
> Unfortunately I've not found a proper configuration to call OPNSense HTTP API over
|
|
> opnvpn on backup server using blackbox configuratoin. That why I've started to develop
|
|
> this exporter install on a server on the LAN to be able to resquest both OPNSense servers.
|
|
|
|
## Metrics
|
|
|
|
This exporter gives following metrics, all metrics received following labels:
|
|
|
|
- `instance`: by default this is set with the hostname where is running this exporter service
|
|
- `host`: the host of the OPNSense
|
|
- `role`: `main` or `backup` to determine the OPNSense server role.
|
|
|
|
### Enums
|
|
|
|
- `opnsense_main_ha_state`: (deprecated) OPNSense HA state of the MAIN server
|
|
- `opnsense_backup_ha_state`: (deprecated) OPNSense HA state of the BACKUP server
|
|
- `opnsense_server_ha_state`: OPNSense HA state, on of following value:
|
|
- **active**: that OPNSense server is receiving traffic
|
|
- **hot_standby**: the OPNSense server is ready to be promote as active server
|
|
- **maintenancemode**: the OPNSense server was turned into maintenance mode
|
|
- **unavailable**: the OPNSense server wasn't accessible or return unexpected value
|
|
|
|
### Gauges
|
|
|
|
- `opnsense_active_server_traffic_rate`: Active OPNSense server traffic rate per interfaces bits/s
|
|
add following labels:
|
|
- **interface**: the interface to export (values given using `--opnsense-interfaces`)
|
|
- **metric**: the metric name (as today one of `rate_bits_in`, `rate_bits_in`)
|
|
|
|
## Usage
|
|
|
|
> _Note_: Most updated documentation from command line !
|
|
|
|
```
|
|
opnsense-exporter --help
|
|
usage: opnsense-exporter [-h] [--check-frequency-seconds FREQUENCY]
|
|
[--main-host MAIN] [--backup-host BACKUP]
|
|
[--opnsense-user USER]
|
|
[--opnsense-interfaces INTERFACES]
|
|
[--opnsense-password PASSWORD]
|
|
[--prometheus-instance PROM_INSTANCE]
|
|
|
|
OPNSense prometheus exporter
|
|
|
|
optional arguments:
|
|
-h, --help show this help message and exit
|
|
--check-frequency-seconds FREQUENCY, -c FREQUENCY
|
|
How often (in seconds) this server requests
|
|
OPNSense servers (default: 2)
|
|
--main-host MAIN, -m MAIN
|
|
MAIN OPNsense server that should be in `active`
|
|
state in normal configuration.
|
|
--backup-host BACKUP, -b BACKUP
|
|
BACKUP OPNsense server that should be `hot_standby`
|
|
state in normal configuration.
|
|
--opnsense-user USER, -u USER
|
|
OPNsense user. Expect to be the same on MAIN and
|
|
BACKUP servers
|
|
--opnsense-interfaces INTERFACES, -i INTERFACES
|
|
OPNsense interfaces (coma separated) list to
|
|
export trafic rates (bytes/s). An empty string ''
|
|
means not calling the traffic diagnostic REST API
|
|
so no `opnsense_active_server_traffic_rate`
|
|
metric. (default: wan,lan)
|
|
--opnsense-timeout-sec-get-vip-status GET_VIP_STATUS_TIMEOUT_SEC
|
|
Allow to configure timeout while requesting
|
|
OPNSense REST API
|
|
/api/diagnostics/interface/get_vip_status/
|
|
(default: 5)
|
|
--opnsense-timeout-sec-get-traffic GET_TRAFFIC_TIMEOUT_SEC
|
|
Allow to configure timeout while requesting
|
|
OPNSense REST API
|
|
/api/diagnostics/traffic/top/[INTERFACES]
|
|
(default: 15)
|
|
--opnsense-password PASSWORD, -p PASSWORD
|
|
OPNsense password. Expect to be the same on MAIN
|
|
and BACKUP servers
|
|
--prometheus-instance PROM_INSTANCE
|
|
Exporter Instance name, default value computed with
|
|
hostname where the server is running. Use to set
|
|
the instance label. (default: my-opnsense-prom-exporter-server)
|
|
```
|
|
|
|
You can setup env through `.env` file or environment variables with defined as default values
|
|
(so command line will get the precedent):
|
|
|
|
- **CHECK_FREQUENCY_SECONDS**: default value for `--check-frequency-seconds` param
|
|
- **OPNSENSE_MAIN_HOST**: default value for `--main-host` param
|
|
- **OPNSENSE_BACKUP_HOST**: default value for `--backup-host` param
|
|
- **OPNSENSE_USERNAME**: default value for `--opnsense-user` param
|
|
- **OPNSENSE_PASSWORD**: default value for `--opnsense-password` param
|
|
- **OPNSENSE_INTERFACES**: default value for `--opnsense-interfaces` param
|
|
- **OPNSENSE_TIMEOUT_SEC_GET_VIP_STATUS**: default value for `--opnsense-timeout-sec-get-vip-status` param
|
|
- **OPNSENSE_TIMEOUT_SEC_GET_TRAFFIC**: default value for `--opnsense-timeout-sec-get-traffic` param
|
|
|
|
## Roadmap
|
|
|
|
- allow to change the listening port (today it force using `8000`)
|
|
- improves logging to get a debug mode to understand errors based on unexpected payloads
|
|
|
|
## Changelog
|
|
|
|
### Version 1.1.0 (2023-09-06)
|
|
|
|
- allow to configure OPNSense REST API calls timeout per REST API endpoint adding
|
|
`--opnsense-timeout-sec-get-vip-status` and
|
|
`--opnsense-timeout-sec-get-traffic` parameters.
|
|
|
|
### Version 1.0.0 (2023-09-06)
|
|
|
|
- remove `opnsense_main_ha_state` and `opnsense_backup_ha_state`
|
|
metrics marked as deprecated on version 0.5.0 and replace
|
|
by `opnsense_server_ha_state` and `role` label
|
|
- allow empty string interfaces to **not** call diagnostic
|
|
traffic REST API
|
|
|
|
### Version 0.5.1 (2023-09-04)
|
|
|
|
- FIX `opnsense_server_ha_state` calls were not
|
|
implemented
|
|
|
|
### Version 0.5.0 (2023-09-04)
|
|
|
|
- add role label in metrics
|
|
- all to configure supervised interfaces using `--opnsense-interfaces`
|
|
- replace `active_server_bytes_received` and
|
|
`active_server_bytes_transmitted` by
|
|
`opnsense_active_server_traffic_rate`
|
|
- add `opnsense_server_ha_state` and mark `opnsense_main_ha_state`
|
|
and `opnsense_backup_ha_state` as deprecated.
|
|
|
|
### Version 0.4.0 (2023-09-02)
|
|
|
|
- Higher timeout while getting WAN traffic info
|
|
|
|
### Version 0.3.0 (2023-09-02)
|
|
|
|
- Use proper method to compute WAN traffic
|
|
|
|
### Version 0.2.0 (2023-09-01)
|
|
|
|
- Setup automatic release from gitlab while pushing new tag
|
|
|
|
### Version 0.1.0 (2023-09-01)
|
|
|
|
- Initial version
|