Auto-install OpenBSD on QEMU
Update 17 March 2022: Starting with OpenBSD 7.0, autoinstall(8) no longer respects the TFTP server name option used below. I’ve added updated instructions at the end of this post. Thanks for reporting the issue, Benjamin.
I happen to develop a pet project of mine on a Linux desktop, while actually targeting an OpenBSD server. Thus I searched for a scriptable way to install OpenBSD on the QEMU virtual machine manager, such that I could automate a local integration test against OpenBSD running on Linux.
As expected, OpenBSD has a remarkably straightforward unattended installation solution. During a normal, interactive installation, you answer a series of questions like what timezone you are in or which file sets to install. At the end of the installation, the installer sends a recorded list of those questions along with your answers to the root user’s mail box. You can then adapt this so-called response file to your needs and feed it to the autoinstall(8) command to perform an unattended installation.
In the remainder of this post, I will show how to auto-install OpenBSD/amd64 6.7 on the QEMU PC system emulator 5.0.0. In the end, I will present a simple yet complete POSIX shell script to get the job done. The script is intended to run on Linux, though. If you already have a running OpenBSD installation, you should consider to use OpenBSD’s own hypervisor vmm(4) instead of QEMU as described in the OpenBSD FAQ and in this blog post by Eric Radman.
We will perform the following steps:
- Install several prerequisites
- Setup a local OpenBSD mirror
- Configure the installation
- Setup a network boot environment
- Install the virtual machine
- Log in to the virtual machine
We will use the following tools:
- curl, a data transfer tool (and library)
- OpenSSH, a remote login tool
- QEMU, a virtual machine monitor (or hypervisor)
- rsync, an incremental file transfer tool
- signify, a cryptographic signature tool1
- socat, a successor of the infamous TCP/IP Swiss Army knife netcat
Chances are that your Linux distribution of choice packages these tools. For example, the following command installs them on Arch Linux:
$ sudo pacman -S curl openssh qemu rsync signify socat
Local OpenBSD mirror
To begin with, we setup a partial, local OpenBSD mirror.
First, we create the relevant part of the directory layout:
$ mkdir -p mirror/pub/OpenBSD/6.7/amd64
Second, we fetch the base public key from the official HTTPS mirror using curl(1):
$ curl \ --output mirror/pub/OpenBSD/6.7/openbsd-67-base.pub \ https://ftp.openbsd.org/pub/OpenBSD/6.7/openbsd-67-base.pub
Third, we fetch the kernel, the PXE bootstrap program, and the file sets from an untrusted rsync mirror using rsync(1):
$ rsync --archive --files-from=- --verbose \ rsync://ftp.halifax.rwth-aachen.de/openbsd/6.7/amd64/ \ mirror/pub/OpenBSD/6.7/amd64 \ << EOF SHA256.sig base67.tgz bsd bsd.mp bsd.rd comp67.tgz game67.tgz man67.tgz pxeboot xbase67.tgz xfont67.tgz xserv67.tgz xshare67.tgz EOF
Fourth, we verify the fetched files using signify(1) and the previously fetched base public key:2
$ ( cd mirror/pub/OpenBSD/6.7/amd64 && signify -C \ -p ../openbsd-67-base.pub \ -x SHA256.sig \ -- bsd bsd.* pxeboot *67.tgz )
Finally, we serve the local mirror at http://127.0.0.1:8080/. Feel free to use your web server of choice. Chances are, that your Linux distribution comes with Python’s http.server module:
$ python3 \ -m http.server \ --directory mirror \ --bind 127.0.0.1 8080
First, we create a response file for autoinstall(8) at
Change the default console to com0 = yes Which speed should com0 use = 115200 System hostname = openbsd Password for root = ************* Allow root ssh login = no Setup a user = puffy Password for user = ************* Public ssh key for user = ssh-rsa AAAAB3N... alex@example What timezone are you in = UTC Location of sets = http HTTP Server = 10.0.2.1 Unable to connect using https. Use http instead = yes URL to autopartitioning template for disklabel = http://10.0.2.1/disklabel Set name(s) = site67.tgz Checksum test for site67.tgz failed. Continue anyway = yes Unverified sets: site67.tgz. Continue without verification = yes
Take care to insert your own public SSH key here, for example, the contents of
Note that we effectively disable password-based authentication here by assigning the conventional 13 asterisks as encrypted passwords for both users,
puffy, see passwd(5).
Instead, we enable the user
puffy to login using the given SSH key.
Besides, we will later permit the user
puffy to run any command as root without entering his password using doas(1).
Note also that we will later instruct QEMU to redirect port 80 on the virtual network address 10.0.2.1 to port 8080 on the local host.
Next, we create a disklabel(8) template at
/ 2G swap 8G /tmp 1G /var 1G /usr 2G /usr/X11R6 500M /usr/local 4G /usr/src 1M /usr/obj 1M /home 4G
Finally, we create an optional site-specific file set.
This way, we can run some commands at the end of the installation.
Here, we reset the OpenBSD mirror server used by pkg_add(1) and other commands.4
Moreover, we permit the user group
wheel — and thus the user
puffy — to run any command as the user
root without entering their password using doas(1).
Create the file
#! /bin/ksh set -o errexit echo "https://cdn.openbsd.org/pub/OpenBSD" > /etc/installurl echo "permit nopass keepenv :wheel" >> /etc/doas.conf
Then, make the file executable, package the file set, and add it to the local OpenBSD mirror:
$ chmod +x site/install.site $ ( cd site && tar -czf ../mirror/pub/OpenBSD/6.7/amd64/site67.tgz . ) $ ( cd mirror/pub/OpenBSD/6.7/amd64 && ls -l > index.txt )
Network boot environment
We create a dedicated directory to serve the OpenBSD kernel and PXE bootstrap program over TFTP:
$ mkdir tftp $ ln -s ../mirror/pub/OpenBSD/6.7/amd64/pxeboot tftp/auto_install $ ln -s ../mirror/pub/OpenBSD/6.7/amd64/bsd.rd tftp/bsd.rd
Furthermore, we create a boot(8) configuration file at
stty com0 115200 set tty com0 boot tftp:/bsd.rd
First, we create a copy-on-write disk image using qemu-img(1):
$ qemu-img create -f qcow2 disk.qcow2 24G
Then, we start a virtual machine — and thus the unattended installation of OpenBSD — off this disk using qemu-system-x86_64(1) and socat(1):
$ qemu-system-x86_64 \ -enable-kvm \ -smp "cpus=4" \ -m 4G \ -drive "file=disk.qcow2,media=disk,if=virtio" \ -device e1000,netdev=n1 \ -netdev "user,id=n1,hostname=openbsd-vm,tftp-server-name=10.0.2.1,tftp=tftp,bootfile=auto_install,hostfwd=tcp::2222-:22,guestfwd=tcp:10.0.2.1:80-cmd:socat STDIO TCP4:127.0.0.1:8080" \ -nographic
Let’s break this last command down.
-enable-kvm option enables the Linux Kernel-based Virtual Machine (KVM) support.
-smp option instructs QEMU to simulate a symmetric multiprocessing (SMP) system.
-m option sets the amount of virtual memory.
-drive option attaches the previously created copy-on-write disk image as a Virtio disk drive.
-device option attaches a standard network adapter.
-netdev option configures a virtual network
10.0.2.15 point to the QEMU host and guest respectively.
Moreover, we instruct QEMU to (a) run an embedded TFTP server at
10.0.2.1, (b) redirect port 2222 on the host to port 22 on the guest, and (c) redirect port 80 on the virtual host address
10.0.2.1 to port 8080 on the host.
The former port redirection enables us to log in to the guest using ssh(1), and the latter port redirection frees us from binding to the privileged port 80 on the host.5
-nographic option turns QEMU into a command-line application that redirects the emulated serial port to the console.
C-a x to stop the virtual machine, or
C-a h to show other options.
Once the virtual machine has booted, you can log in as the user
puffy using ssh(1):
ssh \ -o "StrictHostKeyChecking no" \ -o "UserKnownHostsFile /dev/null" \ -o "Port 2222" \ firstname.lastname@example.org
Here, we use the
UserKnownHostsFile options to keep the presumably temporary virtual machine’s host key out of our known hosts file.
We auto-installed OpenBSD/amd64 6.7 on the QEMU PC system emulator 5.0.0 by means of several command-line tools. First, we setup a partial, local OpenBSD mirror using rsync(1) and signify(1). Second, we prepared a response file for autoinstall(8), a disklabel(8) template, and a site-specific file set. Third, we setup a standard network boot environment. Fourth, we actually installed OpenBSD on a QEMU guest machine. Finally, we logged in to the virtual machine using ssh(1).
Of course, you can automate the whole process. For example, I use a simple, yet complete POSIX shell script to auto-install OpenBSD on QEMU. In fact, I have written another script to install and test the said pet project of mine as well. But this is out of scope here.
Starting with OpenBSD 7.0, autoinstall(8) no longer respects the TFTP server name option used below.
Instead, it uses the next-server DHCP option.
Thus, the installer tries to fetch the response file from the QEMU host at
To fix that, you can serve the mirror on port 80 instead of 8080, change the response file to point at 10.0.2.2 instead of 10.0.2.1, and remove the now obsolete TFTP server name option and the guest forwarding from the QEMU invocation.
Of course, binding to port 80 requires root privileges.
I think it should be possible to avoid that using a corresponding guest forwarding from
tcp:10.0.2.2:8080 but QEMU rejects this as an invalid forwarding rule.
We use Adrian Perez’ portable version of OpenBSD’s signify(1) here.↩︎
You can also verify the SHA256 checksums of the fetched files if you cannot use signify(1).↩︎
You can serve per-host response files for autoinstall(8) by prefixing the MAC address or the hostname. Besides, you can add the response file to the RAM disk kernel
You can create a fully isolated virtual machine by (a) including patches, packages, and ports in your local OpenBSD mirror, and (b) restricting the virtual network created by QEMU.↩︎
I failed to forward port 80 on the virtual host address to port 8080 on the local host using qemu-system-x86_64(1)’s
guestfwdalone. That’s why I resorted to the invaluable socat(1).↩︎