VLANs and guest networking

Segment guest traffic with IEEE 802.1Q tags. Successful isolation depends on three layers working together:

1. Upstream switch port mode (access vs trunk) and allowed VLAN IDs.
2. Host Linux networking (bridges, optional VLAN subinterfaces, bridge VLAN filtering).
3. Guest attachment — how the virtual NIC is defined (untagged vs tagged) when the VM is created.

Scope of this page

This guide explains networking models and host diagnostics accurately. Product UI labels for VLAN fields in Electros or AtomOS GUI may vary by release; see Feature availability.

Network models (do not confuse them)

Model	What it does	What it does not do
Access port (switch)	Untagged frames; switch assigns one VLAN	Carry multiple tenant VLANs on one link
Trunk port (switch)	Tagged frames for an allowed VLAN list	Replace correct host or guest config
Linux VLAN subinterface (eno1.100, br0.100)	Host L3/L2 endpoint for one VLAN ID on a parent device	Automatically tag per-VM traffic
VLAN-aware bridge / bridge VLAN filtering	Bridge ports have PVID / tagged membership	Appear just because nmcli created a VLAN iface
Per-port VLAN membership	Each bridge port (including vNIC taps) belongs to specific VLANs	Happen without explicit bridge or libvirt configuration
Untagged guest + host tagging	Guest sends untagged frames; host/switch maps them to a VLAN	Prove isolation without testing
Tagged guest traffic	Guest or virt stack emits 802.1Q tags	Work if the trunk disallows that ID
libvirt network VLAN XML	<vlan> / <tag> elements on the interface definition	Substitute for switch trunk allow-lists

Creating a host VLAN interface with NetworkManager is host configuration. It is not by itself “per-VM VLAN tagging in AtomOS.”

How AtomOS guests can carry VLAN metadata

Compute provisioning can attach VLAN information to the guest network definition used by libvirt. Supported shape (conceptual fields from the AtomOS compute stack):

Field	Role
vlan.trunk	When true, VLAN element is emitted as a trunk
vlan.tags	One or more VLAN IDs associated with the interface
vlan.native_tag	Untagged / native VLAN ID when used
vlan.native_mode	Required when native_tag is set (libvirt nativeMode)

Validation rejects incomplete combinations (for example native_tag without native_mode). Exact Electros form fields map onto this model — use the UI or API your release documents.

flowchart TB
  SW[Switch trunk / access]
  PHY[Host physical NIC]
  BR[Linux bridge]
  VNIC[Guest vNIC]
  GUEST[Guest OS]
  SW --> PHY --> BR --> VNIC --> GUEST

Guest vNICs attach to a host bridge. Tags may be applied in the libvirt interface XML, on bridge ports, via VLAN subinterfaces, or only on the upstream switch — your design must pick one coherent model.

Host bridge and management safety

AtomOS install and atomos-cli --bridge-setup typically attach a physical NIC to a Linux bridge (often br0). Prefer:

• Separate management NIC for SSH / Electros.
• Guest bridge NIC for VM traffic.
• BMC / IPMI / iDRAC / iLO before changing the only remote path.

Disruptive

Moving the active management address onto a bridge can drop SSH. Use out-of-band console access. See Networking.

Switch side

Port type	Configuration
Access	One VLAN; untagged toward the host
Trunk	Allowed VLAN list; tagged frames toward the host

Missing VLAN IDs on the trunk are the most common cause of “link up, no gateway.”

Example: host VLAN subinterface (generic Linux only)

Example only

These commands create a host VLAN interface. They do not configure guest libvirt VLAN XML. Adapt names; prefer atomos-cli --bridge-setup for the initial AtomOS bridge.

# VLAN 100 as a host interface on physical eno1 (example)
sudo nmcli connection add type vlan \
  con-name eno1.100 ifname eno1.100 \
  dev eno1 id 100

# Alternative pattern: VLAN interface whose parent is an existing bridge
# This still creates a HOST endpoint — not per-VM tagging by itself.
sudo nmcli connection add type vlan \
  con-name br0.100 ifname br0.100 \
  dev br0 id 100

Read-only diagnostics

ip -d link show
bridge vlan show
bridge link show
nmcli connection show

Use packet capture only where policy allows, for example tcpdump -i eno1 -nn -e vlan (replace eno1 with your interface).

Validation scenario (lab)

Target design:

Item	Expectation
VM A	Connected for VLAN 100; addressing in that subnet
VM B	Connected for VLAN 200; addressing in that subnet
Upstream	Trunk allows 100 and 200 (or separate access ports if that is your model)
Isolation	A cannot reach B’s L2/L3 unless a router intentionally interconnects the VLANs

Procedure outline:

1. Document switch port mode and allowed VLANs.
2. Confirm host bridge and (if used) VLAN membership with bridge vlan show.
3. Create or attach guests with the intended VLAN metadata in Electros / AtomOS GUI.
4. Assign IPs inside each guest for its VLAN.
5. Test same-VLAN connectivity (A↔peer on 100).
6. Test cross-VLAN isolation (A↛B) without a router.
7. Optional: capture to confirm tags on the trunk.

Do not assert isolation for production until this lab passes on your release and switches.

Troubleshooting

Symptom	Checks
Link up, no DHCP / gateway	Trunk allow-list, access VLAN, DHCP relay
Wrong tenant network	Wrong tag in guest definition or bridge PVID
Host VLAN iface up, guests still mixed	Host subinterface ≠ guest tagging — review libvirt/Electros network object
Intermittent loss	STP, MTU (tag overhead), bond misconfig
Host unreachable after bridge change	Management IP moved; recover via BMC

Related pages

• Networking & certificates
• VMs & Electros
• Feature availability
• Diagnostic commands