OPNsense Admin

Complete OPNsense firewall administration via API and SSH. Automate backups, monitor security, manage services, and troubleshoot network issues.

Features

🔥 Firewall Management - Rules, NAT, aliases, and diagnostics
🛡️ IDS/IPS (Suricata) - Monitor and manage intrusion detection/prevention
🌐 DNS (Unbound) - DNS resolver, blocklists, forwarding, DNS over TLS
📊 Monitoring - Service status, traffic analysis, system health
💾 Automated Backups - Scheduled configuration backups with retention
🔧 Service Control - Start/stop/restart services via SSH
🔌 API Integration - RESTful API wrapper for automation

Installation

Prerequisites

OPNsense 26.1 or later
API key with appropriate permissions
SSH access (optional, for service management)

Quick Setup

Generate API credentials in OPNsense:
```
System → Access → Users → API
```

Configure credentials (choose one method):

Option A: Environment variables

export OPNSENSE_HOST="192.168.1.1"
export OPNSENSE_KEY="your_api_key"
export OPNSENSE_SECRET="your_api_secret"

Option B: Credentials file (recommended)

mkdir -p ~/.opnsense
cat > ~/.opnsense/credentials << EOF
OPNSENSE_HOST=192.168.1.1
OPNSENSE_PORT=443
OPNSENSE_KEY=your_api_key
OPNSENSE_SECRET=your_api_secret
EOF
chmod 600 ~/.opnsense/credentials

Usage

API Helper Script

# Check system status
./scripts/opnsense-api.sh status

# Get firmware information
./scripts/opnsense-api.sh firmware-status

# Check Suricata status
./scripts/opnsense-api.sh suricata-status

# Custom API request
./scripts/opnsense-api.sh get /api/core/system/status
./scripts/opnsense-api.sh post /api/core/firmware/update '{"upgrade":true}'

Configuration Backup

# Full backup (with RRD data)
./scripts/backup-config.sh

# Config-only backup (smaller)
./scripts/backup-config.sh --config-only

# Custom directory and retention
./scripts/backup-config.sh --dir /mnt/backups --keep 90

Service Control

# Restart DNS resolver
./scripts/service-control.sh unbound restart

# Check Suricata status
./scripts/service-control.sh suricata status

# Reload DHCP configuration
./scripts/service-control.sh dhcpd reload

# Check all services
./scripts/service-control.sh all status

Configuration Reference

Environment Variables

Variable	Default	Description
`OPNSENSE_HOST`	`192.168.1.1`	OPNsense IP or hostname
`OPNSENSE_PORT`	`443`	HTTPS port
`OPNSENSE_KEY`	-	API key
`OPNSENSE_SECRET`	-	API secret
`SSH_PORT`	`22`	SSH port for service control
`BACKUP_DIR`	`./backups`	Default backup directory
`KEEP_DAYS`	`30`	Backup retention period

Common API Endpoints

Endpoint	Method	Purpose
`/api/core/system/status`	GET	System health
`/api/core/firmware/status`	GET	Firmware info
`/api/ids/service/status`	GET	Suricata status
`/api/unbound/diagnostics/stats`	GET	DNS statistics
`/api/diagnostics/interface/getInterfaceConfig`	GET	Interface config
`/api/diagnostics/firewall/pfstatists`	GET	Firewall stats
`/api/core/backup/backup`	GET	Download backup

Security Best Practices

SSL Certificate Validation - Enabled by default. Use --insecure or OPNSENSE_INSECURE=true ONLY for development or self-signed certificates in internal networks
Restrict API permissions - Create dedicated API users with minimal required permissions
Secure credential storage - Use file permissions (600) and environment variables
Backup before changes - Always backup configuration before making changes
Test IDS rules first - Run Suricata in IDS mode before enabling IPS blocking

SSL/TLS Configuration

By default, all API calls validate SSL certificates. For production deployments with valid certificates, no changes needed.

For development or self-signed certificates:

# Option 1: Command line flag
./scripts/opnsense-api.sh --insecure status

# Option 2: Environment variable
export OPNSENSE_INSECURE=true
./scripts/opnsense-api.sh status

Key Concepts

Firewall Rules

Stateful filtering - Connection tracking enabled by default
Processing order: Floating → Interface Groups → Interface Rules
Actions: Pass (allow), Block (drop silently), Reject (drop with notice)
NAT: Processed BEFORE filter rules

Suricata IDS/IPS

IDS Mode: Detection only (alerts, no blocking)
IPS Mode: Detection + blocking (requires inline setup)
Best Practice: Monitor on LAN interface to see real client IPs
Rules: Emerging Threats, Abuse.ch feeds, app detection

Unbound DNS

Recursive resolver - Queries root servers directly by default
DNSSEC validation - Enabled by default for security
Blocklists - DNS-based ad/tracker blocking via plugin
DNS over TLS - Encrypted upstream queries

Troubleshooting

API Connection Issues

# Test connectivity
curl -k -u "key:secret" https://opnsense/api/core/system/status

# Check API is enabled in OPNsense
# System → Access → Settings → Enable API

SSH Connection Issues

# Test SSH connectivity
ssh -p 22 root@opnsense "echo OK"

# Check SSH is enabled
# System → Administration → Secure Shell

Permission Denied

Verify API key has required permissions
Check user is member of appropriate groups
Ensure API is enabled in System → Access → Settings

Version Compatibility

OPNsense Version	Skill Version	Status
26.1+	1.x	✅ Supported
25.x	1.x	⚠️ May work
24.x	1.x	❌ Not tested

Reference Documentation

API Guide - Complete API authentication guide
Firewall Rules - Rule structure and examples
Suricata IPS - IDS/IPS configuration
Unbound DNS - DNS resolver setup
Quick Reference - Commands and file locations

License

MIT - See LICENSE file for details.

Contributing

Issues and pull requests welcome at the GitHub repository.

Disclaimer: This is an unofficial skill. Not affiliated with Deciso B.V. or the OPNsense project.

opnsense-admin