opnsense-prom-exporter/README.md

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

Enums

• opnsense_main_ha_state: OPNSense HA state of the MAIN server
• opnsense_backup_ha_state: OPNSense HA state of the BACKUP server

Gauges

• opnsense_active_server_bytes_received: Active OPNSense server bytes received on WAN interface
• opnsense_active_server_bytes_transmitted: Active OPNSense server bytes transmitted on WAN interface

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-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-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

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

Roadmap

• merge opnsense_active_server_bytes_received and opnsense_active_server_bytes_transmitted metrics adding labels to distinguish rates transmitted and rate received
• allow to configure interfaces to get traffic rates for lan,wan and/or other names
• refactor server in a class to avoid transmitted params over methods
• allow to change the listening port (today it force using 8000)
• allow to configure timeouts using environemnt variables
• improves logging to get a debug mode to understand errors based on unexpected payloads

Changelog

Version 0.0.5 (UNRELEASED)

• add role label in metrics

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