HomeLab Series: Network Architecture - Bridges & OPNsense

In Post 1, we installed Proxmox VE on a refurbished Dell PowerEdge R720 and created a capable, cost-effective virtualization platform. This post gives that platform a proper network architecture — four isolated bridges with OPNsense as the edge firewall.

A flat home network, everything on the same subnet, routed through a consumer router, is fine for basic lab work. But it’s not fine for security testing. When you’re running intentionally vulnerable systems, attack tools, or internet-facing services, isolation matters. This post builds four discrete network zones, each with a defined purpose and enforced boundaries, using only open source software.

By the end of this post, the lab will have a real edge firewall between the internal lab network and the internet, an isolated DMZ ready for future internet-facing services, and management access cleanly separated from lab traffic. Every step has a corresponding script in the homelab-series repository.

Clone the repo to your Proxmox host before starting:

Copy to Clipboard

Why Network Segmentation

The Four Network Zones

Before touching any configuration, it helps to understand what we’re building and why each zone exists.

Management (`vmbr0`, 192.168.1.0/24)

This bridge is created by the Proxmox installer and is not modified here. It carries admin access to the Proxmox host only, no lab VM traffic passes through it. Critically, OPNsense never gets an interface on this network. If the firewall VM crashes or behaves unexpectedly, management access to the host is always available on this bridge.

Edge/WAN (`vmbr1`, DHCP from home router)

A pure Layer 2 passthrough bridge. OPNsense is the only tenant. It receives a DHCP lease from the home router and uses it as the upstream internet connection. Importantly, no IP address is assigned to the Proxmox host on this bridge.

Internal (`vmbr2`, 10.10.10.0/24)

The private lab network. Pi-hole, the Samba Domain Controller, the Kali Linux VM, and all future lab systems live here. OPNsense’s LAN interface is the gateway at 10.10.10.1. As a result, internet access is permitted outbound through OPNsense. However, access to the DMZ is blocked at the firewall.

DMZ (`vmbr3`, 10.20.20.0/24)

Isolated from Internal at the firewall. Specifically, reserved for future internet-facing services. Hard-blocked from reaching the Internal network or Management at the firewall level. Importantly, built now so the full architecture is in place from day one.

Proxmox network topology diagram: four bridge zones — Management, Edge WAN, OPNsense LAN, and DMZ

network-diagram-light

Network topology, four isolated zones with OPNsense as the edge firewall.

Network and IP Reference

Bridge	NIC	Role	Subnet	Gateway
vmbr0	eno1	Management	192.168.1.0/24	Home router
vmbr1	eno2	Edge (WAN)	Home router DHCP	Home router
vmbr2	eno3	Internal (LAN)	10.10.10.0/24	OPNsense 10.10.10.1
vmbr3	eno4	DMZ	10.20.20.0/24	OPNsense 10.20.20.1

OPNsense VM NIC assignments:

VM Interface	Bridge	Role
vtnet0	vmbr1	WAN
vtnet1	vmbr2	Internal
vtnet2	vmbr3	DMZ

Key design rule: OPNsense does not get an interface on vmbr0. The Proxmox host must never be reachable through the firewall VM.

Identify Your Physical NICs

SSH into the Proxmox host and confirm all four NICs are present and cabled before creating bridges.

1. List all interfaces and confirm link status:

Copy to Clipboard

2. Check speed and link detection per interface to confirm all four NICs are connected:

Copy to Clipboard

3. Confirm which NIC is currently carrying the Proxmox management IP, this is your vmbr0 NIC and must not be reassigned:

Copy to Clipboard

Proxmox host terminal: ip link show listing all four physical NICs before bridge assignment

nic-detection-ip-link

ip link show — all four NICs visible and UP

Note: Interface names on your system may differ (eth0–eth3, enp3s0f0, etc.). Substitute the correct names wherever eno1–eno4 appear in the scripts and config files. The scripts detect the management NIC automatically and will warn if you attempt to reassign it.

Create the Network Bridges

This script creates vmbr1, vmbr2, and vmbr3 by appending bridge stanzas to /etc/network/interfaces and applying them with ifreload -a. It backs up the interfaces file before making any changes and validates that the requested NICs exist and are not the management interface.

1. Pull the latest scripts from the repo:

Copy to Clipboard

2. Review the script before running it:

Copy to Clipboard

3. Run the bridge creation script:

Copy to Clipboard

Proxmox terminal: 01-create-bridges.sh running interactively, assigning NICs to vmbr1, vmbr2, vmbr3

bridge-script-running

01-create-bridges.sh running, prompting for NIC assignments before applying changes

The script prompts for the physical NIC names for each bridge (defaulting to eno2, eno3, eno4) and displays a confirmation summary before applying any changes. Full script:

View full script: 01-create-bridges.sh

Copy to Clipboard

#!/bin/bash
# Script:      01-create-bridges.sh
# Description: Interactively creates vmbr1 (Edge/WAN), vmbr2 (Internal),
#              and vmbr3 (DMZ) on a Proxmox VE host. vmbr0 (management) is
#              created by the Proxmox installer and is never modified here.
# Blog post:   https://abrictosecurity.com/homelab-series-network-architecture
# Usage:       sudo bash 01-create-bridges.sh
# Dependencies: ifreload (ifupdown2, default on Proxmox VE), brctl (bridge-utils)

set -euo pipefail

source "$(dirname "${BASH_SOURCE[0]}")/../lib/logo.sh" 2>/dev/null || true

RED='\033[0;31m'; YELLOW='\033[1;33m'; GREEN='\033[0;32m'
CYAN='\033[0;36m'; BOLD='\033[1m'; RESET='\033[0m'

info()    { echo -e "${CYAN}[INFO]${RESET}  $*"; }
ok()      { echo -e "${GREEN}[OK]${RESET}    $*"; }
warn()    { echo -e "${YELLOW}[WARN]${RESET}  $*"; }
die()     { echo -e "${RED}[ERROR]${RESET} $*" >&2; exit 1; }

[[ $EUID -ne 0 ]] && die "Must be run as root.  Try: sudo bash $0"
command -v ifreload &>/dev/null || die "ifreload not found. Is this a Proxmox VE host?"
command -v brctl    &>/dev/null || die "brctl not found. Run: apt install bridge-utils -y"

IFACES_FILE="/etc/network/interfaces"
BACKUP="${IFACES_FILE}.bak.$(date +%Y%m%d%H%M%S)"

# Detect management NIC
MGMT_NIC=""
MGMT_IP=""
if MGMT_NIC=$(ip route show default 2>/dev/null \
    | awk '/dev/ { for(i=1;i<=NF;i++) if($i=="dev") print $(i+1) }' | head -1); then
    if [[ -n "$MGMT_NIC" ]]; then
        MGMT_IP=$(ip -4 addr show "$MGMT_NIC" 2>/dev/null \
            | awk '/inet / { print $2 }' | cut -d/ -f1 | head -1)
        info "Detected management NIC: ${BOLD}${MGMT_NIC}${RESET}  IP: ${BOLD}${MGMT_IP:-unknown}${RESET}"
    fi
fi

# Check for pre-existing bridge definitions
for bridge in vmbr1 vmbr2 vmbr3; do
    if grep -q "^auto ${bridge}$" "$IFACES_FILE" 2>/dev/null; then
        die "${bridge} is already defined in ${IFACES_FILE}."
    fi
done

# Interactive NIC selection
read -r -p "  Physical NIC for vmbr1 (Edge/WAN) [eno2]: " NIC_WAN
NIC_WAN="${NIC_WAN:-eno2}"

read -r -p "  Physical NIC for vmbr2 (Internal) [eno3]: " NIC_LAN
NIC_LAN="${NIC_LAN:-eno3}"
read -r -p "  Internal subnet [10.10.10.0/24]: " INTERNAL_SUBNET
INTERNAL_SUBNET="${INTERNAL_SUBNET:-10.10.10.0/24}"
read -r -p "  Proxmox host IP on vmbr2 [10.10.10.254]: " HOST_BRIDGE_IP
HOST_BRIDGE_IP="${HOST_BRIDGE_IP:-10.10.10.254}"

read -r -p "  Physical NIC for vmbr3 (DMZ) [eno4]: " NIC_DMZ
NIC_DMZ="${NIC_DMZ:-eno4}"
read -r -p "  DMZ subnet (for reference comments only) [10.20.20.0/24]: " DMZ_SUBNET
DMZ_SUBNET="${DMZ_SUBNET:-10.20.20.0/24}"

# Derive gateway IPs
LAN_MASK="${INTERNAL_SUBNET#*/}"
INTERNAL_GW="${INTERNAL_SUBNET%/*}"; INTERNAL_GW="${INTERNAL_GW%.*}.1"
DMZ_GW="${DMZ_SUBNET%/*}"; DMZ_GW="${DMZ_GW%.*}.1"

# Validate NICs
for label_nic in "vmbr1:${NIC_WAN}" "vmbr2:${NIC_LAN}" "vmbr3:${NIC_DMZ}"; do
    label="${label_nic%%:*}"; nic="${label_nic##*:}"
    ip link show "$nic" &>/dev/null \
        || die "Interface '${nic}' (${label}) not found. Run 'ip link show'."
    [[ "$nic" == "$MGMT_NIC" ]] \
        && die "Interface '${nic}' is the management NIC, do not reassign it."
done

read -r -p "Apply this configuration? [y/N]: " CONFIRM
CONFIRM="${CONFIRM,,}"
[[ "$CONFIRM" == "y" || "$CONFIRM" == "yes" ]] \
    || { info "Aborted. No changes were made."; exit 0; }

info "Backing up ${IFACES_FILE} → ${BACKUP}"
cp "$IFACES_FILE" "$BACKUP"
ok "Backup created."

# Appends vmbr1/vmbr2/vmbr3 stanzas to /etc/network/interfaces via heredoc.
# Full bridge config: https://github.com/AbrictoSecurity/homelab-series/blob/main/scripts/network/01-create-bridges.sh

info "Applying with ifreload -a ..."
ifreload -a
ok "Network configuration applied."

brctl show

4. Verify all four bridges are active:

Copy to Clipboard

brctl-show-output

brctl show — all four bridges active with NICs assigned

Proxmox Node System Network panel showing all four bridges: vmbr0, vmbr1, vmbr2, vmbr3

proxmox-network-panel

Proxmox Network panel (Node → System → Network) confirming all four bridges

Deploy the OPNsense VM

With bridges in place, the next step is creating the OPNsense VM. Download the OPNsense CE installer ISO to the Proxmox ISO store first:

Copy to Clipboard

Why OPNsense over pfSense? pfSense’s parent company Netgate has increasingly pushed users toward paid subscriptions and commercial hardware. OPNsense is a fully community-driven fork built on HardenedBSD with weekly releases and no subscription model. It is the recommended open source edge firewall for a homelab in 2025.

Run the VM creation script, it auto-discovers available ISOs and storage pools:

Copy to Clipboard

Proxmox terminal: OPNsense VM creation script running, selecting ISO and storage for the firewall VM

opnsense-vm-script-running

02-create-opnsense-vm.sh running, interactive ISO and storage selection

Full script (see 02-create-opnsense-vm.sh on GitHub for the latest version):

View full script: 02-create-opnsense-vm.sh

Copy to Clipboard

#!/bin/bash
# Script:      02-create-opnsense-vm.sh
# Description: Interactively creates the OPNsense edge firewall VM on Proxmox VE
#              using the qm CLI. Discovers available ISOs and storage pools
#              from the host, nothing is hardcoded.
# Blog post:   https://abrictosecurity.com/homelab-series-network-architecture
# Usage:       sudo bash 02-create-opnsense-vm.sh
# Dependencies: Proxmox VE (qm, pvesm), OPNsense ISO in /var/lib/vz/template/iso/

set -euo pipefail

source "$(dirname "${BASH_SOURCE[0]}")/../lib/logo.sh" 2>/dev/null || true

RED='\033[0;31m'; YELLOW='\033[1;33m'; GREEN='\033[0;32m'
CYAN='\033[0;36m'; BOLD='\033[1m'; RESET='\033[0m'

[[ $EUID -ne 0 ]] && die "Must be run as root.  Try: sudo bash $0"
command -v qm    &>/dev/null || die "qm not found. Is this a Proxmox VE host?"
command -v pvesm &>/dev/null || die "pvesm not found. Is this a Proxmox VE host?"

# Prerequisite: bridges must exist
missing_bridges=()
for bridge in vmbr1 vmbr2 vmbr3; do
    ip link show "$bridge" &>/dev/null || missing_bridges+=("$bridge")
done
[[ ${#missing_bridges[@]} -gt 0 ]] \
    && die "Missing bridge(s): ${missing_bridges[*]}, Run 01-create-bridges.sh first."

# Auto-discover ISOs
ISO_DIR="/var/lib/vz/template/iso"
iso_files=( "$ISO_DIR"/*.iso )
[[ ${#iso_files[@]} -eq 0 ]] && die "No ISO found in ${ISO_DIR}. Download OPNsense first."

if [[ ${#iso_files[@]} -eq 1 ]]; then
    ISO_PATH="${iso_files[0]}"
else
    # display list, prompt for selection (see full script for display code)
    read -r -p "  Select ISO number [1]: " iso_choice
    iso_choice="${iso_choice:-1}"
    ISO_PATH="${iso_files[$((iso_choice-1))]}"
fi
ISO_NAME=$(basename "$ISO_PATH")
ISO_REF="local:iso/${ISO_NAME}"

# Auto-discover storage pools (display list, prompt for selection, see full script)
# ...storage selection code...
read -r -p "  Select storage number [1]: " storage_choice

# Interactive VM configuration
read -r -p "  VM ID [100]: " VMID; VMID="${VMID:-100}"
read -r -p "  VM name [opnsense-edge]: " VM_NAME; VM_NAME="${VM_NAME:-opnsense-edge}"
read -r -p "  Memory in GB [2]: " VM_MEM; VM_MEM="${VM_MEM:-2}"
read -r -p "  CPU cores [2]: " VM_CORES; VM_CORES="${VM_CORES:-2}"
read -r -p "  Disk size in GB [8]: " VM_DISK_GB; VM_DISK_GB="${VM_DISK_GB:-8}"

read -r -p "Create this VM? [y/N]: " CONFIRM
[[ "${CONFIRM,,}" == "y" || "${CONFIRM,,}" == "yes" ]] || exit 0

qm create "$VMID" \
    --name        "$VM_NAME" \
    --memory      "$((VM_MEM * 1024))" \
    --cores       "$VM_CORES" \
    --cpu         host \
    --ostype      other \
    --scsihw      virtio-scsi-pci \
    --serial0     socket \
    --vga         std \
    --cdrom       "${ISO_REF}" \
    --boot        "order=scsi0;ide2" \
    --net0        "virtio,bridge=vmbr1,firewall=0" \
    --net1        "virtio,bridge=vmbr2,firewall=0" \
    --net2        "virtio,bridge=vmbr3,firewall=0" \
    --onboot      1

qm set "$VMID" --scsi0 "${VM_STORAGE}:${VM_DISK_GB}"

Verify the VM was created:

Copy to Clipboard

Proxmox VM list showing the OPNsense VM entry with status stopped

opnsense-vm-list-1

Proxmox VM list showing the OPNsense edge VM

Proxmox VM hardware summary showing three network interfaces attached to vmbr1, vmbr2, and vmbr3

opnsense-vm-hardware

VM hardware summary — net0 vmbr1 (WAN), net1 vmbr2 (Internal), net2 vmbr3 (DMZ)

Install OPNsense via Console

The ISO installer and first-boot interface assignment must be done through the Proxmox noVNC console. Everything after this point is scripted.

1. Start the VM and open the console:

Copy to Clipboard

Navigate to the Proxmox web UI → VM 100 → Console.

The OPNsense boot menu appears. Select Install OPNsense.
Log in with the default installer credentials: installer / opnsense
Select Install (UFS) → accept the disk selection → confirm.
Set a strong root password when prompted.
Select Reboot when the install completes.

Lessons learned: Auto (UFS) failure on a blank disk

On a disk with no existing partition table, the OPNsense installer’s “Auto (UFS)” option will fail at the partitioning step. The fix: select “Manual” partitioning, choose the disk, create a GPT partition table (g), write it (w), then exit back to the installer menu and select “Auto (UFS)” again. It will succeed on the now-initialized disk.

OPNsense installer showing Auto UFS partitioning failure on a blank disk

opnsense-install-ufs-fail

Auto (UFS) fails on a disk with no partition table

OPNsense installer Manual partitioning screen, disk selected

opnsense-install-workaround-1

Step 1: Select Manual partitioning and choose the disk

OPNsense installer showing Auto UFS option after GPT initialization

opnsense-install-workaround-2-auto-ufs

Step 2: After GPT is written, return to the installer menu

OPNsense installer: GPT partition table creation on blank disk to fix Auto UFS failure

opnsense-install-workaround-3-gpt

Step 3: Create the GPT partition table (g to create, w to write)

OPNsense installer completing Auto UFS installation successfully after GPT fix

opnsense-install-workaround-4-commit

Step 4: Auto (UFS) now succeeds on the initialized disk

Before the VM reboots, remove the ISO so it boots from disk on the next start:

Copy to Clipboard

Alternatively, remove the ISO via the Proxmox web UI: VM → Hardware → CD/DVD Drive → Edit → Do not use any media.

Proxmox VM Hardware panel showing the Edit CD/DVD Drive dialog with Do not use any media selected

proxmox-remove-iso

Remove the ISO via Proxmox Hardware → CD/DVD Drive → Edit → Do not use any media

On first boot, at the console menu

Select 1) Assign Interfaces:

Decline VLAN setup when prompted (N)
WAN → vtnet0
LAN → vtnet1
Optional 1 → vtnet2
Confirm the assignment

Select 2) Set Interface IP Address → choose LAN:

IP: 10.10.10.1 / Subnet: 24
Upstream gateway: leave blank for LAN
Enable DHCP server on LAN: (N) (Pi-hole handles DHCP in the next post)
Revert to HTTP: (N)

OPNsense first-boot console showing vtnet0, vtnet1, vtnet2 interface assignment to WAN, LAN, and OPT1

opnsense-console-assign-interfaces

OPNsense first-boot interface assignment — vtnet0 → WAN, vtnet1 → LAN, vtnet2 → OPT1

OPNsense console Set Interface IP Address screen showing LAN IP 10.10.10.1 with subnet 24 being entered

opnsense-console-set-lan-ip

Setting the LAN IP to 10.10.10.1/24 at the OPNsense console

OPNsense console main menu showing LAN vtnet1 at 10.10.10.1/24 and OPT1 vtnet2 at 10.20.20.1/24 with WAN on DHCP

opnsense-console-all-interfaces

All interfaces confirmed — LAN 10.10.10.1/24, OPT1 (DMZ) 10.20.20.1/24, WAN on DHCP

Configure OPNsense via API

With OPNsense installed and the LAN IP set, the API configuration script handles the rest. It runs in two phases: Phase 0 creates a persistent internal admin LXC on vmbr2, and Phase 1 configures OPNsense via the REST API to enable the DMZ interface and create three baseline firewall rules.

Before running the script, enable the OPNsense API. Access the web UI from the Proxmox host using an SSH tunnel:

Copy to Clipboard

Then open https://localhost:8443 in a browser. Complete the setup wizard, then:

OPNsense login page at https://127.0.0.1:8443 shown in browser via SSH tunnel

opnsense-web-gui-login

OPNsense web GUI login page, accessed via SSH tunnel from the management network

Enable API: System → Settings → Administration → Enable API → Save.
Generate API key: System → Access → Users → admin → API Keys → Add. Copy the key and secret, shown only once.

OPNsense System Access Users page showing the Create and download API key button for the admin user

opnsense-web-gui-api-key

System → Access → Users → admin → API Keys — create and download the key before running the script

Run the configuration script:

Copy to Clipboard

The script configures:

OPT1 (DMZ) interface enabled and labeled “DMZ”
Firewall rule: Internal → WAN (allow)
Firewall rule: Internal → DMZ (block)
Firewall rule: DMZ → Internal (block)

Full script available at 03-opnsense-configure.sh on GitHub.

View full script: 03-opnsense-configure.sh

Copy to Clipboard

#!/bin/bash
# Script:      03-opnsense-configure.sh
# Description: Two-phase script run on the Proxmox host.
#              Phase 0 - Creates a Debian 12 LXC on vmbr2 (Internal) as the
#                        permanent internal admin machine for web GUI access.
#              Phase 1 - Configures OPNsense post-install via the REST API:
#                        enables and names the DMZ (OPT1) interface, then
#                        creates three baseline firewall rules:
#                          Allow Internal (LAN) → WAN
#                          Block  Internal (LAN) → DMZ
#                          Block  DMZ → Internal (LAN)
# Blog post:   https://abrictosecurity.com/homelab-series-network-architecture
# Usage:       bash 03-opnsense-configure.sh <api_key> <api_secret>
# Run from:    Proxmox host (root) - requires pct and curl
# Dependencies: pct (Proxmox LXC), pveam (template manager), curl
#
# SECURITY NOTE: API credentials are passed as command-line arguments.
# On a shared system, arguments are visible in process listings (ps aux).
# On a single-user homelab host this is acceptable. To prevent the
# credentials from being written to ~/.bash_history, run:
#   unset HISTFILE && bash 03-opnsense-configure.sh <key> <secret>

set -euo pipefail

# ─── Abricto logo ─────────────────────────────────────────────────────────────
# shellcheck source=../lib/logo.sh
source "$(dirname "${BASH_SOURCE[0]}")/../lib/logo.sh" 2>/dev/null || true

# ─── Colours ──────────────────────────────────────────────────────────────────
RED='\033[0;31m'
YELLOW='\033[1;33m'
GREEN='\033[0;32m'
CYAN='\033[0;36m'
BOLD='\033[1m'
RESET='\033[0m'

# ─── Output helpers ───────────────────────────────────────────────────────────
info()    { echo -e "${CYAN}[INFO]${RESET}  $*"; }
ok()      { echo -e "${GREEN}[OK]${RESET}    $*"; }
warn()    { echo -e "${YELLOW}[WARN]${RESET}  $*"; }
die()     { echo -e "${RED}[ERROR]${RESET} $*" >&2; exit 1; }

# ─── Root check ───────────────────────────────────────────────────────────────
[[ $EUID -ne 0 ]] && die "Must be run as root.  Try: sudo bash $0"

# ─── Dependency check ─────────────────────────────────────────────────────────
command -v curl  &>/dev/null || die "curl not found. Install with: apt install curl -y"
command -v pct   &>/dev/null || die "pct not found. Is this a Proxmox VE host?"
command -v pveam &>/dev/null || die "pveam not found. Is this a Proxmox VE host?"

# ─── Prerequisite: Internal bridge must exist ─────────────────────────────────
ip link show vmbr2 &>/dev/null \
    || die "vmbr2 not found. Run 01-create-bridges.sh first."

# ─── Credential arguments ─────────────────────────────────────────────────────
API_KEY="${1:?Usage: bash $0 <api_key> <api_secret>}"
API_SECRET="${2:?Usage: bash $0 <api_key> <api_secret>}"
AUTH="${API_KEY}:${API_SECRET}"

# ─── Banner ───────────────────────────────────────────────────────────────────
echo ""
echo -e "${BOLD}╔══════════════════════════════════════════════════════════╗${RESET}"
echo -e "${BOLD}║      Abricto HomeLab - 03-opnsense-configure.sh          ║${RESET}"
echo -e "${BOLD}║   Phase 0: Create internal admin LXC on vmbr2            ║${RESET}"
echo -e "${BOLD}║   Phase 1: Configure DMZ interface + firewall rules      ║${RESET}"
echo -e "${BOLD}╚══════════════════════════════════════════════════════════╝${RESET}"
echo ""
warn "SSL certificate verification is skipped (-k) because OPNsense"
warn "uses a self-signed certificate until Let's Encrypt is configured."
warn "This is addressed in Post 3 of the HomeLab Series."
echo ""

# ─── Shared network configuration prompts ─────────────────────────────────────
echo -e "${BOLD}Network Configuration${RESET}"
echo ""

read -r -p "  OPNsense LAN IP [10.10.10.1]: " OPNSENSE_IP
OPNSENSE_IP="${OPNSENSE_IP:-10.10.10.1}"

read -r -p "  Internal subnet [10.10.10.0/24]: " LAN_SUBNET
LAN_SUBNET="${LAN_SUBNET:-10.10.10.0/24}"

read -r -p "  DMZ subnet [10.20.20.0/24]: " DMZ_SUBNET
DMZ_SUBNET="${DMZ_SUBNET:-10.20.20.0/24}"

LAN_MASK=$(echo "$LAN_SUBNET" | cut -d/ -f2)
HOST_BRIDGE_IP="${OPNSENSE_IP%.*}.254"

BASE_URL="https://${OPNSENSE_IP}/api"
echo ""

# ═══════════════════════════════════════════════════════════════════════════════
# PHASE 0 - Internal admin LXC
# ═══════════════════════════════════════════════════════════════════════════════
echo -e "${BOLD}╔══════════════════════════════════════════════════════════╗${RESET}"
echo -e "${BOLD}║             Phase 0 - Internal Admin LXC                 ║${RESET}"
echo -e "${BOLD}╚══════════════════════════════════════════════════════════╝${RESET}"
echo ""
echo "  A lightweight Debian 12 LXC on vmbr2 gives you a persistent machine"
echo "  on the Internal network to access the OPNsense web GUI and run"
echo "  future scripts from inside the lab."
echo ""
read -r -p "  Create internal admin LXC now? [Y/n]: " CREATE_LXC
CREATE_LXC="${CREATE_LXC:-y}"
CREATE_LXC="${CREATE_LXC,,}"

LXC_CTID=""

if [[ "$CREATE_LXC" == "y" || "$CREATE_LXC" == "yes" ]]; then

echo ""

while true; do
        read -r -p "  Container ID [110]: " LXC_CTID
        LXC_CTID="${LXC_CTID:-110}"
        [[ "$LXC_CTID" =~ ^[0-9]+$ ]] || { warn "CT ID must be a number."; continue; }
        if pct status "$LXC_CTID" &>/dev/null; then
            warn "CT ID ${LXC_CTID} already exists. Choose a different ID."
            continue
        fi
        break
    done

read -r -p "  Hostname [admin-internal]: " LXC_HOSTNAME
    LXC_HOSTNAME="${LXC_HOSTNAME:-admin-internal}"

read -r -p "  Static IP for LXC [10.10.10.10]: " LXC_IP
    LXC_IP="${LXC_IP:-10.10.10.10}"

echo ""
    echo -e "  ${BOLD}Available storage pools:${RESET}"
    echo ""
    printf "    %-4s  %-20s  %-12s  %s\n" "NUM" "NAME" "TYPE" "AVAILABLE"
    printf "    %-4s  %-20s  %-12s  %s\n" "───" "───────────────────" "───────────" "─────────"

mapfile -t lxc_storage_lines < <(pvesm status 2>/dev/null | awk 'NR>1 { print $1, $2, $3, $5 }')
    lxc_storage_names=()

for line in "${lxc_storage_lines[@]}"; do
        read -r sname stype sstatus savail <<< "$line"
        stype_lower="${stype,,}"
        [[ "$stype_lower" =~ ^(dir|lvm|lvmthin|zfspool|rbd|cephfs|nfs|cifs|btrfs|glusterfs|iscsi|iscsidirect|zfs) ]] || continue
        [[ "$sstatus" == "active" ]] || continue
        lxc_storage_names+=("$sname")
        idx=${#lxc_storage_names[@]}
        printf "    ${CYAN}%-4s${RESET}  %-20s  %-12s  %s\n" \
            "$idx" "$sname" "$stype" "${savail:-n/a}"
    done
    echo ""

if [[ ${#lxc_storage_names[@]} -eq 0 ]]; then
        die "No active storage pools found. Run 'pvesm status' to diagnose."
    fi

if [[ ${#lxc_storage_names[@]} -eq 1 ]]; then
        LXC_STORAGE="${lxc_storage_names[0]}"
        info "Auto-selected storage: ${BOLD}${LXC_STORAGE}${RESET}"
    else
        lxc_default_storage_idx=1
        for i in "${!lxc_storage_names[@]}"; do
            [[ "${lxc_storage_names[$i]}" == "local-lvm" ]] && { lxc_default_storage_idx=$((i+1)); break; }
        done
        while true; do
            read -r -p "  Select storage number [${lxc_default_storage_idx}]: " lxc_storage_choice
            lxc_storage_choice="${lxc_storage_choice:-${lxc_default_storage_idx}}"
            if [[ "$lxc_storage_choice" =~ ^[0-9]+$ ]] \
                && (( lxc_storage_choice >= 1 && lxc_storage_choice <= ${#lxc_storage_names[@]} )); then
                LXC_STORAGE="${lxc_storage_names[$((lxc_storage_choice-1))]}"
                break
            fi
            warn "Invalid selection. Enter a number between 1 and ${#lxc_storage_names[@]}."
        done
    fi
    echo ""

read -r -p "  Memory in GB [2]: " LXC_MEM
    LXC_MEM="${LXC_MEM:-2}"
    [[ "$LXC_MEM" =~ ^[0-9]+$ ]] || die "Memory must be a number in GB."

read -r -p "  CPU cores [2]: " LXC_CORES
    LXC_CORES="${LXC_CORES:-2}"
    [[ "$LXC_CORES" =~ ^[0-9]+$ ]] || die "CPU cores must be a number."

read -r -p "  Disk size in GB [8]: " LXC_DISK_GB
    LXC_DISK_GB="${LXC_DISK_GB:-8}"
    [[ "$LXC_DISK_GB" =~ ^[0-9]+$ ]] || die "Disk size must be a number in GB."
    echo ""

read -r -s -p "  Root password for LXC: " LXC_PASS
    echo ""
    read -r -s -p "  Confirm password: " LXC_PASS2
    echo ""
    [[ "$LXC_PASS" == "$LXC_PASS2" ]] || die "Passwords do not match."
    [[ -n "$LXC_PASS" ]]              || die "Password cannot be empty."
    echo ""

info "Searching for Debian 12 template ..."

TEMPLATE_PATH=$(find /var/lib/vz/template/cache/ \
        -maxdepth 1 -name "debian-12-standard*.tar.*" 2>/dev/null \
        | sort -V | tail -1)

if [[ -z "$TEMPLATE_PATH" ]]; then
        info "No Debian 12 template found locally. Fetching template list ..."
        pveam update &>/dev/null

TEMPLATE_NAME=$(pveam available --section system 2>/dev/null \
            | awk '{print $2}' \
            | grep "^debian-12-standard" \
            | sort -V | tail -1)

[[ -n "$TEMPLATE_NAME" ]] \
            || die "No Debian 12 template available. Check internet connectivity on the host."

info "Downloading ${TEMPLATE_NAME} ..."
        pveam download local "$TEMPLATE_NAME"

TEMPLATE_PATH=$(find /var/lib/vz/template/cache/ \
            -maxdepth 1 -name "debian-12-standard*.tar.*" 2>/dev/null \
            | sort -V | tail -1)
    fi

TEMPLATE_REF="local:vztmpl/$(basename "$TEMPLATE_PATH")"
    ok "Template: $(basename "$TEMPLATE_PATH")"
    echo ""

echo -e "${BOLD}──────────────────────────────────────────────────────────${RESET}"
    echo -e "${BOLD}LXC Summary:${RESET}"
    echo ""
    printf "  %-18s  %s\n" "Container ID:"  "$LXC_CTID"
    printf "  %-18s  %s\n" "Hostname:"      "$LXC_HOSTNAME"
    printf "  %-18s  %s\n" "IP:"            "${LXC_IP}/${LAN_MASK}"
    printf "  %-18s  %s\n" "Gateway:"       "$OPNSENSE_IP"
    printf "  %-18s  %s\n" "Bridge:"        "vmbr2 (Internal)"
    printf "  %-18s  %s\n" "Storage:"       "${LXC_STORAGE}:${LXC_DISK_GB}G"
    printf "  %-18s  %s\n" "Memory:"        "${LXC_MEM} GB  ($((LXC_MEM * 1024)) MB)"
    printf "  %-18s  %s\n" "CPU cores:"     "$LXC_CORES"
    printf "  %-18s  %s\n" "Template:"      "$(basename "$TEMPLATE_PATH")"
    echo ""
    echo -e "${BOLD}──────────────────────────────────────────────────────────${RESET}"
    echo ""
    read -r -p "  Create this LXC? [y/N]: " CONFIRM_LXC
    CONFIRM_LXC="${CONFIRM_LXC,,}"
    [[ "$CONFIRM_LXC" == "y" || "$CONFIRM_LXC" == "yes" ]] \
        || { info "LXC creation skipped."; LXC_CTID=""; }

if [[ -n "$LXC_CTID" ]]; then
        info "Creating LXC ${LXC_CTID} (${LXC_HOSTNAME}) ..."

pct create "$LXC_CTID" "$TEMPLATE_REF" \
            --hostname    "$LXC_HOSTNAME" \
            --memory      "$((LXC_MEM * 1024))" \
            --cores       "$LXC_CORES" \
            --rootfs      "${LXC_STORAGE}:${LXC_DISK_GB}" \
            --net0        "name=eth0,bridge=vmbr2,ip=${LXC_IP}/${LAN_MASK},gw=${OPNSENSE_IP}" \
            --nameserver  "$OPNSENSE_IP" \
            --password    "$LXC_PASS" \
            --unprivileged 1 \
            --onboot      1
        ok "LXC created."

info "Starting LXC ${LXC_CTID} ..."
        pct start "$LXC_CTID"

info "Waiting for LXC network to come up ..."
        for i in {1..15}; do
            if pct exec "$LXC_CTID" -- ping -c1 -W1 "$OPNSENSE_IP" &>/dev/null; then
                ok "LXC can reach OPNsense at ${OPNSENSE_IP}."
                break
            fi
            [[ $i -eq 15 ]] \
                && warn "LXC network not confirmed after 15s - continuing anyway."
            sleep 1
        done
        echo ""
    fi
fi

# ═══════════════════════════════════════════════════════════════════════════════
# PHASE 1 - OPNsense API configuration
# ═══════════════════════════════════════════════════════════════════════════════
echo -e "${BOLD}╔══════════════════════════════════════════════════════════╗${RESET}"
echo -e "${BOLD}║         Phase 1 - OPNsense API Configuration             ║${RESET}"
echo -e "${BOLD}╚══════════════════════════════════════════════════════════╝${RESET}"
echo ""

BRIDGE_IP_ADDED=false

cleanup_bridge_ip() {
    if $BRIDGE_IP_ADDED; then
        ip addr del "${HOST_BRIDGE_IP}/${LAN_MASK}" dev vmbr2 2>/dev/null || true
        info "Removed temporary host IP ${HOST_BRIDGE_IP} from vmbr2."
    fi
}
trap cleanup_bridge_ip EXIT

if ! ip addr show vmbr2 | grep -q "${HOST_BRIDGE_IP}"; then
    info "Adding temporary host IP ${HOST_BRIDGE_IP}/${LAN_MASK} to vmbr2 for API access ..."
    ip addr add "${HOST_BRIDGE_IP}/${LAN_MASK}" dev vmbr2
    BRIDGE_IP_ADDED=true
    ok "Host IP added. Will be removed automatically on script exit."
else
    info "Host IP ${HOST_BRIDGE_IP} already present on vmbr2 - skipping."
fi
echo ""

api_call() {
    local method="$1"
    local endpoint="$2"
    local body="${3:-}"
    local response

if [[ -n "$body" ]]; then
        response=$(curl -sk -u "$AUTH" -X "$method" \
            -H "Content-Type: application/json" \
            -d "$body" \
            "${BASE_URL}${endpoint}" 2>&1) || die "curl failed on ${endpoint}"
    else
        response=$(curl -sk -u "$AUTH" -X "$method" \
            "${BASE_URL}${endpoint}" 2>&1) || die "curl failed on ${endpoint}"
    fi

[[ -z "$response" ]] \
        && die "Empty response from ${endpoint} - is OPNsense running and the API enabled?"
    echo "$response"
}

info "Testing API connectivity to ${OPNSENSE_IP} ..."
response=$(api_call GET "/core/firmware/status")

if echo "$response" | grep -q '"product_name"'; then
    version=$(echo "$response" | grep -o '"product_version":"[^"]*"' | cut -d'"' -f4)
    ok "Connected to OPNsense ${version}"
elif echo "$response" | grep -qi "unauthorized\|403\|401"; then
    die "Authentication failed. Verify the API key and secret."
else
    die "Unexpected API response. Is OPNsense running at ${OPNSENSE_IP}?"
fi
echo ""

echo -e "${BOLD}Step 1 of 3 - Configure DMZ interface${RESET}"
echo ""
info "Enabling OPT1 and setting description to 'DMZ' ..."
response=$(api_call POST "/interfaces/overview/setInterfaceIdentifier" \
    '{"identifier": "opt1", "description": "DMZ"}')

if echo "$response" | grep -qi '"result"\s*:\s*"saved"\|"status"\s*:\s*"ok"'; then
    ok "DMZ interface configured."
else
    warn "Unexpected response - verify OPT1 in OPNsense: Interfaces → Assignments."
fi

info "Applying interface changes ..."
api_call POST "/interfaces/overview/reconfigure" > /dev/null
ok "Interface changes applied."
echo ""

echo -e "${BOLD}Step 2 of 3 - Baseline firewall rules${RESET}"
echo ""

read -r -p "  Create these rules? [y/N]: " CONFIRM
CONFIRM="${CONFIRM,,}"
[[ "$CONFIRM" == "y" || "$CONFIRM" == "yes" ]] \
    || { info "Aborted. No rules were created."; exit 0; }
echo ""

info "Creating rule: Allow Internal → WAN ..."
response=$(api_call POST "/firewall/filter/addRule" \
    "{
        \"rule\": {
            \"enabled\":         \"1\",
            \"action\":          \"pass\",
            \"interface\":       \"lan\",
            \"direction\":       \"in\",
            \"ipprotocol\":      \"inet\",
            \"protocol\":        \"any\",
            \"source_net\":      \"${LAN_SUBNET}\",
            \"source_not\":      \"0\",
            \"destination_net\": \"any\",
            \"destination_not\": \"0\",
            \"log\":             \"1\",
            \"description\":     \"HomeLab: Allow Internal to WAN\"
        }
    }")
echo "$response" | grep -q '"uuid"' && ok "Rule created." || warn "Unexpected response."

info "Creating rule: Block Internal → DMZ ..."
response=$(api_call POST "/firewall/filter/addRule" \
    "{
        \"rule\": {
            \"enabled\":         \"1\",
            \"action\":          \"block\",
            \"interface\":       \"lan\",
            \"direction\":       \"in\",
            \"ipprotocol\":      \"inet\",
            \"protocol\":        \"any\",
            \"source_net\":      \"${LAN_SUBNET}\",
            \"source_not\":      \"0\",
            \"destination_net\": \"${DMZ_SUBNET}\",
            \"destination_not\": \"0\",
            \"log\":             \"1\",
            \"description\":     \"HomeLab: Block Internal to DMZ\"
        }
    }")
echo "$response" | grep -q '"uuid"' && ok "Rule created." || warn "Unexpected response."

info "Creating rule: Block DMZ → Internal ..."
response=$(api_call POST "/firewall/filter/addRule" \
    "{
        \"rule\": {
            \"enabled\":         \"1\",
            \"action\":          \"block\",
            \"interface\":       \"opt1\",
            \"direction\":       \"in\",
            \"ipprotocol\":      \"inet\",
            \"protocol\":        \"any\",
            \"source_net\":      \"${DMZ_SUBNET}\",
            \"source_not\":      \"0\",
            \"destination_net\": \"${LAN_SUBNET}\",
            \"destination_not\": \"0\",
            \"log\":             \"1\",
            \"description\":     \"HomeLab: Block DMZ to Internal\"
        }
    }")
echo "$response" | grep -q '"uuid"' && ok "Rule created." || warn "Unexpected response."
echo ""

echo -e "${BOLD}Step 3 of 3 - Apply changes${RESET}"
echo ""
info "Applying firewall rules ..."
api_call POST "/firewall/filter/apply" > /dev/null
ok "Firewall rules applied."
echo ""

echo -e "${GREEN}${BOLD}╔══════════════════════════════════════════════════════════╗${RESET}"
echo -e "${GREEN}${BOLD}║             Phase 0 + Phase 1 complete.                  ║${RESET}"
echo -e "${GREEN}${BOLD}╚══════════════════════════════════════════════════════════╝${RESET}"
echo ""
echo -e "${BOLD}Verify in the OPNsense web UI:${RESET}"
echo "  Interfaces → Assignments   OPT1 shows as 'DMZ' and is enabled"
echo "  Firewall → Rules → LAN     Allow Internal to WAN  (pass)"
echo "                             Block Internal to DMZ  (block)"
echo "  Firewall → Rules → DMZ     Block DMZ to Internal  (block)"
echo ""

Proxmox terminal: OPNsense firewall configuration script Phase 0, creating admin-internal LXC on vmbr2

opnsense-script-phase0-lxc

Script 03 Phase 0 — creating the admin-internal LXC (CT 110) on the Internal network

Proxmox terminal: OPNsense firewall API configuration Phase 1 output, three firewall rules applied

opnsense-script-phase1-rules

Script 03 Phase 1 — OPNsense API configuration complete, all three firewall rules created

OPNsense Firewall Rules page showing all three rules: Allow Internal to WAN, Block Internal to DMZ, Block DMZ to Internal

opnsense-firewall-rules-all

OPNsense Firewall → Rules — all three baseline rules active across LAN and OPT1 interfaces

Verify Network Connectivity

Spin up a quick test LXC on the Internal network to verify the full network stack is working end-to-end.

Proxmox storage note: Proxmox uses two separate storages for LXC creation. The template (local:vztmpl/...) must come from a directory-based storage like local. Additionally, the container root filesystem (--rootfs) must go to a block or directory storage that supports rootdir content — typically your LVM or ZFS pool, not local. Run pvesm status --content rootdir to find valid rootfs storage names on your node.

Copy to Clipboard

Proxmox terminal: pct create test container on vmbr2 to verify OPNsense firewall routing

test-container-creation

Test container (CT 998) created on the Internal network at 10.10.10.51

Copy to Clipboard

Proxmox test container: ping to OPNsense LAN gateway 10.10.10.1 and internet 1.1.1.1 both succeeding

connectivity-ping-lan-internet

LAN gateway (10.10.10.1) and internet (1.1.1.1) both reachable from the Internal network

Copy to Clipboard

Proxmox test container: apt install dnsutils confirming internet access through OPNsense firewall

connectivity-dns-install

DNS tools installing inside the container, confirming internet routing and package repo access

Copy to Clipboard

Proxmox test container: nslookup confirming DNS resolution through OPNsense firewall via 1.1.1.1

connectivity-dns-response

External DNS resolution working — google.com resolves via 1.1.1.1 through OPNsense

Copy to Clipboard

Terminal showing OPNsense DMZ interface 10.20.20.1 responding to ping, and 10.20.20.100 returning 100% packet loss

connectivity-dmz-test

OPNsense DMZ interface responds (expected) — forwarded traffic to 10.20.20.100 blocked or no host

Copy to Clipboard

Congratulations

The lab now has four isolated network zones with a real open source firewall between them. Management is completely separated from lab traffic. The DMZ is live and waiting for future internet-facing services. OPNsense is handling all routing and enforcement.

Every step in this post has a corresponding script in the homelab-series repository, clone it, customize the variables for your environment, and run.

In the next post, we give the lab a real identity: a registered domain, browser-trusted SSL certificates on every service via Let’s Encrypt, a Pi-hole DNS resolver with local hostname records, and a full Active Directory domain with Samba 4, for approximately $10 per year.

Next post: HomeLab Series: Domain, SSL, Pi-hole & Samba AD

Resources

Resource	Link
OPNsense CE Downloads	opnsense.org/download
OPNsense API Documentation	docs.opnsense.org
Proxmox Linux Bridge Docs	pve.proxmox.com/wiki/Network_Configuration
homelab-series Repository	github.com/AbrictoSecurity/homelab-series

HomeLab Series: Network Architecture – Bridges & OPNsense

Why Network Segmentation

The Four Network Zones

Management (`vmbr0`, 192.168.1.0/24)

Edge/WAN (`vmbr1`, DHCP from home router)

Internal (`vmbr2`, 10.10.10.0/24)

DMZ (`vmbr3`, 10.20.20.0/24)

Network and IP Reference

Identify Your Physical NICs

Create the Network Bridges

View full script: 01-create-bridges.sh

Deploy the OPNsense VM

View full script: 02-create-opnsense-vm.sh

Install OPNsense via Console

Configure OPNsense via API

View full script: 03-opnsense-configure.sh

Verify Network Connectivity

Congratulations

Resources

About the Author: David Edwards

HomeLab Series: Network Architecture – Bridges & OPNsense

Why Network Segmentation

The Four Network Zones

Management (vmbr0, 192.168.1.0/24)

Edge/WAN (vmbr1, DHCP from home router)

Internal (vmbr2, 10.10.10.0/24)

DMZ (vmbr3, 10.20.20.0/24)

Network and IP Reference

Identify Your Physical NICs

Create the Network Bridges

View full script: 01-create-bridges.sh

Deploy the OPNsense VM

View full script: 02-create-opnsense-vm.sh

Install OPNsense via Console

Configure OPNsense via API

View full script: 03-opnsense-configure.sh

Verify Network Connectivity

Congratulations

Resources

About the Author: David Edwards

Management (`vmbr0`, 192.168.1.0/24)

Edge/WAN (`vmbr1`, DHCP from home router)

Internal (`vmbr2`, 10.10.10.0/24)

DMZ (`vmbr3`, 10.20.20.0/24)