PUFFMATIC-NET(1)

NAME
puffmatic-net - create OpenBSD installation sets for autoinstall

SYNOPSIS
puffmatic-net [-h] [-v]

DESCRIPTION
The puffmatic-net utility downloads OpenBSD installation sets from a configured mirror and processes domain configurations for all hosts, creating autoinstall response files, disklabel files, and site sets.

The resulting files can be served over HTTP for network installation. Before exposing installation files on the public internet, please refer to SECURITY CONSIDERATIONS

For additional details, please refer to EXAMPLES.

Options:

-h  Display help and exit

-v  Enable verbose mode

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

EXAMPLES

  doas.conf
Since puffmatic-net 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

  Generating response files and site sets
Puffmatic ships with example domain configuration example.com. The example contains configuration files and templates required to generate complete installable file sets for 2 hosts. Copy that directory into your $HOME first. Then, to generate site sets, enter the directory $HOME/example.com and run the script:

    $ cd ~/example.com
    $ puffmatic-net -v

The output files will be placed in example.com/output/resp and example.com/output/sets, by default.

  Service files with httpd
Configure your httpd(8) to serve response and set files using example.com/httpd/install.example.com.conf as example. To create htpasswd, use htpasswd(1) utility:

    $ echo user:pass | htpasswd -I > htpasswd

and place it in location from the httpd(8) configuration file. Copy file sets and response files to /var/www/install.example.com/resp and /var/www/install.example.com/sets.

  Run installer using vmd
Example host bravo is suitable for network installation using vmd(8):

    $ vmctl -s 40G bravo.qcow2
    $ vmctl start -m 2G -L -d bravo.qcow2 -b output/sets/bsd.rd -c bravo

Since allocated tap(4) IP address depends on virtual machine ID and we use 100.64.1.0 network in the autoinstall response file, make sure your virtual machine starts with ID 1 or adjust the configuration. When prompted, choose (A)utoinstall and point it to a response file:

    Welcome to the OpenBSD/amd64 7.7 installation program.
    (I)nstall, (U)pgrade, (A)utoinstall or (S)hell? a
    Could not determine auto mode.
    Response file location? [http://100.64.1.2/install.conf]
    http://user:pass@100.64.1.2:8080/install-bravo.conf
    (I)nstall or (U)pgrade? i
    Fetching http://user:pass@100.64.1.2:8080/install-bravo.conf
    Performing non-interactive install...

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
autoinstall(8) httpd(8) mount_mfs(8) mtree(8) puffmatic-usb(1)

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

CAVEATS

This tool requires privileged access to execute the mount(8) and umount(8) commands, which are essential for mounting the mfs filesystem in noperm mode to create site archives.

The initial synchronization with the mirror may take considerable amount of time, as the script needs to download the complete file set from the mirror server. This process might create the impression that the script is unresponsive. However, subsequent executions will utilize these already downloaded files.

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

SECURITY CONSIDERATIONS

The resulting files are designed for HTTP delivery, facilitating (semi-)automatic installation on VPS hosting via the internet. Therefore, users must protect the files on the server from unauthorized access.

The configuration includes support for basic authentication and a "secret path" method to secure archive files.

Response files can be secured using basic authentication and TLS.

While set archives can be secured by TLS, the installer does not support basic authentication. These files may be stored in a "secret directory" (path), which will remain accessible only to the installer having prior access to the (protected) response file.