Jean-Gabriel Gill-Couture
6c9472212c
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
120 lines
3.1 KiB
Markdown
120 lines
3.1 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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
|
|
```
|