Live Test Scripts

The repository includes live diagnostic scripts for maintainers who need to inspect aiopnsense and raw OPNsense API responses against a real firewall. They read credentials from scripts/aiopnsense.env by default. Copy scripts/aiopnsense.env.example to that path and fill in your local OPNsense API URL, key, and secret before running them.

Do not commit scripts/aiopnsense.env or other files containing live API credentials.

aiopnsense endpoint dump

scripts/aiopnsense_dump.py calls supported aiopnsense client endpoints and prints the raw data returned by the library. Use --list to show the available endpoint names, or omit --endpoint for an interactive menu. The interface traffic stream endpoint runs for the configured duration and defaults to 30 seconds.

scripts/aiopnsense_dump.py - CLI interface

Dump live OPNsense endpoint JSON payloads.

scripts/aiopnsense_dump.py [-h] [--env-file ENV_FILE] [--endpoint ENDPOINT] [--list]
                           [--output OUTPUT] [--stream-seconds STREAM_SECONDS]

aiopnsense_dump.py options

  • -h, --help - show this help message and exit

  • --env-file ENV_FILE - Path to the env file with live credentials. (default: scripts/aiopnsense.env)

  • --endpoint ENDPOINT - Endpoint to dump. Available endpoints: arp_table, carp, certificates, device_unique_id, dhcp_leases, firewall, firmware_update_info, gateways, host_firmware_version, interface_traffic, interface_traffic_stream, interfaces, notices, nut_ups_status, openvpn, services, smart, speedtest, system_info, telemetry, unbound_blocklist, upgrade_status, vnstat, wireguard.

  • --list - Print all endpoint metadata as JSON and exit.

  • --output OUTPUT - Optional path to save output JSON.

  • --stream-seconds STREAM_SECONDS - Streaming duration in seconds for interface traffic stream. (default: 30.0)

Raw OPNsense API call

scripts/opnsense_api_call.py calls an arbitrary OPNsense API endpoint and prints response metadata plus the JSON or text body returned by OPNsense. Specify the endpoint, HTTP method, and optional POST payload on the command line.

scripts/opnsense_api_call.py - CLI interface

Call a raw OPNsense API endpoint.

scripts/opnsense_api_call.py [-h] [--env-file ENV_FILE] --endpoint ENDPOINT
                             --method {get,post} [--payload PAYLOAD]
                             [--payload-file PAYLOAD_FILE] [--output OUTPUT]

opnsense_api_call.py options

  • -h, --help - show this help message and exit

  • --env-file ENV_FILE - Path to the env file with live credentials. (default: scripts/aiopnsense.env)

  • --endpoint ENDPOINT - Target endpoint path, with or without a leading slash.

  • --method METHOD - HTTP method.

  • --payload PAYLOAD - Inline JSON object for POST requests.

  • --payload-file PAYLOAD_FILE - Path to a JSON object payload file for POST requests.

  • --output OUTPUT - Optional path to save output JSON.