WiFi

NET-01 // WIFI

FreeBSD has solid WiFi support for many common chipsets, but some modern cards — particularly MediaTek, newer Realtek, and some Qualcomm parts — lack native FreeBSD drivers. Wifibox bridges that gap by running a tiny Alpine Linux VM via bhyve, passing the PCI WiFi card through, and transparently bridging the connection back to the host.

The FreeBSD WiFi Situation

Cards with native FreeBSD drivers (Intel iwm/iwlwifi, Atheros, older Broadcom) work with the standard wlan0 interface and wpa_supplicant out of the box. Cards without native drivers appear in pciconf -lv as none@pci... — unattached, no driver.

For unattached cards, wifibox is the recommended path. It is transparent: after setup, wifibox0 behaves like any other network interface.

Run pciconf -lv | grep -B5 "802.11" to see your WiFi hardware and whether it has an attached driver.

wifi-setup

wifi-setup handles detection, installation, and configuration of wifibox. It auto-detects your card’s vendor and selects the correct wifibox package.

# Check current status and hardware
wifi-setup status

# Install wifibox for your card (auto-detects PCI address and vendor)
wifi-setup install

# Configure SSID and password
wifi-setup configure

# Start the service
wifi-setup start

# Stop the service
wifi-setup stop

What install does

1. Finds the unattached PCI WiFi device (pciconf -lv)
2. Selects the correct wifibox package based on vendor (see table below)
3. Installs the package via pkg
4. Adds pptdevs="N/N/N" to /boot/loader.conf for PCI passthrough
5. Adds vmm_load="YES" to /boot/loader.conf
6. Enables wifibox and configures wifibox0 for WPA+DHCP via sysrc

A reboot is required after wifi-setup install — PCI passthrough only takes effect at boot.

wifi-manager

wifi-manager is an interactive WiFi tool that works with both native wlan0 and wifibox wifibox0. It auto-detects which interface to use.

# Interactive network picker (uses fuzzel)
wifi-manager

# Scan for networks
wifi-manager scan

# Show connection status
wifi-manager status

# Connect directly
wifi-manager connect "MyNetwork" "password"

# List saved networks
wifi-manager list

# Disconnect
wifi-manager disconnect

The interactive picker (wifi-manager with no arguments) scans for networks and opens a fuzzel selector. Select a network, enter the password, and it connects.

How Wifibox Works

Wifibox runs a minimal Alpine Linux virtual machine using bhyve. The VM boots in under a second and presents a standard wpa_supplicant interface internally. The WiFi card is passed through directly to the VM via the ppt (PCI passthrough) driver — the FreeBSD kernel hands the device over entirely.

Inside the VM, Linux drivers manage the card. The VM then bridges the connection back to the host via a tap interface, which appears as wifibox0. From the host’s perspective, wifibox0 is an ordinary Ethernet-style interface with a DHCP address.

Host FreeBSD
  └── bhyve VM (Alpine Linux)
        └── Linux WiFi driver (e.g. mt7921e)
              └── WiFi card (PCI passthrough)
  wifibox0 (tap bridge) ←──────────────────┘

Credentials are stored in /usr/local/etc/wifibox/wpa_supplicant/wpa_supplicant.conf on the host and are passed into the VM at startup.

Supported Chipsets

Vendor / Chipset	Package	Notes
MediaTek MT7921, MT7922, MT7925	wifibox-mediatek	MT7921 at PCI 3/0/0 confirmed working
Intel Wi-Fi 6/6E (AX200, AX210, BE200)	wifibox-iwlwifi	Also covers older iwlwifi cards
Qualcomm / Atheros (ath11k)	wifibox-ath11k	QCA6390, WCN685x series
Broadcom (newer)	wifibox-brcm	Cards not supported by native bwn/bwi
Realtek RTW89 series	wifibox-rtw89	RTL8852AE, RTL8851B, etc.

Cards with native FreeBSD drivers do not need wifibox. Intel cards supported by if_iwm or if_iwlwifi in base FreeBSD can use either path.

Troubleshooting

No wifi hardware detected

pciconf -lv | grep -B5 "802.11" returns nothing. Check that the card is physically seated and visible in pciconf -l at all.

wifi-setup install finds no unattached device

Your card may already have a native driver attached (shown as iwm0@pci... rather than none@pci...). Use wifi-manager directly in that case.

No IP after reboot

Wifibox starts but wifibox0 has no IP. Check credentials with wifi-setup configure (re-run to overwrite), then wifi-setup start.

vmm not loading

If bhyve fails to start, ensure VT-x / AMD-V is enabled in BIOS/UEFI firmware settings. Verify with kldload vmm && echo ok.

Checking wifibox status

# Service state
service wifibox status

# Interface state
ifconfig wifibox0

# Full status via wifi-setup
wifi-setup status