Network Segmentation on Deevnet Infrastructure Platform

Prerequisites & Preflight

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites & Preflight #

Vault #

All secrets are encrypted with Ansible Vault in the inventory. Decrypt before starting the migration and re-encrypt when done:

cd ansible-inventory-deevnet
make unvault # decrypt — run once before starting
# ... run migration steps ...
make vault # re-encrypt when migration is complete

Migration Artifact Capture #

Migration logs (preflight, each migration step, postcheck) are automatically captured in ansible-collection-deevnet.net/migration-logs/ with timestamps. Each make target produces a log file named YYYYMMDD-HHMMSS-<target>.log. No additional setup is required.

VLAN Foundation

Mon, 01 Jan 0001 00:00:00 +0000

VLAN Foundation #

Create the VLAN infrastructure on the router and switch. All steps in this phase are non-disruptive — no existing traffic is affected.

Step 2: OPNsense VLAN Interfaces #

Create VLAN sub-interfaces on OPNsense. This step is non-disruptive — it only adds new interfaces without affecting existing traffic.

Run:

cd ansible-collection-deevnet.net
make migration-opnsense-vlans

Verify:

OPNsense GUI -> Interfaces -> Devices -> VLAN
Confirm 11 VLANs created on the correct parent interface
Each VLAN shows the correct tag (10, 20, 25, 30, 31, 35, 40, 50, 51, 52, 99)

Rollback: Delete VLAN interfaces via OPNsense GUI -> Interfaces -> Devices -> VLAN -> delete each entry.

Builder Cutover

Mon, 01 Jan 0001 00:00:00 +0000

Builder Cutover to Management VLAN #

Move the builder (provisioner-ph01) from the flat network to VLAN 99 with a static IP. This eliminates the DHCP dependency — the builder’s eth0 is configured with a static address before its port moves to the new VLAN. After this step, the builder has routed access to all VLANs for the rest of the migration.

Prerequisites:

Step 4 complete (trunk uplink carrying tagged VLANs)

5a — Assign and configure OPNsense VLAN interfaces #

Assign all VLAN devices to OPNsense interface slots and configure gateway IPs. The OPNsense API does not support interface assignment (GitHub #7324), so the playbook will pause and prompt you to complete a manual GUI step before continuing with automated IP configuration.

Services & Routing

Mon, 01 Jan 0001 00:00:00 +0000

Services & Routing #

Configure DHCP, interface IPs, firewall rules, and trunk PVID. After this phase, all VLANs are fully routed and served.

**Post-cutover inventory:** All `make` targets from this point forward automatically use the `dvntm-new` inventory (target IPs on the new VLAN subnets). The builder is on VLAN 99 and can only reach devices at their new addresses. No manual `-i` overrides are needed.

Step 6: Test Second Port #

Test a non-builder port on a different VLAN to validate the trunk + VLAN path end-to-end.

Port Migration & Wireless

Mon, 01 Jan 0001 00:00:00 +0000

Port Migration & Wireless #

Move remaining switch ports to their assigned VLANs, perform the management cutover, adopt devices in Omada, and configure AP SSIDs.

Step 10: Migrate Remaining Access Ports #

Move all remaining switch ports to their assigned VLANs as defined in host_vars/access-sw01.yml.

**DNS:** New 10.20.x.x addresses will not resolve via DNS until post-migration ([Step 11](#step-11-management-cutover) / [Post-Migration](../post-migration/)). This is expected — Ansible uses inventory IPs directly. Use IP addresses for any manual verification during this step.

**Wireless clients:** AP SSID-to-VLAN mappings are not reconfigured in this step. When the AP's port moves to its target VLAN, wireless clients may lose connectivity. SSID configuration is handled in [Step 13](#step-13-ap-ssid-configuration) after Omada adoption ([Step 12](#step-12-omada-device-adoption)).

Run:

Post-Migration

Mon, 01 Jan 0001 00:00:00 +0000

Post-Migration #

After all steps complete and connectivity is verified:

Run automated post-migration validation:
```
cd ansible-collection-deevnet.net
make postcheck
```
Validates OPNsense VLANs, switch database/trunk, device reachability, gateway IPs, and builder state. All checks should show [PASS].
Run DNS and DHCP roles (must run before vault encryption):
```
cd ansible-collection-deevnet.net
make dns
make dhcp
```

Re-encrypt vault files:

cd ansible-inventory-deevnet
make vault

Remove old network config:
- Delete old 192.168.10.0/23 Kea DHCP subnet (if not already removed)
- Remove temp VLAN 99 DHCP pool (if not already removed)
- Remove old 192.168.10.0 LAN interface from OPNsense (Interfaces → LAN → clear IP or reassign)
- Remove any old static routes referencing 192.168.10.x
Ongoing switch management — use the switch target for day-2 operations:

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Troubleshooting & Known Issues #

Lost switch access after trunk configuration #

Connect via console cable
Check show interface switchport gigabitEthernet 1/0/1 for native VLAN mismatch
Revert to access mode on uplink if needed

Device not getting DHCP lease #

Kea not listening on VLAN interfaces: Check OPNsense GUI → Services → Kea DHCP → Settings → Interfaces. All VLAN interfaces must be selected. By default, Kea only listens on LAN (re0). The opnsense_dhcp role automates this, but verify with: ssh root@10.20.99.1 'cat /usr/local/etc/kea/kea-dhcp4.conf' and check the interfaces-config section.
Verify port VLAN assignment: show vlan brief
Verify DHCP subnet exists in OPNsense for that VLAN
Check OPNsense firewall rules allow DHCP on VLAN interface
Check show mac address-table to confirm device is on expected port

AP not discoverable or adoption fails in Omada #

Factory reset AP uses static fallback IP 192.168.0.254, not DHCP. Add temp IP on builder (sudo ip addr add 192.168.0.1/24 dev enp4s0) and access AP web UI at http://192.168.0.254 (admin/admin) to set inform URL.
Adoption timeout (errorCode -39002): AP can’t reach controller on required ports. Check ss -tlnp | grep 29814 — Omada must listen on TCP 29814 (not just UDP). Newer AP firmware (EAP650-Outdoor) requires TCP 29814 for v2 adoption.
Omada controller version mismatch: Controller 5.12.7 does not listen on TCP 29814. Update the controller to a version that supports v2 adoption protocol.
Firewalld missing ports: Verify sudo firewall-cmd --list-ports includes 29810-29814/udp AND 29811-29814/tcp.

Builder lost connectivity during Step 5 #

Verify ethernet cable is connected to gi1/0/16 — do not rely on WiFi for substrate access
Check port VLAN assignment: show interface switchport gigabitEthernet 1/0/16
Verify VLAN 99 interface is enabled with IP 10.20.99.1 in OPNsense
If the builder has the wrong static IP config, revert the port to VLAN 1 and re-run the builder playbook with the dvntm inventory
If the builder is unreachable, Omada adoption (Step 12) cannot proceed — but the switch and AP continue to function independently

Last resort: revert the builder port to VLAN 1 via console:

configure
interface gigabitEthernet 1/0/16
 switchport access vlan 1
end
copy running-config startup-config

Inter-VLAN routing not working #

Check default gateway on target device: Devices on VLAN 99 (management) need ip route 0.0.0.0 0.0.0.0 10.20.99.1 to route responses back to other VLANs. Without this, the device receives cross-VLAN traffic but replies are silently dropped (no return route). This was the root cause of the “builder can’t ping cross-VLAN gateways” issue — the switch had no default gateway.
Verify VLAN interfaces have IP addresses assigned in OPNsense
Check OPNsense firewall rules for inter-VLAN traffic
Verify routing table: OPNsense GUI -> System -> Routes

To Do #

Automation gaps and improvements identified during the initial migration run.