Runbook: Add a VLAN

Purpose

This runbook creates an 802.1Q VLAN on OPNsense, tags it on the parent NIC and upstream switch, and brings the new segment online with sane defaults. It is the runbook to reach for whenever a new logical segment needs to share a physical NIC with the rest of the firewall’s traffic.

When to use this runbook

Use this runbook when a new VLAN needs to exist on the network (guest, server, DMZ, IoT, voice, management, etc.) and OPNsense is the Layer-3 boundary for it. If you also need to add the corresponding physical or LAG interface first, see opnsense-rb-add-interface.

Pre-checks

• Capture a fresh encrypted config backup before any change.
• Confirm the parent NIC supports 802.1Q (essentially all modern NICs do; this is a FreeBSD vlan driver feature).
• Confirm the switch port OPNsense is connected to is set as a trunk and the planned VLAN ID is on the allowed list.
• Confirm no IP overlap with existing subnets configured on OPNsense.
• Have console access ready in case the management interface is accidentally placed on the new VLAN.

Procedure

1. Stay on a safe management path. Connect to the GUI over a non-VLAN management path (the LAN interface or a separate management VLAN that is not being modified).
2. Create the VLAN. Navigate to Interfaces > Other Types > VLAN and click +.
3. Configure the VLAN. Set Parent interface to the physical NIC or LAG that will carry the trunk. Set VLAN tag to the planned 802.1Q VLAN ID (1–4094; avoid 1 unless you really mean the native VLAN). Set VLAN priority to 0 unless QoS design specifies otherwise. Set Description to a human-readable name; this becomes part of the interface name.
4. Save the VLAN. OPNsense creates a new interface (e.g. igc1.100 for VLAN 100 on parent igc1).
5. Assign the VLAN interface. Navigate to Interfaces > Assignments, find the new VLAN in the dropdown, click +, and save.
6. Configure the new OPT interface. Click the new OPT entry. Check Enable interface. Set IPv4 configuration type to Static IPv4 and enter the IP/CIDR (e.g. 10.30.0.1/24). Leave IPv6 at None unless there is a concrete IPv6 plan.
7. Set the MTU. Keep 1500 for ordinary VLANs; do not lower it unless the upstream network explicitly requires it.
8. Apply. Click Save and then Apply changes.
9. Add a management allow rule first. Navigate to Firewall > Rules > [new VLAN interface] and add a pass rule from your mgmt_hosts alias to this firewall. This guarantees GUI access if subsequent ruleset work goes wrong.
10. Add the zone-appropriate baseline. For a trusted LAN-type VLAN, add a pass from the subnet to any. For a DMZ, guest, or IoT VLAN, add a default deny plus a narrow allow list referencing only the upstream and downstream subnets that must be reachable.
11. Add DHCP if needed. Install the ISC DHCP service and create a scope on Services > ISC DHCPv4 > [interface]. Point DNS at the OPNsense Unbound resolver.
12. Configure the upstream switch. Set the OPNsense-facing port as a trunk with the new VLAN ID allowed. On the user-facing access ports, set them as access ports for the new VLAN ID and bounce the port to apply.
13. Confirm tagging with packet capture. At the OPNsense shell, run tcpdump -nei <parent_if> vlan <vlan_id> -c 20. You should see 802.1Q-tagged frames for the new VLAN arriving from the trunk.

Verification

• A device on the new VLAN receives the expected IP from the DHCP scope (or has the expected static IP).
• The device can ping the VLAN interface IP at OPNsense (ping 10.30.0.1).
• ifconfig <vlan_if> at the OPNsense shell shows the configured address and status: active.
• Packet capture on the parent interface confirms tagged frames for the new VLAN (tcpdump -nei <parent> vlan <vlan_id>).
• Live View (Firewall > Log Files > Live View) filtered to the VLAN interface shows expected pass/block decisions.

Rollback

• Disable the OPT interface and remove its assignment from Interfaces > Assignments; apply.
• Delete the VLAN from Interfaces > Other Types > VLAN; apply.
• Restore the pre-change encrypted config backup if alias or other related changes were made.
• Revert the switch port configuration to the prior trunk/access state.
• Verify the parent NIC and any other VLANs on it remain functional.

Escalation

• Escalate to the network team if the switch port is not trunking the VLAN: suspect VLAN allowed list mismatch, native VLAN mismatch, or trunk disabled on the port.
• Escalate to the platform team if the parent NIC does not show the VLAN at all; check NIC driver support for 802.1Q (rare on supported hardware).
• Escalate if you accidentally placed the management interface on the new VLAN and lost GUI access: use the OPNsense console menu option to reset web GUI access or to assign the management VLAN explicitly.
• Escalate to security if the new VLAN carries traffic that crosses trust boundaries; require a documented firewall ruleset before allowing inter-VLAN routing.