Skip to content

Add strongSwan / IPsec application#19857

Closed
lirone wants to merge 1 commit into
librenms:masterfrom
lirone:app-strongswan
Closed

Add strongSwan / IPsec application#19857
lirone wants to merge 1 commit into
librenms:masterfrom
lirone:app-strongswan

Conversation

@lirone

@lirone lirone commented Jun 10, 2026

Copy link
Copy Markdown
Contributor

Add strongSwan / IPsec application (per-connection traffic, state, rekeys)

What this does

Adds a new strongswan application that monitors per-connection IPsec metrics from any
strongSwan host (OPNsense/pfSense, Linux strongSwan, …) via an SNMP JSON-extend script.

Today LibreNMS can only graph IPsec tunnels for Cisco devices (CISCO-IPSEC-FLOW-MONITOR-MIB).
strongSwan exposes nothing comparable over SNMP, so there is no way to see IPsec throughput on
the very common OPNsense/strongSwan firewalls. This app fills that gap.

For every IPsec connection it graphs:

  • Inbound / outbound throughput (bits/s) and packets/s
  • Tunnel state (1 = an IKE SA is established, 0 = down)
  • Installed child SAs (count)
  • Re-establishment rate — surfaces flapping tunnels

Plus daemon-wide counters from swanctl --counters: IKE/child rekeys/s and error rates
(invalid, invalid SPI).

Each connection is labelled with its human description (and peer IP) instead of the raw
strongSwan connection name, e.g. "Example Partner A (192.0.2.10)".

How it works

  • A companion strongswan extend script (submitted separately to
    librenms-agent) is the agent-side
    JSON SNMP extend:
    it parses swanctl --list-sas and swanctl --counters and aggregates per connection.
  • Works with both OPNsense IPsec models: the legacy "Tunnel Settings" (con<N> connection
    names, <phase1> in config.xml) and the new "Connections" model (UUID connection names,
    //OPNsense/Swanctl/Connections/Connection). On plain Linux strongSwan the connection name is
    used as-is. The poller stores a name→label map so graphs/UI show meaningful names.
  • The per-SA byte/packet counters in strongSwan reset on every rekey. The extend keeps a
    small state file and emits monotonic cumulative counters, so DERIVE datasets produce clean,
    gap-free rates instead of spikes at each rekey.

Files

includes/polling/applications/strongswan.inc.php             # poller
includes/html/graphs/application/strongswan-common.inc.php   # multi-instance graph helper
includes/html/graphs/application/strongswan_*.inc.php        # per-metric + global graphs
includes/html/pages/device/apps/strongswan.inc.php           # device "Apps" page (tunnel selector)
doc/Extensions/Applications/Strongswan.md                    # documentation
tests/snmpsim/linux_strongswan.snmprec                       # test fixture
tests/data/linux_strongswan.json                             # expected discovery/poll output

The agent-side extend script is a companion PR to librenms/librenms-agent (snmp/strongswan).
The app is auto-discovered through the standard JSON-extend mechanism (the snmpd extend must be
named strongswan, matching the poller file name).

Testing

  • Test fixture (linux_strongswan) covers a legacy con<N> tunnel with traffic, a new-model
    UUID tunnel, a down tunnel, and global counters. Generated with
    ./scripts/save-test-data.php --os linux --variant strongswan --modules applications.
  • Verified in production on OPNsense 21.1, 22.7 and 23.7 firewalls (legacy and new
    "Connections" models), polled by LibreNMS 26.5.

Notes / scope

  • Graphs convert bytes→bits with $multiplier = 8.
  • strongSwan exposes rekey/error counters globally (graphed as global), not per-connection;
    the per-tunnel reestablishes metric (IKE SA id change between polls) is the per-connection
    flapping signal. True per-connection DPD counters would require a VICI event listener (a daemon),
    which is out of scope for an SNMP extend.
  • Have you followed our code guidelines?
  • Have you added/updated docs (doc/Extensions/Applications/Strongswan.md)?
  • Have you added tests where applicable (tests/snmpsim + tests/data)?

@CLAassistant

CLAassistant commented Jun 10, 2026

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

New 'strongswan' application: per-connection IPsec metrics (in/out throughput,
state, installed child SAs, re-establishment rate) plus global rekey/error
counters, collected from strongSwan via a JSON SNMP extend.

Works with OPNsense legacy 'Tunnel Settings' (con<N>) and the new 'Connections'
model (UUID names) as well as plain Linux strongSwan. Per-SA counters reset on
rekey, so the extend emits monotonic cumulative counters for clean DERIVE rates.

Includes poller, multi-instance graphs, device app page, docs and test data.
The agent-side extend script is a companion PR to librenms/librenms-agent.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@lirone lirone closed this Jun 10, 2026
@Jvonderburg

Copy link
Copy Markdown

hey @lirone , why did u close the PR?

@lirone

lirone commented Jul 1, 2026

Copy link
Copy Markdown
Contributor Author

I didn't mean to close it — it was resubmitted right after as #19858, which is the live one (companion agent script: librenms/librenms-agent#622).

@Jvonderburg

Copy link
Copy Markdown

thanks for the info. Good idea by the way :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants