---
title: "First release of installiso"
description: "A utility to customize OpenBSD installation images for unattended installation."
published: 2021-07-23
---

One year ago I [posted](/posts/autoinstall-openbsd-on-qemu/) how to script an unattended installation of OpenBSD on the QEMU virtual machine monitor.
The script involved ... TODO; essentially because I treated the installation image as a black box.
Of course, I could have mounted the ISO 9660 image and created a modified image using [`mkisofs(8)`](http://cdrtools.sourceforge.net/private/man/cdrecord/mkisofs.8.html).
But I didn't know how to insert the [`autoinstall(8)`](https://man.openbsd.org/OpenBSD-6.9/autoinstall) response file into the RAMDISK kernel in the ISO 9660 image.
That was no surprise -- why would anyone need to change an OpenBSD kernel on Linux.

OpenBSD, on the other hand, includes adequate utilities.
Thanks to [`vmctl(8)`](https://man.openbsd.org/OpenBSD-6.9/vmctl), [`rdsetroot(8)`](https://man.openbsd.org/OpenBSD-6.9/rdsetroot), and [`mkhybrid(8)`](https://man.openbsd.org/OpenBSD-6.9/mkhybrid), we can modify the ISO 9660 image _and_ the contained RAMDISK kernel.
The exact process is a bit tedious so I decided to automate it.
The resulting script is more hacky than pretty but it gets the job done and I found it useful enough to give it a name, `installiso`, and release it today.
You can download the very first release [here](/files/installiso-0.1.0.tar.gz).
Feedback appreciated!
<!-- TODO: Add release tarball -->
<!-- TODO: Link or embed HTML man page? -->

In the remainder of this post I'll show how I use `installiso` to create custom OpenBSD installation images for unattended -- and possibly offline -- installation.
As an example, I'll show how to create virtual machines on OpenBSD's own virtual machine monitor, [`vmm(4)`](https://man.openbsd.org/OpenBSD-6.9/vmm).

For starters, we create an [`autoinstall(8)`](https://man.openbsd.org/OpenBSD-6.9/autoinstall) response file.
Of course, you can skip this step and have the installer mail you the responses recorded during an interactive installation instead.


```
$ cat >install.conf <<EOF
Change the default console to com0 = yes
Which speed should com0 use = 115200
System hostname = openbsd-vm
DNS domain name = example.com
Password for root = *************
Start sshd(8) by default = yes
Allow root ssh login = no
Setup a user = $USER
Full name for user stefan = $( userinfo "$USER" | sed -n 's/^gecos[[:space:]]*\(.*\)$/\1/p' )
Password for user = *************
Public ssh key for user = $( cat "$HOME/.ssh/id_rsa.pub" )
What timezone are you in = UTC
Location of sets = cd0
Set name(s) = site*.tgz
Directory does not contain SHA256.sig. Continue without verification = yes
EOF
```

Next, we create a site-specific file set.

```
$ mkdir -p site
$ cat >site/install.site <<EOF
#! /bin/ksh

set -o errexit

# Permit user group wheel to run any command as root
# without entering their password using doas(1).
echo "permit nopass keepenv :wheel" > /etc/doas.conf

# Install packages.
#echo "pkg_add sqlite3" >> /etc/rc.firsttime

# Patch the base system.
#echo "syspatch && shutdown -r now" >> /etc/rc.firsttime
EOF
```

Now we're ready to create the custom installation image using `installiso`.
First, we download and verify the latest development snapshot.
You can also specify the mirror, a specific release, and the [`signify(1)`](https://man.openbsd.org/OpenBSD-6.9/signify) public key if you like.
Then, we insert the prepared response file and file set into the image[^tmpdir].

    $ installiso -v fetch -o snapshot.iso
    $ doas installiso -v \
        patch -i install.conf -s site snapshot.iso custom.iso

Finally, we start a virtual machine off a new disk image and the custom installation image.

    $ vmctl create -s 10G disk.qcow2
    $ doas vmctl start -c -d disk.qcow2 -m 512M \
        -i 1 -L -r custom.iso tmp

<!-- TODO: Note vmctl (network) preconditions -->

Once the unattended installation completed, we can log in:

    $ ssh \
        -o "StrictHostKeyChecking no" \
        -o "UserKnownHostsFile /dev/null" \
        100.64.1.3

[^tmpdir]:
The `installiso` utility may fail due to not enough space in `/tmp`.
If so, you can set the `TMPDIR` environment variable of [`mktemp(1)`](https://man.openbsd.org/OpenBSD-6.9/mktemp).
Remember that [`doas(1)`](https://man.openbsd.org/OpenBSD-6.9/doas) creates a new environment by default, though.
You can either configure `doas(1)` to keep the `TMPDIR`, or you execute a shell:
`doas sh -c 'TMPDIR=/path/to/tmp installiso patch ...'`.