opnsense-api

Typed Rust client for the OPNsense REST API. Generated model types cover all first-class OPNsense modules.

Setup

All examples require API credentials. Create an API key in OPNsense under System > Access > Users > API Keys, then export:

export OPNSENSE_API_KEY=your_key
export OPNSENSE_API_SECRET=your_secret
export OPNSENSE_BASE_URL=https://your-firewall/api

Or source a local env file (not committed):

source env.sh

TLS verification is skipped by default in examples (self-signed certs).

Examples

Module settings (read)

Fetch and display the full settings for each supported module:

cargo run --example list_dnsmasq
cargo run --example list_haproxy
cargo run --example list_caddy
cargo run --example list_vlan
cargo run --example list_lagg
cargo run --example list_wireguard
cargo run --example list_firewall_filter

Raw API exploration

Fetch any endpoint as raw JSON — useful for debugging and discovering response shapes:

cargo run --example raw_get -- <module> <controller> <command>

# Examples:
cargo run --example raw_get -- interfaces vlan_settings get
cargo run --example raw_get -- haproxy settings get
cargo run --example raw_get -- core firmware status

Package management

# Check if a package is installed
cargo run --example check_package -- os-haproxy

# Install a package (async, returns immediately)
cargo run --example install_package -- os-haproxy os-caddy

# Install and wait for completion
cargo run --example install_and_wait -- os-haproxy

# Install with full log output
cargo run --example install_verbose -- os-haproxy

Firmware management

# Show firmware/version info
cargo run --example firmware_info

# Check for available updates and list package status
cargo run --example firmware_check

# Trigger firmware upgrade and monitor progress
cargo run --example firmware_upgrade

# Reboot and wait for the firewall to come back
cargo run --example reboot

Other

# List installed packages
cargo run --example list_packages

# Trigger firmware update (low-level, prefer firmware_upgrade)
cargo run --example firmware_update

Generated modules

Types are generated by opnsense-codegen from OPNsense XML model files:

Module	Source XML	API prefix
`dnsmasq`	`Dnsmasq/Dnsmasq.xml`	`/api/dnsmasq/`
`haproxy`	`HAProxy/HAProxy.xml`	`/api/haproxy/`
`caddy`	`Caddy/Caddy.xml`	`/api/caddy/`
`firewall_filter`	`Firewall/Filter.xml`	`/api/firewall/`
`vlan`	`Interfaces/Vlan.xml`	`/api/interfaces/`
`lagg`	`Interfaces/Lagg.xml`	`/api/interfaces/`
`wireguard_general`	`Wireguard/General.xml`	`/api/wireguard/`
`wireguard_client`	`Wireguard/Client.xml`	`/api/wireguard/`
`wireguard_server`	`Wireguard/Server.xml`	`/api/wireguard/`

Regenerate with:

cd ../opnsense-codegen
cargo run -- generate \
    --xml vendor/core/src/opnsense/mvc/app/models/OPNsense/Dnsmasq/Dnsmasq.xml \
    --output-dir ../opnsense-api/src/generated \
    --module-name dnsmasq \
    --api-key dnsmasq