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