Aller au contenu
1337skills 1337skills - Aide-mémoires

OPNsense Cheat Sheet

Overview

OPNsense is an open-source, FreeBSD-based firewall and routing platform that provides enterprise-grade network security features through an intuitive web interface. Forked from pfSense in 2015, OPNsense emphasizes security, code quality, and weekly security updates. It includes a stateful packet filter (pf), VPN support (OpenVPN, WireGuard, IPsec), intrusion detection/prevention (Suricata), web proxy (Squid), DNS filtering, traffic shaping, high availability (CARP), and comprehensive logging with Netflow support.

OPNsense’s architecture is built on the HardenedBSD security framework with features like ASLR, SafeStack, and LibreSSL. The platform uses a plugin system for extending functionality, with over 100 available plugins covering everything from HAProxy to Telegraf monitoring. The REST API allows full programmatic control, making it suitable for infrastructure-as-code workflows. OPNsense supports multi-WAN with failover, VLAN trunking, captive portal, and integrates with external authentication via LDAP, RADIUS, and TOTP two-factor authentication.

Installation

System Requirements

Minimum: 64-bit CPU, 2GB RAM, 8GB storage, 2 NICs
Recommended: 4+ cores, 8GB RAM, 120GB SSD, Intel NICs

Installation Steps

# Download ISO from https://opnsense.org/download/
# Boot from USB/DVD
# Follow installer: Install (ZFS recommended)
# Default credentials after install:
#   Web UI: https://192.168.1.1
#   Username: root
#   Password: opnsense

Post-Installation CLI

# Access console menu
0) Logout                       7) Ping host
1) Assign interfaces            8) Shell
2) Set interface IP address     9) pfTop
3) Reset the root password     10) Firewall log
4) Reset to factory defaults   11) Reload all services
5) Power off system            12) Update from console
6) Reboot system               13) Restore config backup

Core Configuration

Interface Assignment

# From console menu (option 1):
# Assign WAN to first NIC (e.g., igb0)
# Assign LAN to second NIC (e.g., igb1)
# Optionally assign OPT interfaces

# Set interface IP (option 2):
# Select LAN
# Set IPv4: 192.168.1.1/24
# Enable DHCP server: 192.168.1.100 - 192.168.1.200

Firewall Rules via API

# API credentials: System > Access > Users > API keys
export OPNSENSE_KEY="your-api-key"
export OPNSENSE_SECRET="your-api-secret"
export OPNSENSE_URL="https://192.168.1.1"

# List firewall rules
curl -k -u "$OPNSENSE_KEY:$OPNSENSE_SECRET" \
  "$OPNSENSE_URL/api/firewall/filter/searchRule"

# Add firewall rule
curl -k -X POST -u "$OPNSENSE_KEY:$OPNSENSE_SECRET" \
  -H "Content-Type: application/json" \
  "$OPNSENSE_URL/api/firewall/filter/addRule" \
  -d '{
    "rule": {
      "enabled": "1",
      "action": "pass",
      "interface": "lan",
      "protocol": "TCP",
      "source_net": "lan",
      "destination_net": "any",
      "destination_port": "443"
    }
  }'

# Apply changes
curl -k -X POST -u "$OPNSENSE_KEY:$OPNSENSE_SECRET" \
  "$OPNSENSE_URL/api/firewall/filter/apply"

VPN Configuration

WireGuard

# Install plugin: System > Firmware > Plugins > os-wireguard

# Generate keys (on client)
wg genkey | tee privatekey | wg pubkey > publickey

# API: Create WireGuard server
curl -k -X POST -u "$OPNSENSE_KEY:$OPNSENSE_SECRET" \
  "$OPNSENSE_URL/api/wireguard/server/addServer" \
  -d '{
    "server": {
      "enabled": "1",
      "name": "wg0",
      "tunneladdress": "10.10.0.1/24",
      "port": "51820"
    }
  }'

OpenVPN (Road Warrior)

# Web UI: VPN > OpenVPN > Servers
# Server Mode: Remote Access (SSL/TLS + User Auth)
# Protocol: UDP on IPv4
# Port: 1194
# TLS Authentication: Enabled
# Tunnel Network: 10.0.8.0/24
# Local Network: 192.168.1.0/24
# DNS Server: 192.168.1.1

IPsec Site-to-Site

# Phase 1:
# Key Exchange: IKEv2
# Authentication: Mutual PSK
# Encryption: AES-256-GCM
# DH Group: 14 (2048-bit)
# Lifetime: 28800

# Phase 2:
# Mode: Tunnel
# Local Network: 192.168.1.0/24
# Remote Network: 192.168.2.0/24
# Encryption: AES-256-GCM
# PFS Group: 14
# Lifetime: 3600

Intrusion Detection (Suricata)

# Enable: Services > Intrusion Detection > Administration
# Download rulesets: ET Open, Abuse.ch, Feodo Tracker

# API: Enable IDS
curl -k -X POST -u "$OPNSENSE_KEY:$OPNSENSE_SECRET" \
  "$OPNSENSE_URL/api/ids/settings/set" \
  -d '{
    "ids": {
      "general": {
        "enabled": "1",
        "ips": "1",
        "interfaces": "wan",
        "homenet": "192.168.0.0/16,10.0.0.0/8"
      }
    }
  }'

# Update rulesets
curl -k -X POST -u "$OPNSENSE_KEY:$OPNSENSE_SECRET" \
  "$OPNSENSE_URL/api/ids/service/updateRules"

# View alerts
curl -k -u "$OPNSENSE_KEY:$OPNSENSE_SECRET" \
  "$OPNSENSE_URL/api/ids/service/queryAlerts"

DNS and DHCP

Unbound DNS

# Services > Unbound DNS > General
# Listen Port: 53
# Network Interfaces: LAN
# DNSSEC: Enabled
# DNS over TLS: Enabled (port 853)

# Domain Overrides (conditional forwarding):
# Domain: corp.local → 10.0.0.53
# Domain: 10.in-addr.arpa → 10.0.0.53

DHCP Server

# Services > DHCPv4 > LAN
# Range: 192.168.1.100 - 192.168.1.200
# DNS Servers: 192.168.1.1
# Gateway: 192.168.1.1
# Domain Name: home.local
# Default Lease Time: 86400
# Static Mappings: MAC → IP for servers

High Availability (CARP)

# System > High Availability > Settings
# Synchronize Config to IP: 10.0.0.2 (backup node)
# Remote System Username: root
# Remote System Password: <password>
# Synchronize: Firewall Rules, NAT, DHCP, DNS, VPN

# Virtual IPs (Firewall > Virtual IPs):
# Type: CARP
# Interface: WAN
# Address: 203.0.113.1/24
# VHID Group: 1
# Advskew: 0 (master) / 100 (backup)
# Password: carppass

Advanced Usage

Traffic Shaping

# Firewall > Shaper > Pipes
# Create pipe: Download (100Mbps)
# Create pipe: Upload (50Mbps)

# Firewall > Shaper > Rules
# Source: any → Destination: LAN net → Pipe: Download
# Source: LAN net → Destination: any → Pipe: Upload

HAProxy (Load Balancer Plugin)

# Install: os-haproxy plugin

# Backend servers:
# Server 1: 192.168.1.10:8080
# Server 2: 192.168.1.11:8080

# Frontend:
# Listen: 0.0.0.0:443
# SSL Offloading: enabled
# Default Backend: web-servers
# Health Check: HTTP GET /health

Backup and Restore

# API: Download config backup
curl -k -u "$OPNSENSE_KEY:$OPNSENSE_SECRET" \
  "$OPNSENSE_URL/api/core/backup/download/this" \
  -o opnsense-backup.xml

# Restore via Web UI: System > Configuration > Backups

Troubleshooting

IssueSolution
Locked out of web UIReset via console (option 4) or set interface IP (option 2)
VPN clients no internetAdd NAT rule for VPN subnet; enable gateway on VPN interface
IDS blocking legitimate trafficReview alerts in IDS; add SID to suppression list
CARP failover not workingVerify VHID and password match; check CARP traffic (protocol 112)
DNS not resolvingCheck Unbound is running; verify listen interfaces; check upstream DNS
Slow throughputDisable hardware offloading if using VMs; check CPU during traffic
Package install failsUpdate firmware first; check DNS resolution from OPNsense