Virtualization

Synopsis #

OpenBSD provides the vmm(4) hypervisor, vmd(8) management daemon, vmctl(8) control utility, and vm.conf(5) persistent configuration. Create a serial-console guest, configure its network and startup settings, and learn how to stop, back up, and recover it.

Supported guests are OpenBSD and Linux systems with serial consoles. OpenBSD 8.0 supports guest SMP with up to 64 virtual CPUs per VM; the default is one. Graphics, snapshots, hardware passthrough, live migration, and live hardware changes are not available. Consult vm.conf(5) and vmctl(8) for release-specific configuration and limits.

Confirm Host Support #

vmm is available on supported amd64 systems with hardware virtualization and nested paging. Firmware settings may need to enable the feature. Check the processor flags:

dmesg | egrep '(VMX/EPT|SVM/RVI)'

VMX/EPT identifies the required Intel facilities; SVM/RVI identifies the AMD equivalents. Check for EPT or RVI as well as the virtualization feature.

After changing firmware settings, install the separately distributed vmm firmware with fw_update(8) :

doas fw_update

Plan host memory, storage, CPU, and network capacity before starting guests. Guest memory is also constrained by the datasize limit for the vmd service account in login.conf(5) .

Enable vmd #

Use rcctl(8) rather than editing rc.conf.local directly:

doas rcctl enable vmd
  # Enable the daemon at boot
doas rcctl start vmd
  # Start it now
doas rcctl check vmd
  # Confirm that it remains running

When the host shuts down, vmd requests clean shutdown through vmmci(4) and waits before forcing termination. Adjust the service timeout only after measuring guest shutdown behavior.

Prepare Guest Storage and Installation Media #

Create a protected directory and a sparse qcow2 disk:

doas install -d -o root -g wheel -m 700 /var/vm
  # Create the VM storage directory
doas vmctl create -s 40G /var/vm/example.qcow2
  # Create a 40 GB qcow2 disk image

Download and verify an installation ISO from the guest operating system’s authoritative source. For an OpenBSD 8.0 guest, use the verified-media procedure in Installing OpenBSD . Use the matching verified ISO filename in the commands below.

Start the Installer #

Start a guest with two virtual CPUs, one gigabyte of memory, one local network interface, the installation ISO, and the prepared disk:

doas vmctl start -c -p 2 -m 1G -L -r INSTALL_ISO -d /var/vm/example.qcow2 example

INSTALL_ISO is a placeholder for the verified image path. -c attaches the serial console, and -p 2 selects two virtual CPUs. Size the CPU count for host capacity and guest workload; omitting -p uses one CPU. -L gives the guest one local interface with an address supplied by vmd. The guest sees a vio(4) network device and the host sees a tap(4) device.

Configure the guest installer to use its serial console. Disconnect from a vmctl console session with ~.. When the console is reached through SSH, the SSH escape processing requires ~~..

Inspect the running guest from a separate terminal:

doas vmctl status
  # List configured and running VMs
doas vmctl console example
  # Reattach to the named guest console

Make the Guest Persistent #

After installation, define the guest in /etc/vm.conf:

vm "example" {
    cpus 2
    memory 1G
    enable
    disk "/var/vm/example.qcow2"
    local interface
}

Validate the complete configuration before loading it:

doas vmd -n
  # Parse /etc/vm.conf without starting another daemon
doas vmctl reload
  # Remove stopped definitions and load the validated configuration

Running guests do not receive all configuration changes during reload. Stop a guest cleanly before relying on changed memory, disk, or interface settings.

The enable keyword starts the VM when vmd loads the configuration. Use disable when startup must remain manual.

Configure Local Networking #

A local interface allocates a host/guest address pair from 100.64.0.0/10 and provides DHCP/BOOTP to the guest. The host-side tap address becomes the guest’s default route and resolver address.

The vmm local-interface path from guest to InternetA guest vio interface receives an address from vmd using DHCP. It connects to a host tap interface whose address is the guest default gateway. The local pair uses 100.64.0.0/10. Reaching the Internet additionally requires host IPv4 forwarding, PF ingress and egress permission, and outbound NAT on egress. The host tap interface is not a virtual switch or an automatic Internet connection.A local interface is the first linkAddress pair from 100.64.0.0/10Guest: vio interfaceAddress supplied by vmd via DHCPHost network stackHost: tap interfaceIts address is the guest default gatewayRequired for outside accessIPv4 forwarding + PF in/out policyOutbound NAT on egressHost: egress interfaceInternetDashed path requires the host routing policy.
A local interface connects the guest to the host. Reaching the Internet also requires host forwarding, PF policy, and outbound NAT.

Local networking alone does not provide Internet access. To route guest IPv4 traffic, enable forwarding and add PF policy that is consistent with the host’s complete ruleset:

net.inet.ip.forwarding=1

In /etc/pf.conf, a minimal outbound translation rule is:

pass out on egress from 100.64.0.0/10 to any nat-to (egress)

Parse the complete PF ruleset before loading it:

doas pfctl -nf /etc/pf.conf
  # Check syntax without changing the active ruleset
doas pfctl -f /etc/pf.conf
  # Load only after the full policy and recovery path are verified

This is only the egress and translation half of the policy. A default-block ruleset also needs an explicit, suitably restricted pass in policy on the relevant tap interface or interface group before guest packets can reach egress. Restrict that rule to the intended guests, destinations, and ports. Avoid granting guests access to unrelated host services. DNS redirection, inbound publication, and inter-guest policy are separate decisions.

Use a Virtual Switch for Explicit Topologies #

For host-only, segmented, or physical-network attachment, create a supported veb(4) and optional vport(4) topology, then reference it from a switch block. Do not copy old examples that add an addressed physical interface directly to bridge0; a veb port is disconnected from the host IP stack and host addressing belongs on a vport when the host must participate.

The official virtualization FAQ documents four current patterns:

  • local host/guest networking;
  • local networking with NAT;
  • a controlled virtual switch using veb and vport;
  • attachment to a real Ethernet network.

Bridging to a real network works with Ethernet, not a Wi-Fi client interface. Preserve console access while moving host addresses between physical and virtual interfaces because a mistake can remove host connectivity.

Operate Guests Safely #

Request a clean stop and wait for completion:

doas vmctl stop -w example

Use -f only when the guest cannot shut down and data-loss risk has been accepted. Pause is not a durable backup or shutdown state.

Inspect guest state and host logs when an operation fails:

doas vmctl status example
  # Inspect the VM state
doas tail -n 100 /var/log/daemon
  # Review recent vmd diagnostics
doas ifconfig -g tap
  # Inspect host-side guest interfaces

Do not assume a command from another hypervisor exists in vmctl. The current manual documents create, start, stop, console, pause, unpause, status, load, reload, reset, and wait operations.

Back Up and Restore a Guest #

Copying a running VM disk can leave incomplete writes in the backup. Use the application’s backup tools inside the guest, or shut down the guest before copying its complete disk image:

  1. shut the guest down cleanly;
  2. confirm vmctl status no longer reports it as running;
  3. copy the disk image and /etc/vm.conf to independent storage;
  4. verify the backup and periodically restore it under another VM name;
  5. retain guest encryption keys and application recovery material separately.

vmm does not provide VM snapshots. Copy disk images only after the guest has stopped.

Recover a Failed Guest #

Separate host, configuration, boot, disk, and guest-network failures:

  • If vmd does not start, run vmd -n, inspect firmware availability, and review daemon logs.
  • If the guest is undefined, verify /etc/vm.conf, reload it, and inspect vmctl status.
  • If the guest does not boot, attach the console and use verified installation media for guest recovery.
  • If the disk image is damaged, stop write attempts and restore the tested copy.
  • If networking fails, inspect the guest vio device, host tap device, forwarding state, PF state, and the selected local or switch topology in order.

Troubleshoot PF, NAT, and Routing provides the packet path workflow. Plan a Docker Workload Migration to OpenBSD explains when a Linux guest is appropriate for a workload that requires Linux container interfaces.

Report a bug