aiopnsense

aiopnsense is an async Python client library for OPNsense.

What this library does

aiopnsense wraps supported OPNsense REST endpoints behind a single async client, OPNsenseClient. It is designed for applications that need to query router state or trigger supported OPNsense actions without manually building HTTP requests.

The client currently includes helpers for:

• system information, notices, certificates, CARP, Wake-on-LAN, reboot, and interface reloads
• firmware version checks, update status, and upgrade actions
• interface, gateway, CPU, memory, filesystem, and temperature telemetry
• diagnostics traffic snapshots and live interface traffic stream samples
• DHCP lease and ARP table access
• firewall rules, NAT rules, alias toggling, and state killing
• service status lookup and service start/stop/restart operations
• SMART device listing and per-device SMART detail queries
• Unbound blocklist management
• OpenVPN and WireGuard status plus VPN instance toggling
• vnStat metrics, captive portal vouchers, and speed test data

Requirements

• Requires OPNsense Firmware >= 25.1

• Recommended OPNsense Firmware >= 26.1.1

  • For firmware < 26.1.1, the Firewall and NAT methods will return empty data.

Documentation

• Read the Docs: https://aiopnsense.readthedocs.io

Live test scripts

The scripts/ directory includes live diagnostic helpers for maintainers:

• aiopnsense_dump.py runs supported aiopnsense client endpoints and prints the raw data returned by the library.
• opnsense_api_call.py calls an arbitrary OPNsense API endpoint with a specified method and optional POST payload.

Both scripts read credentials from scripts/aiopnsense.env by default. Copy scripts/aiopnsense.env.example to create your local env file; it is ignored by git. Full CLI reference is in the Read the Docs script documentation.

Origin and Purpose

aiopnsense was extracted from the hass-opnsense integration. It is primarily used as an external dependency by hass-opnsense and Home Assistant for its OPNsense Integration.

Changelog

v1.1.9 (2026-09-04)

Full Changelog

Bug Fixes

• Fix empty Dnsmasq lease interface discovery #108 (Snuffy2)

Code Quality

• Add OpenVPN toggle response logging #113 (Snuffy2)
• Modernize CI and release automation with uv #106 (Snuffy2)

Maintenance

• Fix protected release promotion statuses #114 (Snuffy2)
• Migrate release workflow to published releases #112 (Snuffy2)
• Fix GitHub release repository detection #110 (Snuffy2)
• Update pytest coverage workflows for action v4 #109 (Snuffy2)
• Skip coverage comments for prek autoupdate bot #104 (Snuffy2)
• Add prek-autoupdate bot auto-merge workflow #102 (Snuffy2)

Other Changes

• test: optimize and de-brittle test suite #100 (Snuffy2)

v1.1.8 (2026-08-30)

Full Changelog

v1.1.7 (2026-08-08)

Full Changelog

Documentation

• Add pydoclint documentation checks #95 (Snuffy2)

Code Quality

• Reuse parsed vnStat period labels #99 (Snuffy2)
• Optimize and harden DHCP lease collection #98 (Snuffy2)
• Defer caught-error log rendering #97 (Snuffy2)
• Avoid expensive caller stack inspection #96 (Snuffy2)

v1.1.6 (2026-08-01)

Full Changelog

Bug Fixes

• Cache endpoint permission failures #91 (Snuffy2)

Maintenance

• Update GitHub maintenance workflows #90 (Snuffy2)
• Update prek_autoupdate.yml #86 (Snuffy2)

v1.1.5 (2026-07-21)

Full Changelog

Bug Fixes

• Add timezone to Speedtest dates #83 (Snuffy2)

v1.1.4 (2026-07-20)

Full Changelog

Enhancements

• Support alternate Speedtest plugins #80 (Snuffy2)

Bug Fixes

• Parse raw NUT UPS status responses #79 (Snuffy2)

v1.1.3 (2026-07-16)

Full Changelog

Bug Fixes

• Switch firewall rule retrieval to CSV downloads #77 (Snuffy2)

v1.1.2 (2026-07-15)

Full Changelog

Enhancements

• Raise public OPNsense exceptions consistently #76 (Snuffy2)

v1.1.1 (2026-07-12)

Full Changelog

Enhancements

• Allow validation without device identity #75 (Snuffy2)

Documentation

• Update agent and live script docs #73 (Snuffy2)

Code Quality

• Trim audit cleanup boilerplate #70 (Snuffy2)

Maintenance

• Run prek cleanup daily #72 (Snuffy2)
• Use reusable prek autoupdate workflow #71 (Snuffy2)

v1.1.0 (2026-07-03)

Full Changelog

New Features

• Add Kea DHCPv6 lease support #64 (Snuffy2)
• Add NUT UPS status endpoint #63 (Snuffy2)
• Add live OPNsense test scripts #62 (Snuffy2)
• Add diagnostics traffic stream support #61 (Snuffy2)

Enhancements

• Handle OPNsense 26.1.11 API changes #69 (Snuffy2)
• Normalize OPNsense NAT and DHCP payloads #68 (Snuffy2)

Code Quality

• Update agent instructions #66 (Snuffy2)

Maintenance

• Add issue templates #67 (Snuffy2)

v1.0.15 (2026-06-28)

Full Changelog

Bug Fixes

• Exclude automatic firewall rules #59 (Snuffy2)

v1.0.14 (2026-06-21)

Full Changelog

Enhancements

• Raise missing device unique ID during validation #56 (Snuffy2)

Bug Fixes

• Preserve deprecated set_use_snake_case compatibility #55 (Snuffy2)

v1.0.13 (2026-06-21)

Full Changelog

Bug Fixes

• Privatize endpoint probe helpers #54 (Snuffy2)

v1.0.12 (2026-06-20)

Full Changelog

Bug Fixes

• Filter invalid SMART devices #52 (Snuffy2)

Code Quality

• Move OPNsense endpoints to module constants #53 (Snuffy2)

v1.0.11 (2026-06-20)

Full Changelog

New Features

• Add SMART device API support #51 (Snuffy2)
• Add CARP maintenance mode toggle #47 (Snuffy2)

Documentation

• Add Documentation link to pyproject #44 (Snuffy2)

Code Quality

• Refactor method-aware endpoint availability #48 (Snuffy2)

Maintenance

• prek autoupdate #45 (Snuffy2)

v1.0.10 (2026-05-29)

Full Changelog

Enhancements

• Improve generated API docstrings #41 (Snuffy2)

Documentation

• Support PEP 702 deprecations in docs #43 (Snuffy2)
• Update README.md #42 (Snuffy2)

v1.0.9 (2026-05-29)

Full Changelog

Bug Fixes

• Map validation endpoint probe errors #39 (Snuffy2)
• Fix for kea lease state change in OPNsense 26.1.8 #38 (Snuffy2)
• Raise SSL errors during validate call #37 (HarlemSquirrel)

Code Quality

• Clean up code noise #40 (Snuffy2)

v1.0.8 (2026-04-06)

Full Changelog

Maintenance

• Merge changelog and release actions #35 (Snuffy2)

v1.0.7 (2026-04-05)

Full Changelog

Bug Fixes

• Fix conf.py #32 (Snuffy2)

Documentation

• Refine changelog #33 (Snuffy2)
• Further documentation refinement #31 (Snuffy2)

v1.0.6 (2026-04-05)

Full Changelog

Enhancements

• Add back legacy unbound blocklist support #26 (Snuffy2)
• Add back legacy camelCase support #25 (Snuffy2)
• Add validate method #23 (Snuffy2)
• Add endpoint checks to prevent errors #22 (Snuffy2)
• Firewall endpoints to GET and don't fail if unavailable #21 (Snuffy2)

Bug Fixes

• Fix showing docstrings in documentation #29 (Snuffy2)

Documentation

• Clarify opts documentation #30 (Snuffy2)
• Introduce GitHub Actions changelog workflow and reorganize docs #28 (Snuffy2)
• Add documentation #27 (Snuffy2)

Code Quality

• Finish rename to aiopnsense #24 (Snuffy2)
• Change to prek.toml #20 (Snuffy2)

v1.0.5 (2026-04-03)

Full Changelog

Enhancements

• In OPNsenseClient, change from initial to throw_errors #19 (Snuffy2)

v1.0.4 (2026-03-29)

Full Changelog

Enhancements

• Add CARP status summary and improve VIP interface matching #16 (Snuffy2)

Bug Fixes

• Further CARP refinement #17 (Snuffy2)

Maintenance

• Update release Github Action #18 (Snuffy2)

v1.0.3 (2026-03-26)

Full Changelog

Bug Fixes

• Handle 26.1.5+ changes in dnsmasq leases API #14 (Snuffy2)

Code Quality

• Turn down more debug logging #15 (Snuffy2)

v1.0.2 (2026-03-23)

Full Changelog

Enhancements

• Expand ambiguous time zone list #12 (Snuffy2)

Code Quality

• Turn down firewall debug logging #11 (Snuffy2)

v1.0.1 (2026-03-23)

Full Changelog

Documentation

• Update Documentation #10 (Snuffy2)

v1.0.0 (2026-03-22)

Full Changelog

v0.0.3 (2026-03-22)

Full Changelog

Enhancements

• Improve pytest coverage and Refactor test infrastructure with reusable HTTP response mocking #8 (Snuffy2)

Bug Fixes

• Fix some endpoints from POST to GET #6 (Snuffy2)
• Fix GitHub release Workflow #4 (Snuffy2)

Documentation

• Standardize docstring formatting across codebase #7 (Snuffy2)

Other Changes

• Handle if DHCP endpoints are unavailable #9 (Snuffy2)
• Remove legacy code #5 (Snuffy2)

v0.0.2 (2026-03-22)

Full Changelog

Other Changes

• Update version in const.py on release #3 (Snuffy2)

v0.0.1 (2026-03-22)

Full Changelog

Other Changes

• Create AGENTS.md #2 (Snuffy2)
• GitHub Workflows and Linting #1 (Snuffy2)

* This Changelog was automatically generated by github_changelog_generator