The Handbook

    Theme
    • Guides
        • Check a system before installing FreeBSD
        • Orient a Linux administrator on FreeBSD
        • Supported FreeBSD releases
        • Choose a FreeBSD documentation and support channel
        • Move files safely without GNU mv -t
        • Update and Upgrade FreeBSD
        • Upgrade 14.4 or 15.0 to FreeBSD 15.1
        • Choose packages, ports, or poudriere
        • Choose the quarterly or latest package branch
        • Choose a FreeBSD download or package mirror
        • Convert a test installation to pkgbase
        • Make a system setting persistent
        • Run a command from cron reliably
        • Configure locale, keyboard, and time zone
        • Configure a serial console for recovery
        • Choose a custom kernel, module, or loader setting
        • Run a Linux binary with the compatibility layer
        • Check desktop and laptop hardware before installation
        • Choose and check a graphics driver
        • Choose Xorg or Wayland
        • Build a maintainable desktop baseline
        • Install and check a desktop browser
        • Install GNOME and troubleshoot graphical login
        • Check laptop Wi-Fi, power, and suspend
        • Check multimedia readiness
        • Choose and configure a printing stack
        • Run Windows applications with Wine
        • Snapshot and replicate a ZFS dataset
        • Choose a filesystem and storage layout
        • Operate ZFS without losing the recovery path
        • Restore files from a ZFS snapshot
        • Find what is using ZFS space
        • Grow a ZFS virtual disk
        • Read ZFS pool health and run a scrub
        • Replace a failed device in a ZFS mirror
        • Replicate a ZFS dataset over SSH
        • Test changes in a writable ZFS clone
        • Read a ZFS pool from another FreeBSD system
        • Change PF safely on a remote host
        • Configure a narrow WireGuard tunnel
        • Share a directory with NFS
        • Share files with a named Samba account
        • Plan a FreeBSD home server
        • Choose a mail server or an outgoing relay
        • Publish a network service safely
        • Choose a jail network model
        • Choose native jails or a jail manager
        • Choose a jail or a bhyve virtual machine
        • Establish a FreeBSD security baseline
        • Choose a MAC policy
        • Audit security-relevant activity
        • Start a DTrace performance investigation
    • Integrations
        • Create a first jail with Bastille
        • Compare jail managers and OCI tooling
        • Publish a Bastille service through PF
        • Mount a ZFS dataset in a Bastille jail
        • Update and upgrade Bastille jails
        • Back up and restore a Bastille jail
        • Prepare bhyve and vm-bhyve
        • Install a Linux guest with vm-bhyve
        • Choose NFS or Samba for file sharing
        • Choose ZFS backup automation
        • Build a first signed poudriere repository
        • Operate a signed poudriere repository
        • Manage FreeBSD configuration with Ansible or Salt
        • Run Motion with webcamd on FreeBSD
        • Design a reverse proxy, certificates, and monitoring
    • FAQ
      • Troubleshooting
          • Recover an interrupted freebsd-update run
          • Resolve a package repository or ABI mismatch
          • Diagnose the FreeBSD boot path
          • Recover with a ZFS boot environment
          • Diagnose DNS, routing, and firewall paths
          • Diagnose network mbuf exhaustion
          • Bind a service to a low port without running it as root
          • Diagnose a service that will not start
          • Diagnose audio output or input
          • Diagnose webcamd, cuse, and a webcam
          • Fix USB device permissions without opening every device
      • About this handbook
      • Synopsis
      • Prepare the template and installer
      • Create and install the guest
      • Verify the installed system
      • References

      Install a Linux guest with vm-bhyve

      Last reviewed
      21 November 2026
      Applies to
      15.1-RELEASE
      Tested on
      15.1-RELEASE

      Synopsis #

      Install an amd64 Alpine Linux guest using vm-bhyve’s UEFI loader. First complete bhyve and vm-bhyve preparation , including a working datastore and a switch with the network access the guest needs.

      The example uses a switch named public, a 16 GiB guest disk, and 1 GiB of RAM. The guest is separate from FreeBSD’s Linux compatibility layer : it boots its own Linux kernel.

      Prepare the template and installer #

      Install UEFI firmware:

      # pkg install bhyve-firmware
      # vm switch list
      

      In the datastore’s .templates directory, create alpine.conf with these settings:

      loader="uefi"
      cpu="1"
      memory="1G"
      network0_type="virtio-net"
      network0_switch="public"
      disk0_type="virtio-blk"
      disk0_name="disk0.img"
      graphics="yes"
      graphics_listen="127.0.0.1"
      xhci_mouse="yes"
      

      Use the actual prepared switch name. Download the x86_64 Virtual ISO and its SHA-256 checksum from Alpine Linux . The commands below use version 3.24.4; use the filenames and checksum for the selected release:

      # vm iso https://dl-cdn.alpinelinux.org/alpine/v3.24/releases/x86_64/alpine-virt-3.24.4-x86_64.iso
      

      Run sha256 on the downloaded file in the datastore’s .iso directory and compare it with Alpine’s published checksum before booting it.

      Create and install the guest #

      # vm create -t alpine -s 16G alpine
      # vm install alpine alpine-virt-3.24.4-x86_64.iso
      # vm list
      # vm info alpine
      

      Find the VNC port in the output. It listens only on the FreeBSD host’s loopback address. From a workstation, forward that port through SSH; for example, if it is 5900:

      $ ssh -N -L 5901:127.0.0.1:5900 admin@FREEBSD_HOST
      

      Connect a VNC client to 127.0.0.1:5901 to release the installer’s firmware screen. Alpine’s Virtual image sends its login prompt to the serial console. On the FreeBSD host, connect with:

      # vm console alpine
      

      Log in as root and run:

      # setup-alpine
      

      Choose the keyboard, hostname, network settings, time zone, and a package mirror. Set passwords and create a normal user. Select vda, the guest’s virtual disk, and sys installation mode when prompted. This erases the selected guest disk; check its name and size before confirming.

      Shut down from inside Alpine after installation:

      # poweroff
      

      Once vm list shows the guest stopped, start it without the installer:

      # vm start alpine
      

      Verify the installed system #

      Reconnect with vm console alpine and log in. To detach without stopping the guest, press Enter and then ~.; through an SSH session, type ~~. instead. In Alpine, check the installed system, address, route, and name resolution:

      $ cat /etc/alpine-release
      $ uname -r
      $ ip address
      $ ip route
      $ nslookup alpinelinux.org
      

      A private vm-bhyve switch does not provide DHCP or Internet access by itself. If the guest has no address or default route, check that network’s DHCP or static configuration before changing the virtual disk or boot loader.

      From the FreeBSD host, request a clean stop and restart:

      # vm stop alpine
      # vm list
      # vm start alpine
      

      Wait until it is stopped before starting it again. Confirm that the installed system boots and its files persist. Add autostart only after these checks succeed. A forced poweroff is for an unresponsive guest, not normal shutdown.

      References #

      • vm-bhyve documentation
      • Alpine installation guide
      • bhyve(8)

      Independent documentation. Not affiliated with or endorsed by the FreeBSD Project or the FreeBSD Foundation.

      Report a bug
      • Synopsis
      • Prepare the template and installer
      • Create and install the guest
      • Verify the installed system
      • References