OpenBSD FAQ - Virtualization [FAQ Index]

Introduction

OpenBSD comes with the vmm(4) hypervisor and vmd(8) daemon. Virtual machines can be orchestrated with the vmctl(8) control utility, using configuration settings stored in the vm.conf(5) file.

The following features are available:

The following features are not available at this time: Supported guest operating systems are currently limited to OpenBSD and Linux. As there is no VGA support yet, the guest OS must support serial console.

Prerequisites

A CPU with nested paging support is required to use vmm(4). Support can be checked by looking at the processor feature flags: SLAT for AMD or EPT for Intel. In some cases, virtualization capabilities must be manually enabled in the system's BIOS. Be sure to run the fw_update(8) command after doing so to get the required vmm-firmware package.

Processor compatibility can be checked with the following command: 

$ dmesg | egrep '(VMX/EPT|SVM/RVI)'
Before going further, enable and start the vmd(8) service. 
# rcctl enable vmd
# rcctl start vmd

Starting a VM

In the following example, a VM will be created with 50GB of disk space and 1GB of RAM. It will boot from the install78.iso image file. 
# vmctl create -s 50G disk.qcow2
vmctl: qcow2 imagefile created
# vmctl start -m 1G -L -i 1 -r install78.iso -d disk.qcow2 example
vmctl: started vm 1 successfully, tty /dev/ttyp8
# vmctl show
   ID   PID VCPUS  MAXMEM  CURMEM     TTY        OWNER NAME
    1 72118     1    1.0G   88.1M   ttyp8         root example
To view the console of the newly created VM, attach to its serial console: 
# vmctl console example
Connected to /dev/ttyp8 (speed 115200)
The escape sequence ~. is needed to leave the serial console. See the cu(1) man page for more info. When using a vmctl serial console over SSH, the ~ (tilde) character must be escaped to prevent ssh(1) from dropping the connection. To exit a serial console over SSH, use ~~. instead.

The VM can be stopped using vmctl(8). 

# vmctl stop example
stopping vm: requested to shutdown vm 1
Virtual machines can be started with or without a vm.conf(5) file in place. The following /etc/vm.conf example would replicate the above configuration: 
vm "example" {
    memory 1G
    enable
    disk /home/user/disk.qcow2
    local interface
}
Some configuration properties in vm.conf(5) can be reloaded by vmd(8) on the fly. Other changes, like adjusting the amount of RAM or disk space, require the VM to be restarted.

Networking

Network access to vmm(4) guests can be configured a number of different ways, four of which are detailed in this section.

In the examples below, various IPv4 address ranges will be mentioned for different use cases:

Option 1 - VMs only need to talk to the host and each other

For this setup, vmm uses local interfaces: interfaces that use the shared address space defined above.

Using vmctl(8)'s -L flag creates a local interface in the guest which will receive an address from vmd via DHCP. This essentially creates two interfaces: one for the host and the other for the VM.

Option 2 - NAT for the VMs

This setup builds upon the previous and allows VMs to connect outside the host. IP forwarding is required for it to work.

The following line in /etc/pf.conf will enable Network Address Translation and redirect DNS requests to the specified server: 

match out on egress from 100.64.0.0/10 to any nat-to (egress)
pass in proto { udp tcp } from 100.64.0.0/10 to any port domain \
	rdr-to $dns_server port domain
Reload the pf ruleset and the VM(s) can now connect to the internet.

Option 3 - Additional control over the VM network configuration

Sometimes you may want additional control over the virtual network for your VMs, such as being able to put certain ones on their own virtual switch. This can be done using a veb(4) and a vport(4) interface.

Create a vport0 interface that will have a private IPv4 address as defined above. In this example, we'll use the 10.0.0.0/8 subnet. 

# cat <<END > /etc/hostname.vport0
inet 10.0.0.1 255.255.255.0
up
END
# sh /etc/netstart vport0
Create the veb0 interface with the vport0 interface as a child interface: 
# cat <<END > /etc/hostname.veb0
add vport0
up
END
# sh /etc/netstart veb0
Ensure that NAT is set up properly if the guests on the virtual network need access beyond the physical machine. An adjusted NAT line in /etc/pf.conf might look like this: 
match out on egress from vport0:network to any nat-to (egress)
The following lines in vm.conf(5) can be used to ensure that a virtual switch is defined: 
switch "my_switch" {
    interface veb0
}

vm "my_vm" {
    ...
    interface { switch "my_switch" }
}
Inside the my_vm guest, it's now possible to assign vio0 an address on the 10.0.0.0/24 network and set the default route to 10.0.0.1.

For convenience, you may wish to set up a DHCP server on vport0.

Option 4 - VMs on the real network

In this scenario, the VM interface will be bridged with the same network as the host. The VM can then be configured as if it were physically connected to the host network. This option only works for hosts with Ethernet connectivity, as the IEEE 802.11 standard prevents wireless interfaces from participating in network bridges.

The Ethernet network will be switched between the real network, the host, and the VM using veb(4). Because veb(4) disconnects interfaces added as ports from the IP stack, any IP configuration on the real interface has to be moved to a vport(4) interface for the host to be able to participate in the network. In this example em0 is the interface connected to the real network.

Move the IP configuration from em0 to vport0: 

# mv /etc/hostname.em0 /etc/hostname.vport0
# echo up >> /etc/hostname.vport0
# echo up >> /etc/hostname.em0
# sh /etc/netstart em0 vport0

Create the veb0 interface and add the em0 and vport0 interfaces: 

# cat <<END > /etc/hostname.veb0
add em0
add vport0
up
END
# sh /etc/netstart veb0
As done in the previous example, create or modify the vm.conf(5) file to ensure that a virtual switch is defined: 
switch "my_switch" {
    interface veb0
}

vm "my_vm" {
    ...
    interface { switch "my_switch" }
}
The my_vm guest can now participate on the real network as if it were physically connected.

Note: If the host interface (em0 in the above example) uses automatic address configuration (eg, DHCP), it may rely on the MAC address of the interface to get a particular IP address assigned. In this situation the MAC address from em0 can be assigned to vport0 so it can use it on the real network.

Virtual machines can be connected to a real network but isolated from the host by omitting the vport interface in the configuration above.