Configure Wi-Fi Roaming and Wired Failover

Synopsis #

OpenBSD can maintain an auto-join list of wireless networks and select an available access point automatically. A trunk(4) interface can combine Ethernet and Wi-Fi in failover mode so that Ethernet is preferred whenever it has link.

The wired and wireless connections in this procedure must reach the same Layer 2 network. Do not use a failover trunk when the two interfaces connect to different IP networks, different security zones, or unrelated Internet services.

Identify Interfaces and Firmware #

This example uses em0 for Ethernet and iwm0 for Wi-Fi. Determine the actual names with ifconfig(8) and dmesg(8) :

ifconfig
  # List attached interfaces
dmesg | grep -E '^(em|iwm)[0-9]'
  # Match example driver names to hardware

Install required wireless firmware with fw_update(8) before configuring the trunk.

Configure Multiple Wireless Networks #

The hostname.if(5) file for the wireless member contains the join list but no IP configuration:

join home-net wpakey "replace-with-home-passphrase"
join office-net wpakey "replace-with-office-passphrase"
join guest-net
up

Place the lines in /etc/hostname.iwm0 and restrict the file because it contains credentials:

doas chown root:wheel /etc/hostname.iwm0
  # Keep administrative ownership
doas chmod 600 /etc/hostname.iwm0
  # Prevent other users from reading WPA keys

Line order does not define network precedence. OpenBSD evaluates matching candidates by criteria that include security and connection quality. An open network entry should be included only when its use is intentional.

Configure the Ethernet Member #

Create /etc/hostname.em0 with:

up

Neither physical member receives an IP address. The trunk owns the DHCP lease and resolver proposals.

Create the Failover Trunk #

Create /etc/hostname.trunk0:

trunkproto failover
trunkport em0
trunkport iwm0
inet autoconf
inet6 autoconf

The first port is the master. Traffic uses em0 while its link is active and moves to iwm0 when Ethernet becomes unavailable. dhcpleased(8) configures IPv4 on trunk0; slaacd(8) handles IPv6 autoconfiguration.

Apply the configuration with netstart(8) :

doas sh /etc/netstart em0 iwm0 trunk0

A reboot is the clearest final test because it verifies configuration order from a clean state.

Verify Roaming and Failover #

Inspect the wireless join list and trunk state:

ifconfig iwm0
  # Confirm the selected wireless network and link state
ifconfig trunk0
  # Confirm member ports, active port, addresses, and link state
route -n show
  # Confirm the default route
cat /etc/resolv.conf
  # Confirm the resolver proposals selected by resolvd

With both links connected, em0 should be active. Unplug Ethernet and inspect trunk0 again. Existing connections may pause or fail when the access path changes, especially if the network assigns a different lease or filters by MAC address.

Reconnect Ethernet and verify that it resumes the master role.

Override Wireless Selection Temporarily #

Select an entry already present in the join list:

doas ifconfig iwm0 nwid office-net

Return to automatic selection:

doas ifconfig iwm0 -nwid

These runtime commands do not change /etc/hostname.iwm0.

Troubleshooting #

  • If iwm0 has no link, inspect the join list, signal level, firmware, and driver messages.
  • If trunk0 has no IPv4 address, confirm that inet autoconf appears only on the trunk and inspect its lease with dhcpleasectl -l trunk0.
  • If DNS fails after a transition, inspect route proposals and /etc/resolv.conf. resolvd(8) merges current DNS proposals.
  • If Ethernet and Wi-Fi reach different networks, remove the trunk and configure them as independent interfaces with an explicit routing policy.
  • If a network restricts access by MAC address, account for the trunk interface’s link-layer identity.

See Networking for static addressing, resolver ownership, routes, and broader wireless configuration.

Report a bug