This article provides a guide for installing OpenBSD on a headless server without using KVM nor VNC. It assumes that you are able to boot the server in rescue mode, which is built over Linux. In additional this article presents the ready-to-use script which is available at http://install.catap.net.
Manual Instalation
The initial section of this article concentrates on a comprehensive manual installation process. To complete the installation successfully, you will need two things: QEMU and an installer. It is assumed that QEMU has already been installed in your rescue mode. If not, you will need to install it.
Next, download an installer:
# wget https://cdn.openbsd.org/pub/OpenBSD/7.4/amd64/install74.iso
where amd64 is your architecture.
The next step is challenging: run it under QEMU with an attached serial console. By default, it boots without using the serial console as the default console. There are two options: a custom installer or a boot option. Let’s start with a boot option, which is provided manually, see:
# qemu-system-x86_64 -m 1024 \
-hda /dev/nvme0n1 -hdb /dev/nvme1n1 \
-smp 2 \
-cdrom install74.iso \
-boot d \
-net user \
-nographic \
-serial mon:stdio
Booting from DVD/CD…
CD-ROM: E0
Loading /7.4/AMD64/CDBOOT
probing: pc0 com0 mem[639K 3070M 1024M a20=on]
disk: fd0 hd0+* hd1+* cd0
>> OpenBSD/amd64 CDBOOT 3.65
boot> stty com0 115200
boot> set tty com0
switching console to com>> OpenBSD/amd64 CDBOOT 3.65
boot>
0
cannot open cd0a:/etc/random.seed: No such file or directory
booting cd0a:/7.4/amd64/bsd.rd: 3969732+1655808+3886664+0+708608 [109+444888+297417]=0xa76798
entry point at 0xffffffff81001000
Copyright © 1982, 1986, 1989, 1991, 1993
The Regents of the University of California. All rights reserved.
Copyright © 1995–2023 OpenBSD. All rights reserved. https://www.OpenBSD.org
OpenBSD 7.4 (RAMDISK_CD) #1322: Tue Oct 10 09:07:38 MDT 2023
deraadt@amd64.openbsd.org:/usr/src/sys/arch/amd64/compile/RAMDISK_CD
real mem = 4278059008 (4079MB)
avail mem = 4144390144 (3952MB)
random: good seed from bootblocks
where x86_64 is your architecture, and /dev/nvme0n1 and /dev/nvme1n1 are
the two NVMe disk used on this server. You may have noticed the use of -smp 2
in this command. This flag is used to allow the OpenBSD installer to detect that
the system has more than one CPU, which enforces the installation of a kernel
with support for multiple CPUs.
After that, the istaller should boot and use your SSH session as console.
Welcome to the OpenBSD/amd64 7.4 installation program.
(I)nstall, (U)pgrade, (A)utoinstall or (S)hell?
From here you may run instalation or upgrade, or use shell to configure your
RAID. Both your disk are available as wd0 and wd1.
Nonetheless, the installation process should proceed as usual with one notable
exception: it prompts the user to select a terminal type instead of a keyboard
layout, and the default vt220 option is suitable. The only potential issue is
preventing the default console from redirecting to com0, which is enabled by
default with this setup. Failure to change this to no will result in the
machine being unable to boot.
Change the default console to com0? [yes] no
At the end of the installation, just before rebooting, you should terminate the QEMU y pressing CTRL+a x.
CONGRATULATIONS! Your OpenBSD install has been successfully completed!
When you login to your new system the first time, please read your mail
using the ‘mail’ command.
Exit to (S)hell, (H)alt or (R)eboot? [reboot] H
syncing disks… done
The operating system has halted.
Please press any key to reboot.
^a x
QEMU: Terminated
After that you may reboot the server which should be boot as expected. The same technique can be used to boot it in single-user mode for maintenance.
Semi-Automatic Installation
The final section of this article focuses on converting the described
installation process to avoid manual input. Unfortunately, achieving a fully
automated process is possible only possible for OpenBSD up to 6.9, because as of
7.0, OpenBSD drops support for tftp-server-name as a possible option for a
hostname1 to construct the URL to the gets answers file. QEMU has a
limitation that cannot bypass a custom DHCP option or next-server.2
Next, download the necessary component for PXE boot:
# mkdir tftpboot
# wget -O tftpboot/bsd.rd https://mirror.leaseweb.com/pub/OpenBSD/6.9/amd64/bsd.rd
# wget -O tftpboot/pxeboot https://mirror.leaseweb.com/pub/OpenBSD/6.9/amd64/pxeboot
# ln -s pxeboot tftpboot/auto_install
again, amd64 is your architecture, and mirror.leaseweb.com is the mirror used.3
Here, the boot option is stored in the TFTP server which allows to specify to use the serial console as the default console:
# mkdir -p tftpboot/etc
# cat > tftpboot/etc/boot.conf << EOF
stty com0 115200
set tty com0
boot tftp:/bsd.rd
EOF
The next step is to prepare an answers file. You need to put it on any HTTP
server4 as /install.conf:5
Change the default console to com0 = no
Allow root ssh login = prohibit-password
Password for root account = *************
Public ssh key for root = ssh-rsa AAAA...
Do you expect to run the X Window System = no
Use (W)hole disk MBR, whole disk (G)PT, (O)penBSD area or (E)dit = whole
Use (A)uto layout, (E)dit auto layout, or create (C)ustom layout = A
HTTP Server = mirror.leaseweb.com
Unable to connect using https. Use http instead = yes
Exit to (S)hell, (H)alt or (R)eboot = h
where ssh-rsa AAAA... is installed SSH public key for root account, and we
should allow the use HTTP protocol instead of HTTPS because the used mirror
contains an SSL certificate that canmot pass verification on an old system.6
Finally, it can be booted via QEMU as follows:
# qemu-system-x86_64 -m 1024 \
-hda /dev/nvme0n1
-smp 2 \
-boot n \
-netdev user,hostname=kirtest,tftp=tftpboot,bootfile=auto_install,tftp-server-name=install.catap.net \
-nographic \
-serial mon:stdio
where kirtest is the desired hostname for this machine, and
install.catap.net is the used HTTP server used to distributes answers
file.7
Also, after installing the machine in a normal boot, you need to upgrade it with
sysupgrade, and after rebooting, merge the config with sysmerge -d. 8
9 10
Furthermore, the ready-to-use script is available at install.catap.net, which follows the OpenBSD visual style nor uses HTTPS.
This feature has been removed without clear explanation.. ↩︎
The topic of bypassing a custom DHCP option was discussed on qemu-discuss on December 30, 2023. ↩︎
It appears that
mirror.leaseweb.comis the only CDN-based mirror that has OpenBSD 6.9, checked on available OpenBSD mirrors on January 22, 2023. ↩︎The easiest options are GitHub Pages or Gitlab Pages. ↩︎
Multiple answer files can be kept on the same server for different hostnames. For more information, refer to autoinstall(8). ↩︎
In any case, OpenBSD does not rely on transport-level security and contains a public key that should be used to sign sets. ↩︎
The server in the example distributes
kirtest-install.conf, which can be used to install OpenBSD. You may access this machine by using the provided key. ↩︎It is important to keep in mind that
sysupgradewill reboot the machine twice. During the first reboot, the machine will upgrade itself, which may take some time. If you are unable to log in over SSH for a few minutes, do not panic or reboot the machine. ↩︎The
sysupgradecommand upgrades the machine to the next release. It is possible to skip some releases and upgrade directly to the desired one, but developers guarantee that the boot loader can only load the kernel from the next release. For example, the bootloader from version 6.9 cannot boot the kernel from version 7.4. ↩︎Note that automatic RAID building or using more than one disk layout during setup is not supported by OpenBSD 6.9 or 7.4. If necessary, these steps must be performed manually. ↩︎