opnsense-py

A synchronous Python client library and CLI for the OPNsense REST API.

Installation

# Library only
pip install opnsense-py

# Library + CLI (opn / opnsense commands)
pip install opnsense-py[cli]

Requires Python 3.12+.

CLI quick start

# HTTPS with self-signed certificate (most common)
opn --host 192.168.1.1 --no-verify-ssl --api-key KEY --api-secret SECRET system status

# Plain HTTP
opn --host 192.168.1.1 --no-tls --api-key KEY --api-secret SECRET system status

Configuration file

Store connection settings in ~/.config/opnsense-py/config.toml to avoid repeating flags:

[default]
host = "192.168.1.1"
api_key = "your-key"
api_secret = "your-secret"
verify_ssl = "false"

[prod]
host = "firewall.example.com"
api_key = "prod-key"
api_secret = "prod-secret"

Switch profiles with --profile prod or OPNSENSE_PROFILE=prod.

Environment variables

Output formats

opn -o table firewall alias list   # default: human-readable table
opn -o json  firewall alias list   # JSON (pipe-friendly)
opn -o plain firewall alias list   # one value/UUID per line

Available commands

Run any command with --help for full usage.

Library usage

from opnsense_py import OPNsenseClient

with OPNsenseClient(
    host="192.168.1.1",
    api_key="your-key",
    api_secret="your-secret",
    verify_ssl=False,
) as client:
    # List firewall aliases
    aliases = client.firewall.search_aliases()
    for alias in aliases.rows:
        print(alias.name, alias.type)

    # Add a cron job
    from opnsense_py.models.cron import CronJob
    result = client.cron.add_job(CronJob(
        command="firmware",
        description="Nightly firmware check",
        minutes="0", hours="2",
        days="*", months="*", weekdays="*",
    ))
    print(result.uuid)

Architecture

The client is structured in layers:

1. OPNsenseClient — top-level entry point; manages an httpx.Client with Basic Auth. All API modules are lazy-loaded as @cached_property attributes.
2. BaseModule — base class providing generic CRUD helpers (_search, _get_item, _add_item, etc.) and service control helpers.
3. Module classes (modules/core/, modules/plugins/) — one per OPNsense subsystem, returning typed Pydantic models.
4. Pydantic models (models/) — typed representations of OPNsense entities; all extend OPNsenseModel with extra="allow" so unrecognised fields are preserved.
5. Exceptions — OPNsenseError → OPNsenseHTTPError → OPNsenseAuthError / OPNsenseNotFoundError; plus OPNsenseValidationError for HTTP 200 responses with validation errors.

Development

# Install with dev dependencies
poetry install --extras cli

# Run tests
poetry run pytest

# Lint
poetry run ruff check .

# Type check
poetry run mypy opnsense_py/

# Run a single test
poetry run pytest tests/unit/modules/core/test_cron.py::test_search_jobs

Integration tests require a live OPNsense instance and are skipped by default:

OPNSENSE_HOST=192.168.1.1 OPNSENSE_API_KEY=... OPNSENSE_API_SECRET=... \
  poetry run pytest -m integration