Skip to content

OPNsense Setup Guide

OPNsense VM configuration on Proxmox for the fixed homelab.

Overview

                    [ISP Modem]
                         │
                    ┌────┴────┐
                    │  WAN    │ ← vmbr0 (bridged)
                    │         │
                    │ OPNsense│
                    │   VM    │
                    │         │
                    │  LAN    │ ← vmbr1 (bridged)
                    └────┬────┘
                         │
                [MokerLink Switch]
                         │
            ┌────────────┼────────────┐
            │            │            │
       [Docker VM]    [NAS]       [Devices]

Proxmox VM Setup

1. Create VM

VM Settings

Setting Value

| VM ID | 100 | | Name | opnsense | | OS Type | Other | | ISO | OPNsense-24.x-amd64.iso | | Disk | 20GB (local-lvm) | | CPU | 2 cores | | RAM | 2048 MB | | Network | See below |

2. Network Configuration

Two network interfaces required (both bridged)

Interface Type Purpose

| net0 | Bridge (vmbr0) | WAN - ISP/switch side | | net1 | Bridge (vmbr1) | LAN - internal network |

Bridged Networking

Both NICs use Proxmox bridges (no PCI passthrough needed):

# /etc/network/interfaces on Proxmox

# WAN bridge (OPNsense WAN - public IP via DHCP)
auto vmbr0
iface vmbr0 inet manual
    bridge-ports enp1s0
    bridge-stp off
    bridge-fd 0

# LAN bridge (OPNsense LAN + Docker VM + Proxmox mgmt)
auto vmbr1
iface vmbr1 inet static
    address 192.168.0.237/24
    gateway 192.168.0.1
    bridge-ports enp2s0
    bridge-stp off
    bridge-fd 0

3. VM Hardware Summary

Hardware:
  - Memory: 2048 MB
  - Processors: 2 (host)
  - BIOS: OVMF (UEFI)
  - Disk: 20GB virtio
  - net0: vmbr0 (WAN bridge)
  - net1: vmbr1 (LAN bridge)

OPNsense Installation

1. Boot from ISO

  • Start VM
  • Select "Install (UFS)" from boot menu
  • Choose keyboard layout
  • Select target disk (ada0)
  • Confirm installation

2. Initial Console Setup

After reboot, at console:

*** Welcome to OPNsense ***

WAN (vtnet0/igc0) -> dhcp (from ISP)
LAN (vtnet1)      -> 192.168.0.1/24

Login: root
Password: opnsense

Assign interfaces:

  • WAN: vtnet0 (bridged, vmbr0)
  • LAN: vtnet1 (bridged, vmbr1)

3. Web GUI Access

From a device on LAN:

https://192.168.0.1
Username: root
Password: opnsense

Basic Configuration

1. Change Password

System > Access > Users > root

  • Set strong password

2. General Settings

System > Settings > General

Setting Value

| Hostname | opnsense | | Domain | cronova.local | | Timezone | America/Asuncion | | DNS Servers | 1.1.1.1, 9.9.9.9 |

3. WAN Interface

Interfaces > WAN

Setting Value

| IPv4 Type | DHCP | | Block Private | Enabled | | Block Bogon | Enabled |

4. LAN Interface

Interfaces > LAN

Setting Value

| IPv4 Address | 192.168.0.1/24 | | Description | LAN |

DHCP Server

Services > DHCPv4 > LAN

Setting Value

| Enable | Yes | | Range | 192.168.0.100 - 192.168.0.199 | | DNS Servers | 192.168.0.10 (Pi-hole) | | Gateway | 192.168.0.1 | | Domain | cronova.local |

Static Mappings

Services > DHCPv4 > LAN > DHCP Static Mappings

Device MAC IP

| Docker VM | xx:xx:xx:xx:xx:xx | 192.168.0.10 | | RPi 4 | xx:xx:xx:xx:xx:xx | 192.168.0.11 | | NAS | xx:xx:xx:xx:xx:xx | 192.168.0.12 | | Yamaha RX-V671 | xx:xx:xx:xx:xx:xx | 192.168.0.30 | | Apple TV | xx:xx:xx:xx:xx:xx | 192.168.0.31 | | LG TV | xx:xx:xx:xx:xx:xx | 192.168.0.32 |

VLAN Configuration

See docs/guides/vlan-design.md for detailed VLAN setup.

Create VLANs

Interfaces > Other Types > VLAN

Parent Tag Description

| vtnet0 | 10 | IoT | | vtnet0 | 20 | Guest |

Assign Interfaces

Interfaces > Assignments

Interface Device Description

| LAN | vtnet0 | Management (untagged) | | OPT1 | vtnet0.10 | IoT | | OPT2 | vtnet0.20 | Guest |

Configure VLAN Interfaces

Interfaces > IOT (OPT1)

Setting Value

| Enable | Yes | | IPv4 | 192.168.10.1/24 | | Description | IoT |

Interfaces > GUEST (OPT2)

Setting Value

| Enable | Yes | | IPv4 | 192.168.20.1/24 | | Description | Guest |

Firewall Rules

LAN (Management)

Firewall > Rules > LAN

# Action Source Dest Port Description

| 1 | Pass | LAN net | any | any | Allow all outbound |

IoT VLAN

Firewall > Rules > IOT

# Action Source Dest Port Description

| 1 | Pass | IOT net | 192.168.0.10 | 53 | DNS (Pi-hole) | | 2 | Pass | IOT net | 192.168.0.10 | 123 | NTP | | 3 | Pass | 192.168.10.101-103 | 192.168.0.10 | 5000 | Cameras → Frigate | | 4 | Block | IOT net | RFC1918 | any | Block LAN access | | 5 | Block | IOT net | any | any | Block internet |

Guest VLAN

Firewall > Rules > GUEST

# Action Source Dest Port Description

| 1 | Pass | GUEST net | 192.168.0.10 | 53 | DNS | | 2 | Block | GUEST net | RFC1918 | any | Block LAN | | 3 | Pass | GUEST net | any | 80,443 | HTTP/HTTPS | | 4 | Block | GUEST net | any | any | Block all else |

DNS Resolver (Unbound)

Services > Unbound DNS > General

Setting Value

| Enable | Yes | | Listen Port | 53 | | Network Interfaces | LAN, IOT, GUEST | | DNSSEC | Enabled |

Note: Pi-hole on Docker VM (192.168.0.10) provides ad-blocking. Configure DHCP to use Pi-hole as DNS, with OPNsense Unbound as fallback.

Tailscale Integration

Install Tailscale plugin for mesh access:

System > Firmware > Plugins

  • Install os-tailscale

VPN > Tailscale

  • Enable Tailscale
  • Authenticate with Headscale:
tailscale up --login-server=https://hs.cronova.dev --authkey=<key>

NUT Integration (UPS)

For graceful shutdown on power loss:

Services > UPS > Configuration

Setting Value

| UPS Type | nut (networked) | | Remote Host | 192.168.0.12 (NAS) | | Remote User | upsmon | | Remote Password | (from NAS NUT config) |

See docs/guides/nut-config.md for NUT server setup on NAS.

Dual-WAN / LTE Failover

Automatic WAN failover using a TP-Link TL-MR100 LTE router on the LAN as a secondary gateway. When the ISP goes down, OPNsense routes critical traffic (Tailscale, DNS) over LTE within ~60 seconds. The family doesn't notice — Augusto retains remote access.

Design: LAN-Side Gateway

The Aoostar N1 Pro has only 2 NICs (both occupied: WAN + LAN). Instead of adding a third NIC via USB adapter, the TL-MR100 connects to the MokerLink switch alongside all other LAN devices. OPNsense uses it as a failover gateway on the LAN interface — no extra interfaces, no Proxmox USB passthrough, no cable mess.

The MR100 is a standalone LTE router with a built-in SIM slot. It handles the cellular connection internally and presents a clean Ethernet interface. Double NAT is irrelevant since Tailscale handles NAT traversal via DERP relays.

Hardware

Item Details

| LTE Router | TP-Link TL-MR100 (~$32, Flytec CDE) | | SIM | Tigo or Personal prepaid, 5GB/month (~$3/mo) | | Connection | Ethernet from MR100 LAN port → MokerLink switch |

Prerequisites: MR100 Setup

Before connecting to the homelab, configure the MR100 standalone (connect via WiFi or direct Ethernet to a laptop):

  1. Insert SIM into the MR100's micro-SIM slot (bottom of device)
  2. Access admin UI at http://192.168.1.1 (MR100 default)
  3. Default password: admin
  4. Set APN if not auto-detected:
  5. Tigo: internet.tigo.py
  6. Personal: internet
  7. Change MR100 LAN IP to 192.168.0.3/24:
  8. Network > LAN Settings → IP Address: 192.168.0.3, Subnet: 255.255.255.0
  9. This puts the MR100 on the same subnet as OPNsense LAN
  10. Disable DHCP server on the MR100:
  11. Network > LAN Settings > DHCP → Disable
  12. OPNsense remains the only DHCP server on the network
  13. Disable MR100 WiFi (both bands):
  14. Wireless > Wireless Settings → Disable
  15. No rogue SSID on the network
  16. Set admin password to something strong (store in Vaultwarden)
  17. Verify LTE connection: check signal bars and test browsing via the MR100's admin UI

Physical Connection

Plug the MR100's LAN/WAN Ethernet port into any free port on the MokerLink switch. Connect power. Done.

Rack / Shelf:
  [ARRIS modem] ──eth──► [MokerLink switch] ◄──eth── [Aoostar nic1 (LAN)]
  [TL-MR100]    ──eth──┘        │            ◄──eth── [Aoostar nic0 (WAN) ← ARRIS]
   (power + SIM)                ├── NAS
                                ├── WiFi AP
                                └── other devices

OPNsense Configuration

1. Add LTE Gateway

The MR100 is at 192.168.0.3 on the LAN. Add it as a gateway manually.

System > Gateways > Configuration > Add

Setting Value

| Name | LTE_GW | | Description | TP-Link MR100 LTE failover | | Interface | LAN | | Address Family | IPv4 | | IP Address | 192.168.0.3 | | Upstream Gateway | Yes | | Far Gateway | Yes | | Monitor IP | 9.9.9.9 | | Priority | 255 (default) |

Important:EnableFar Gateway — this tells OPNsense the gateway is not directly connected (it's a router on the LAN, not a point-to-point link). Without this, gateway monitoring may not work correctly.

Verify the existing ISP gateway:

Setting Value

| Name | ISP_WAN_DHCP | | Interface | WAN | | Monitor IP | 1.1.1.1 |

Use different monitor IPs (1.1.1.1 vs 9.9.9.9) so both gateways are health-checked independently.

2. Create Gateway Group

System > Gateways > Group > Add

Setting Value

| Group Name | WAN_FAILOVER | | ISP_WAN_DHCP | Tier 1 (primary) | | LTE_GW | Tier 2 (failover) | | Trigger Level | Member Down |

3. Enable Gateway Switching

System > Settings > General

  • Enable: Allow default gateway switching

4. Update Firewall Rules

Firewall > Rules > LAN

  • Edit the default "Allow all outbound" rule
  • Set Gateway to WAN_FAILOVER (instead of default)

5. Prevent LAN Devices from Using MR100 Directly

LAN devices should never use 192.168.0.3 as a gateway — only OPNsense should route through it. The MR100's DHCP is disabled (step 5 in prerequisites), so devices won't discover it. As an extra safeguard, add a firewall rule:

Firewall > Rules > LAN (add at top):

# Action Source Dest Port Description

| 1 | Block | !OPNsense | 192.168.0.3 | any | Only OPNsense can reach MR100 |

This ensures only OPNsense itself routes traffic through the MR100.

Reserve 192.168.0.3 for the MR100 in OPNsense DHCP so nothing else gets that IP:

Services > DHCPv4 > LAN > DHCP Static Mappings > Add

Setting Value

| MAC Address | (MR100's MAC — check sticker on bottom) | | IP Address | 192.168.0.3 | | Description | TP-Link MR100 LTE failover |

Testing Failover

  1. Verify both gateways are online:
  2. System > Gateways > Configuration — both should show "Online"

  3. ISP_WAN_DHCP monitors 1.1.1.1 via ISP, LTE_GW monitors 9.9.9.9 via MR100

  4. Simulate ISP failure:

# Unplug ARRIS modem (or disable WAN interface in OPNsense)
# Interfaces > WAN > Disable → Save → Apply
  1. Verify failover (~30-60 seconds):
  2. System > Gateways > Configuration — ISP_WAN should show "Offline", LTE_GW "Online"
  3. From a LAN device: ping 8.8.8.8 should work (routed via MR100 LTE)
  4. Tailscale should reconnect within 1-2 minutes

  5. ntfy alert should fire (Uptime Kuma detects WAN change)

  6. Verify failback:

  7. Re-enable WAN / plug ARRIS back in
  8. ISP_WAN goes back to "Online"

  9. Traffic automatically returns to ISP (Tier 1)

  10. Check LTE data usage:

  11. Access MR100 admin UI at http://192.168.0.3
  12. Advanced > System Tools > Statistics → check monthly data

WAN Watchdog Integration

The existing /root/wan_watchdog.sh on OPNsense handles DHCP recovery for the primary WAN. With multi-WAN, the gateway group handles failover automatically — the watchdog is complementary (it tries to recover ISP before failover kicks in).

Architecture

                    ┌──────────┐
   ISP ────────────►│  ARRIS   │
   (Tier 1)         │ (bridge) │
                    └────┬─────┘
                         │ nic0/vmbr0
                    ┌────▼─────────────────────┐
                    │   Aoostar N1 Pro          │
                    │   (Proxmox)               │
                    │                           │
                    │   ┌───────────────────┐   │
                    │   │    OPNsense VM    │   │
                    │   │  WAN_FAILOVER:    │   │
                    │   │  vtnet0 = Tier 1  │   │
                    │   │  LAN GW = Tier 2  │   │
                    │   └───────────────────┘   │
                    │                           │
                    └────┬─────────────────────┘
                         │ nic1/vmbr1
                    ┌────▼─────────────────────┐
                    │    MokerLink Switch       │
                    │                           │
                    │  ┌─────────┐              │
                    │  │ TL-MR100│◄── LTE SIM   │
                    │  │ .0.2    │   (Tier 2)   │
                    │  └─────────┘              │
                    └────┬────────┬────────┬───┘
                         │        │        │
                    [Docker VM] [NAS]  [Devices]
                      .0.10     .0.12

Backup Configuration

System > Configuration > Backups

  • Enable automatic backups
  • Download backup after major changes
  • Store in homelab git repo (encrypted)
# Encrypt backup with age
age -r age1... opnsense-config.xml > opnsense-config.xml.age

Monitoring

Uptime Kuma

Add OPNsense health check:

Prometheus (Optional)

Install telegraf plugin for metrics export.

Verification Checklist

Initial Setup

  • [ ] VM created with correct resources
  • [ ] WAN bridge (vmbr0) configured
  • [ ] LAN bridge configured
  • [ ] OPNsense installed
  • [ ] Web GUI accessible

Network

  • [ ] WAN gets IP from ISP
  • [ ] LAN devices get DHCP
  • [ ] Internet access works
  • [ ] DNS resolution works

VLANs

  • [ ] IoT VLAN created
  • [ ] Guest VLAN created
  • [ ] Switch configured for VLANs
  • [ ] Firewall rules applied
  • [ ] Camera isolation verified

Security

  • [ ] Strong admin password set
  • [ ] Firmware updated
  • [ ] Backup created
  • [ ] Tailscale connected
  • docs/guides/vlan-design.md - VLAN configuration details
  • docs/architecture/fixed-homelab.md - Overall architecture
  • docs/guides/nut-config.md - UPS graceful shutdown
  • docs/architecture/hardware.md - Mini PC specs
  • docs/reference/family-emergency-internet.md - Family emergency internet runbook
  • docs/guides/incident-2026-03-05-isp-outage.md - ISP outage incident that motivated dual-WAN