Files

Run Check Script / check (pull_request) Successful in 2m6s

Details

fix(opnsense): lowercase match arms in generated From<&str>

Two regressions from fc16e9f that ./build/check.sh catches:

1. `opnsense-api`'s `test_haproxy_deser` example references
   `resp.haproxy` on the response wrapper. The regen auto-derived the
   field name as `op_nsenseha_proxy` from the struct name. Need to pass
   `--api-key haproxy` to keep the wrapper key stable.

2. For enums whose wire values aren't all-lowercase (e.g. `"SSLv3"`,
   `"CONNECT"`), the emitted `From<&str>` matched `s.to_lowercase()`
   against the original-case wire value, which clippy flags as
   unreachable ("match arm has differing case"). Lowercase the wire
   value in the emitted match arm so case-insensitive matching actually
   works; serialization still emits the original-case wire value
   because the serde module is unaffected.

Regenerated `haproxy.rs` via
`cargo run -p opnsense-codegen -- generate --xml ... --module-name haproxy --api-key haproxy`.

`./build/check.sh` now passes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-22 12:52:26 -04:00

examples

chore: cargo fmt across workspace

2026-03-25 23:20:57 -04:00

src

fix(opnsense): lowercase match arms in generated From<&str>

2026-04-22 12:52:26 -04:00

tests

chore: cargo fmt across workspace

2026-03-25 23:20:57 -04:00

Cargo.toml

refactor: move IaC enums to harmony_types, translate in opnsense-api

2026-03-26 10:11:53 -04:00

README.md

docs(opnsense-api): add README with example usage

2026-03-24 19:07:32 -04:00

test_dnsmasq_codegen.sh

misc: Add test dnsmasq end to end codegen

2026-03-24 15:29:01 -04:00

README.md

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