FreeBSD 15 – bhyve VM start fails because tap interface permissions are incorrect

📖 ~1 min read

Table of contents

1. Symptom & Impact
2. Environment & Reproduction
3. Root Cause Analysis
4. Quick Triage
5. Step-by-Step Diagnosis
6. Solution – Primary Fix
7. Solution – Alternative Approaches
8. Verification & Acceptance Criteria
9. Rollback Plan
10. Prevention & Hardening
11. Related Errors & Cross-Refs
12. References & Further Reading

Symptom & Impact

bhyve launch exits immediately with tap/open errors, leaving tenant workloads offline.

Environment & Reproduction

Common after host hardening changes, devfs policy updates, or user/group drift.

kldstat | egrep 'vmm|if_tap|nmdm'
ls -l /dev/tap*
bhyvectl --vm= --destroy || true

Root Cause Analysis

Runtime account cannot access tap devices due to missing group membership or restrictive devfs rules.

Quick Triage

Confirm required kernel modules and launcher account privileges.

pw groupshow wheel
id 
service devfs status

Step-by-Step Diagnosis

Trace vm launch with verbose output and inspect device node permissions.

bhyve -AHP -c 1 -m 512M -s 0,hostbridge -s 3,virtio-net,tap0 
stat /dev/tap0
devfs rule showsets

Solution – Primary Fix

Adjust devfs rules and user groups, then recreate tap interfaces cleanly.

pw groupmod network -m 
ifconfig tap0 destroy || true
ifconfig tap create
service devfs restart

Solution – Alternative Approaches

Run bhyve under privileged orchestration account with audited command wrappers.

doas -u root vm-bhyve start 
vm-bhyve list

Verification & Acceptance Criteria

VM boots and receives network connectivity through tap-backed interface.

vm-bhyve start 
ifconfig tap0
ping -c 3 

Rollback Plan

Revert account and devfs rule changes if broader permission scope is detected.

pw groupmod network -d 
cp /root/backup/devfs.rules /etc/devfs.rules
service devfs restart

Prevention & Hardening

Maintain documented bhyve baseline including module, devfs, and group prerequisites.

sysrc kld_list+=' vmm if_tap nmdm'
service kld restart || true

Related Errors & Cross-Refs

Similar startup failures appear with missing bridge membership or stale bhyvectl state.

Related tutorial: View the step-by-step tutorial for freebsd-15.

View all freebsd-15 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

bhyve man pages, vm-bhyve docs, and FreeBSD virtualization handbook notes.