FreeBSD VLAN Interfaces: 802.1Q Configuration and Verification

A FreeBSD VLAN interface is a logical Layer-2 interface that tags or demultiplexes Ethernet frames over a physical parent. It does not create a VLAN in the switch, assign a subnet, or guarantee that a frame is allowed across an upstream trunk. A successful local ifconfig command proves only that the host accepted the configuration. Production validation must trace the tag through the NIC driver, switch port, routed gateway, and expected client network.

This guide concentrates on host-side 802.1Q operations. It treats VLAN IDs, address plans, and switch settings as inputs owned by the network design. Replace the documentation addresses and interface names below with values verified from inventory; a wrong tag on a live management interface can cut off the host just as effectively as a bad default route.

Establish the parent and trunk contract

Identify the actual NIC using ifconfig -a, pciconf -lv, and the interface’s MAC address. Do not infer the switch port from a familiar name such as em0; device order can change after hardware or firmware changes. Confirm that the driver supports VLAN operation using vlan(4) and the NIC driver’s manual. Inspect media, link state, offload capabilities, and counters before adding the logical interface.

Before changing the host, obtain the intended parent interface, tag, native/untagged behavior, allowed VLAN list on the switch trunk, subnet/prefix, gateway, address allocation method, and MTU from the network owner. A trunk and an access port are not interchangeable. On an access port the switch may deliver untagged traffic for one configured VLAN; a host VLAN interface expects tagged frames unless the switch has been configured to tag the traffic in a compatible way. Do not assign the same Layer-3 address to the parent and child without an explicit design.

ifconfig -a
ifconfig -m igb0
ifconfig igb0
netstat -I igb0 -w 1

-m reports supported media choices/capabilities; it is not a complete proof that the upstream trunk carries the desired VLAN. Record the base interface’s link state and counters so that a later test can distinguish a physical carrier problem from a tag or address problem. If this is the management path, arrange console or out-of-band access before touching its parent configuration.

Create and test a tagged interface at runtime

FreeBSD creates VLAN interfaces through interface cloning. The Handbook shows a name derived from the physical interface and tag, such as em0.5; the vlan(4) manual documents the creation options. For an igb0 parent and a network-assigned tag 120, a controlled runtime example is:

ifconfig igb0 up
ifconfig igb0.120 create vlan 120 vlandev igb0
ifconfig igb0.120 inet 192.0.2.40/24 up

192.0.2.40/24 is an RFC 5737 documentation address and will not work on a real network. Substitute an address that has been reserved for this host. The parent must be up for traffic, and the VLAN child carries the tag association. On a trunk-only parent, it is common for the parent to have no Layer-3 address; the Layer-3 address belongs on the intended VLAN child. The interface name and numeric tag should agree so that operators can identify the mapping later.

Verify the result, not just the command exit status:

ifconfig igb0
ifconfig igb0.120
ifconfig -v igb0.120
route -n get default
arp -an

Inspect the VLAN ID and parent reported by the child, its UP/RUNNING state, assigned address, and routes. A locally assigned address does not prove the gateway can see tagged frames. Use a known peer on that VLAN, test the intended protocol and address family, and capture on the parent or child when the packet path is unclear. The driver and capture point can expose offloaded packets differently from the wire, so correlate with a switch counter or an independent host where possible.

Persist the topology using rc.conf

Once runtime behavior is confirmed, express the same topology in /etc/rc.conf. FreeBSD’s network rc scripts support a vlans_<parent> list and per-child ifconfig_<parent>_<tag> settings. Keep the parent explicitly up and place the address only where the network design expects it.

# /etc/rc.conf; replace interface, tag, and documentation address
ifconfig_igb0="up"
vlans_igb0="120"
ifconfig_igb0_120="inet 192.0.2.40/24"

For multiple children on one trunk, add tags to the parent’s list and configure each child separately. Avoid rebuilding a long cloned_interfaces value by hand if another service owns it. Use sysrc for individual variables when the values are simple; review the resulting configuration and preserve unrelated VLAN definitions. If a renamed child interface or a more complex create_args_ setup is required, follow the current rc.conf(5) and Handbook forms rather than mixing configuration styles without a reason.

Apply a network change through a maintenance path. Restarting the whole netif service can interrupt jails, bridges, storage traffic, wireless interfaces, or the remote session. A remote host should have console access and a rollback command prepared before configuration changes. For an interface-specific test, use service netif only with the syntax supported by the release, then verify all expected parent and child interfaces again. A reboot test is valuable after runtime validation, but it should happen only after the rollback and console path are proven.

Understand MTU and offload interactions

An 802.1Q tag adds link-layer information to an Ethernet frame. Whether the host NIC can transmit/receive tagged frames at the expected MTU, whether VLAN hardware tagging is enabled, and what packet representation a capture shows depend on the driver and hardware. Do not assume that every NIC supports every VLAN offload or that a visible checksum warning means the frame left the wire incorrectly. Inspect ifconfig -m, the driver’s manual, and relevant vlan(4) caveats.

An MTU mismatch often appears as a path that passes small pings but fails large transfers or particular protocols. Test with an explicit packet size and no-fragmentation option appropriate to the selected address family, then compare the configured MTU on parent, child, switch, and routed path. Do not lower MTU blindly: that can mask the point where a tag, tunnel, or encapsulation adds overhead. If an offload change is warranted, change one capability at a time during a window and measure both throughput and errors before/after.

Use counters to detect where traffic stops. Rising input errors on the physical parent point toward a different class of failure than zero child traffic with a healthy carrier. On the switch, confirm the tag is allowed and that the port is actually in trunk mode; compare transmit/receive counters on both sides. A VLAN that carries ARP but not larger application traffic can still be impaired by MTU, filtering, or asymmetric trunk configuration.

Route and resolve traffic on the correct interface

The VLAN child is a normal network interface for address assignment and routing. Once it has an address, inspect the connected route, default route, and source address selected for representative destinations. Multiple VLANs can be on one parent but still require separate route policy, firewall rules, DNS reachability, and service bindings. A host with several routed interfaces does not automatically choose the source address an application owner expects.

netstat -rn -f inet
route -n get 192.0.2.1
ping -c 3 -S 192.0.2.40 192.0.2.1
tcpdump -ni igb0 'vlan 120'

Use a real gateway address in place of the documentation address. ping -S selects a source address; it does not force a specific egress route if the routing table chooses another path. The packet capture filter is illustrative and depends on the capture interface and driver offload behavior. Where a link-local neighbor is unresolved, investigate the parent/trunk/tag path before editing DNS. If ARP or NDP succeeds but application traffic does not, move up the stack to routes, firewall policy, MTU, and service binding.

For IPv6, confirm that router advertisements arrive on the VLAN interface intended to receive them and that the IPv6 default route and neighbor entries are sensible. Do not enable acceptance on every child to compensate for a missing switch tag. Keep the VLAN mapping aligned with the router’s prefix and RA policy, then inspect ndp -an and netstat -rn -f inet6 after the test.

Diagnose common failure signatures

The child cannot be created. Verify that the interface name exists, the tag is in the valid operational range used by the network, the driver supports VLANs, and the syntax matches vlan(4) for the installed release. A physical interface that is absent from ifconfig -a is not repaired by changing a VLAN tag.

The interface is up but has no peer reachability. Check link carrier on the parent, VLAN ID and parent association on the child, switch trunk allow-list, native VLAN behavior, address/prefix, and the peer’s subnet. A host-side UP flag means the logical interface is administratively enabled; it does not prove any frame reached the switch.

The host works until reboot. Compare the tested runtime state to rc.conf, parent/child variable names, vlans_<parent> values, and the ordering/ownership of configuration management. Review boot messages for network interface setup errors and verify that a generator did not rewrite the file.

Small probes work and applications stall. Compare path MTU, offload capabilities, interface error counters, firewall state, and packet sizes. Capture at both endpoints when possible. Avoid changing MTU and offload at the same time, because doing so destroys causal evidence.

An unrelated service loses connectivity. Check whether its traffic used the parent or a child, whether the default route or source-address selection changed, and whether the network service restart touched a bridge, jail, or remote-storage path. Restore the last known-good configuration before layering more changes.

Define an acceptance test and change record

For each VLAN, maintain a small mapping record: host, physical parent and MAC, VLAN ID, switch port/trunk, child name, address method, subnet, gateway, MTU, firewall scope, and owner. This information should be consistent between the host’s rc configuration and network inventory. A tag number without its switch-side context is insufficient for troubleshooting.

Accept the change only after confirming (1) the parent carrier and supported VLAN behavior, (2) the exact tag and parent association, (3) the expected address and routes, (4) bidirectional peer connectivity over the intended services and MTU, and (5) persistence after a controlled reboot or interface reconfiguration. Record counter deltas and a packet trace for one known flow when the path is production-critical. Keep the rollback simple: restore the prior parent/child settings and confirm that the original management route is still reachable.

Treat VLAN creation as an end-to-end network change rather than a host-only command. A stable result depends on coordinated tagging, routing, address management, and operational ownership. Once those are documented and verified at each boundary, FreeBSD’s cloned VLAN interface provides a clean logical attachment without confusing it with an independent physical link.

Related:

Sources: