PUFFMATIC-USB(1)

NAME
puffmatic-usb - create USB autoinstall image for OpenBSD

SYNOPSIS
puffmatic-usb [-h] [-v] [hostdir]

DESCRIPTION
The puffmatic-usb utility downloads OpenBSD installer image from a configured mirror and patches the /bsd.rd adding /auto_install.conf and /disklabel. Then it create (optional) site file set archives site77.tgz and site77-${hostname}.tgz and adds them to the file sets on the installation image.

The resulting installer image allows unattended installation directly from USB stick.

For additional details, please refer to EXAMPLES.

Options:

-h  displays short help message

-v  enable verbose mode

hostdir
    path to directory with host configuration; this path will be located in your domain config directory under hosts/ subdirectory

EXIT STATUS
The puffmatic-usb exits with the following status:
0   Success
>0  An error occured.

EXAMPLES

  doas.conf
Since puffmatic-usb required priviledged access to certain system executables, to avoid running it as root you can leverage doas(1):

    permit nopass user cmd mount
    permit nopass user cmd umount
    permit nopass user cmd vnconfig
    permit nopass user cmd install

  Generating installer for example.com host
Puffmatic ships with example configuration example.com/hosts/alfa. This host example illustrates the process of creating an autoinstallable USB image. The provided install.conf is tailored for a specific machine. This image is designed to be executed using vmd(8). Since vmd(8) boots from the first image, the installer will run from sd0, while the target disk must be designated as sd1. The host is configured with full disk encryption, a custom boot.conf, and a set of sshd host keys included in the host-specific site77-alfa.tgz set. To generate the installer, first copy example.com to your $HOME. Then:

    $ cd ~/example.com
    $ puffmatic-usb -v hosts/alfa

The output file will be placed in example.com/output/img/install77-alfa.img by default.

  Testing installer using vmd
First, create a suitable host disk image. Then run the virtual machine with newly created installer image:

    vmctl create -s 40G alfa.qcow
    vmctl start -m 2G -L -d install77-alfa.img -d alfa.qcow2 -B disk -c alfa

The installation should launch from the patched ramdisk and result in a fully functional system.

DIAGNOSTICS

Since puffmatic is written in Python, thereof any fatal error is likely to produce a detailed stack trace.

Additional diangostic output will be reported to stdout when suitable.

SEE ALSO
Tools related or directly invoked by puffmatic: mount(8) umount(8) mtree(8) vnconfig(8) install(1) vmctl(8) puffmatic-net(1)

AUTHORS
puffmatic-usb has been implemented by Chris Narkiewicz <hello@ezaquarii.com>

CAVEATS

This tool requires privileged access to execute the mount(8), umount(8), vnconfig(8), install(1) commands, which are essential for mounting the image file, ramdisk filesystem and installing files with proper permissions.

The initial installer download may take some amount of time. This process might create the impression that the script is unresponsive. However, subsequent executions will use already downloaded file.

BUGS
To report a bug, please visit https://github.com/ezaquarii/puffmatic/.