OPNsense Controller¶

The OPNsense Controller is a CLI tool suite for managing firewalls, VLANs, DHCP, DNS, and Caddy reverse proxy configurations.

Core Capabilities¶

The package provides five command-line utilities:

Getting Started¶

Installation¶

Installation requires Nix and an OPNsense instance with API access enabled.

API Credentials¶

Create credentials in the OPNsense web interface:

1. Go to System > Access > Users
2. Generate an API key

The controller expects credentials in ~/.opnsense-credentials.txt:

<api-token>
<api-secret>

The system automatically detects API ports by probing ports 443 and 8443 sequentially, supporting various OPNsense deployment configurations.

Configuration¶

Credential File (Recommended)¶

cat > ~/.opnsense-credentials.txt <<EOF
your-api-token
your-api-secret
EOF
chmod 600 ~/.opnsense-credentials.txt

Environment Variables¶

Environment variables allow runtime customization:

• OPNSENSE_TOKEN - API token
• OPNSENSE_SECRET - API secret
• Hostname, port, SSL verification, timeout values, and retry counts

CLI Tools¶

Main Controller¶

The primary tool supports three operational modes:

• VLAN management
• DHCP configuration
• Firewall rules

The --execute flag enables actual changes; dry-run mode is default.

Firewall Manager¶

The dedicated firewall CLI enables rule creation with comprehensive filtering options:

• Source/destination networks
• Ports and protocols
• Actions (allow, block, reject)
• Logging and priority sequencing
• Batch operations with deferred application

Zone Manager¶

Automates configuration from zones.json definitions:

• Manages VLANs
• Configures DHCP ranges
• Creates firewall rules according to zone specifications
• Supports selective configuration of individual components
• Provides programmatic access for scripting

DNS Manager¶

The DNS Manager is a dedicated command-line tool for managing DNS host entries in OPNsense's Dnsmasq service.

Installation¶

The DNS manager is installed as part of the OPNsense controller Nix package:

# Build the OPNsense controller package
cd ~/TAPPaaS/src/foundation/tappaas-cicd/opnsense-controller
nix-build -A default default.nix

# The dns-manager command will be available in the result
./result/bin/dns-manager --help

Commands¶

Usage Examples¶

Add a DNS Entry:

dns-manager --no-ssl-verify add backup mgmt.internal 10.0.0.12

With custom description:

dns-manager --no-ssl-verify add backup mgmt.internal 10.0.0.12 --description "PBS Backup Server"

Delete a DNS Entry:

dns-manager --no-ssl-verify delete backup mgmt.internal

List DNS Entries:

dns-manager --no-ssl-verify list

Dry-Run Mode:

dns-manager --no-ssl-verify --check-mode add backup mgmt.internal 10.0.0.12

Options¶

Authentication¶

The DNS manager uses the same credentials as other OPNsense controller tools:

1. Credential file (recommended):

   cat > ~/.opnsense-credentials.txt <<EOF
   your-api-token
   your-api-secret
   EOF
   chmod 600 ~/.opnsense-credentials.txt
   

2. Environment variables:

   export OPNSENSE_TOKEN="your-api-token"
   export OPNSENSE_SECRET="your-api-secret"
   

3. Command-line option:

   dns-manager --credential-file /path/to/creds.txt ...
   

Integration with TAPPaaS¶

The DNS manager is automatically used by module configuration scripts:

# Example from PBS backup configuration
dns-manager --no-ssl-verify add backup mgmt.internal ${PBS_NODE_IP} --description "PBS Backup Server"

Technical Details¶

• Uses OPNsense's Dnsmasq DHCP/DNS service
• Creates static host entries that work for both DNS resolution and DHCP reservations
• Manages entries via the OPNsense API
• Implemented as a Python module in opnsense_controller.dns_manager_cli

Caddy Manager¶

The Caddy Manager provides a dedicated CLI for managing Caddy reverse proxy domains and handlers on OPNsense. It is used by the firewall:proxy service scripts to automate proxy setup for TAPPaaS modules.

Commands¶

Usage Examples¶

List all reverse proxy domains and handlers:

caddy-manager list --no-ssl-verify

Add a domain (Caddy will obtain a TLS certificate for it):

caddy-manager add-domain app.test.tappaas.org --description "TAPPaaS: myapp" --no-ssl-verify

Add a handler that routes traffic to an upstream VM:

caddy-manager add-handler app.test.tappaas.org \
    --upstream myapp.srv.internal \
    --port 8080 \
    --description "TAPPaaS: myapp" \
    --no-ssl-verify

Delete a handler by description:

caddy-manager delete-handler --description "TAPPaaS: myapp" --no-ssl-verify

Delete a domain:

caddy-manager delete-domain app.test.tappaas.org --no-ssl-verify

Reconfigure Caddy (regenerate Caddyfile and reload):

caddy-manager reconfigure --no-ssl-verify

Dry-run mode:

caddy-manager add-domain app.test.tappaas.org --check-mode --no-ssl-verify

Options¶

add-domain Options¶

add-handler Options¶

delete-handler Options¶

Integration with TAPPaaS¶

The Caddy manager is automatically used by the firewall:proxy service scripts:

# Typical module proxy setup (what install-service.sh does)
caddy-manager add-domain vaultwarden.test.tappaas.org \
    --description "TAPPaaS: vaultwarden" --no-ssl-verify
caddy-manager add-handler vaultwarden.test.tappaas.org \
    --upstream vaultwarden.srv.internal \
    --port 80 \
    --description "TAPPaaS: vaultwarden" --no-ssl-verify
caddy-manager reconfigure --no-ssl-verify

# Cleanup (what delete-service.sh does)
caddy-manager delete-handler --description "TAPPaaS: vaultwarden" --no-ssl-verify
caddy-manager delete-domain vaultwarden.test.tappaas.org --no-ssl-verify
caddy-manager reconfigure --no-ssl-verify

Technical Details¶

• Manages Caddy reverse proxy through the OPNsense Caddy plugin API
• Handles automatic TLS certificate provisioning via ACME
• Creates domain entries and upstream handlers
• Implemented as a Python module in opnsense_controller.caddy_cli

Programmatic Interface¶

Python developers can import manager classes directly for integration into automation workflows:

• Connection testing
• Specification retrieval
• Batch operations
• Rule enumeration and creation
• Toggle functionality

DHCP Manager¶

Handles both dynamic ranges and static reservations with:

• Lease time configuration
• Domain configuration

VLAN Management¶

Supports interface assignment through an optional custom PHP extension.