██████  ██ ▄█▀▒███████▒      ▒█████   ██▓███   ██▄       ▄████▄   ██ ▄█▀
 ▒██    ▒  ██▄█▒ ▒ ▒ ▒ ▄▀░     ▒██▒  ██▒▓██░  ██ ▒████▄    ▒██▀ ▀█   ██▄█▒
 ░ ▓██▄   ▓███▄░ ░ ▒ ▄▀▒   ▓▒█ ▒██░  ██▒▓██░ ██▓▒▒██  ▀█▄  ▒▓█    ▄ ▓███▄░
   ▒   ██▒▓██ █▄   ▄▀▒      ░▒ ▒██   ██░▒██▄█▓▒ ▒░██▄▄▄▄██ ▒▓▓▄ ▄██▒▓██ █▄
 ▒██████▒▒▒██▒ █▄▒███████▒░      ████▓▒░▒██▒ ░  ░ ▓█   ▓██▒▒ ▓███▀ ░▒██▒ █▄
 ▒ ▒▓▒ ▒ ░▒ ▒▒ ▓▒░▒▒ ▓░▒░▒░ ░    ▒░▒░▒░ ▒▓▒░ ░  ░ ▒▒   ▓▒█░░ ░▒ ▒  ░▒ ▒▒ ▓▒
 ░ ░▒  ░ ░░ ░▒ ▒░░░ https://git.sk4.nz/sk4nz/skz-opack ▒▒ ░  ░  ▒   ░ ░▒ ▒░
       ░  ░  ░     ░ ░             ░ ░                 ░  ░░ ░      ░  ░
                 ░                                         ░

---

Samuel 'sk4nz' AUBERTIN

skz-opack is an automated OpenBSD bootstrapper.

Leveraging Packer, Vagrant boxes and a bit of black magic (also known as scripting) it enables frictionless execution of this wonderful operating system within a local virtual machine from a Linux host. It can also emit a compliant Google Compute Engine image, ran in the cloud using Terraform.

Instructions

To get started with skz-opack, follow these steps:

1. Clone the repository using the following command:

   git clone https://git.sk4.nz/sk4nz/skz-opack.git
   

2. Ensure you have the following dependencies installed:

   • GNU Make
   • libvirt
   • Vagrant
   • Vagrant-Libvirt module

3. Use the project by including path/to/skz-opack/src/opack.mk and invoking the opack target in your Makefile to create a local OpenBSD virtual machine with Packer and Vagrant. Use the 'opack-cloud' target to run the same virtual machine in GCP with Terraform.

Available make targets

• opack: downloads, installs an run OpenBSD in a local VM.
• opack-cloud: same as 'opack' but in the GCP cloud.
• opack-clean: Destroys the local/cloud VM.
• opack-cleancache: Removes the cache containing installation isos and Vagrant boxes.
• opack-cleanall: 'opack-clean' and 'opack-cleancache'

Overridable default options

Every default option ending with an ? in "src/options.mk" can be overrided in the invoking Makefile. Here is an short list of theses:

• OPACK_SYS_HOSTNAME: VM hostname
• OPACK_SYS_USER: username to create
• OPACK_SYS_PASSWORD: user password
• OPACK_SYS_DISK_SIZE: VM disk size, in megabytes
• OPACK_SYS_MEMORY: VM RAM, in megabytes
• OPACK_SYS_CPU: VM cpu count
• OPACK_SYS_SERVER: OpenBSD package mirror
• OPACK_SYS_ARCHITECTURE: OpenBSD platform to use (only amd64 has been tested)
• OPACK_SYS_RELEASE: OpenBSD release name aka 74
• OPACK_SYS_VERSION: OpenBSD version aka 7.4 or snapshots
• OPACK_SYS_XENOCARA: Install Xenocara, the OpenBSD X11 fork
• OPACK_SYS_SETS: OpenBSD sets to install
• OPACK_SYS_TIMEZONE: Timezone decalred at installation
• OPACK_SYS_SSH_KEY: The SSH public key added to the created user
• OPACK_SYS_ISO_URL: The installation iso URL
• OPACK_SYS_ISO_SHA256SUM: The installation iso SHA256 sum
• OPACK_SYS_SETS_LOCATION: The location of installed OpenBSD sets eg http or cd0
• OPACK_NO_SIGCHK: Ignore unsigned sets
• OPACK_SYS_HEADLESS: Run Packer installation in headless mode
• OPACK_AUTODISKLABEL_FILE: OpenBSD partitioning scheme for installation
• OPACK_PROVISION_FILE: Script executed after installation
• OPACK_RUNTIME_PROVISION_FILE: Script executed after VM creation

Examples

Quick example

Here is the shortest Makefile that can be used to leverage skz-opack:

OPACK_TARGET=   demo # the VM name
include path/to/src/opack.mk # mandatory

After invokation with make opack, it will download, install, and run the latest OpenBSD release in a local VM with the default options. Once executed, the VM is running and it is possible to log into it using the vagrant ssh command. Then, make clean will remove the VM, but not the vagrant box (in order to clean everything, use make cleancache).

Overrides Example

In this example, we will demonstrate how to use overrides in skz-opack to create an OpenBSD -current virtual machine named "run-current" with 4 CPUs and 1GB of RAM.

OPACK_TARGET=       run-current
OPACK_SYS_VERSION=  snapshots
OPACK_SYS_CPU=      4
OPACK_SYS_MEMORY=   1024

include path/to/src/opack.mk

all: opack 
        vagrant ssh -c "uname -a; sysctl kern.version"

In this Makefile:

• OPACK_TARGET specifies the name of the virtual machine as "run-current."
• OPACK_SYS_VERSION sets the OpenBSD version to "snapshots," indicating the -current version.
• OPACK_SYS_CPU allocates 4 CPUs to the VM.
• OPACK_SYS_MEMORY assigns 1GB of RAM to the VM.

Making "opack" a dependency target of "all" will ensure skz-opack operates before any command in the "all" target. Try it with make all !

Once the "opack" target dependency is finished, the VM is running and the system kernel version is outputted. This example showcases how to customize and run skz-opack for your specific needs.

GCP example

TODO

Troubleshooting

• To enable debug mode, you can declare 'OPACK_DEBUG=yes' either in your Makefile or at runtime with: 'OPACK_DEBUG=yes make opack'.
• Overrides should happen before the include of "opack.mk".

Architecture

Security

OPACK_SYS_USER can become root using the doas command.

The autodisklabel used for this project is flat, so partitions don't benefit from nodev, nosuid and wxallowed protections.

Code structure

In the "src" directory, are located the following files:

• autodisklabel: This file provides the partitioning layout for the installer and can be customized by using the OPACK_AUTODISKLABEL_FILE option.
• defines.mk: Contains internal skz-opack definitions for Packer and Vagrant.
• opack.mk: To use skz-opack in your projects, simply include this file in your Makefiles.
• opack-provision.sh: This file is executed for post-installation provisioning with Packer and can be customized using the OPACK_PROVISION_FILE option.
• options.mk: This file is where all skz-opack options are declared. Options are always in the OPACK_[OPTION NAME] format.
• packerfile-gcp.mk: Special Packerfile for Google Cloud Compute upload.
• packerfile.mk: Generic Packerfile for local execution.
• vagrantfile.mk: Contains Vagrantfile definitions for local execution.
• vagrant-provision.sh: This file is executed for pre-run provisioning with Vagrant and can be customized using the OPACK_RUNTIME_PROVISION_FILE option.

License

skz-opack is distributed under the OpenBSD License. See the LICENSE file for more details.

References

For more information on the tools used in this project, refer to the following resources:

• Packer
• Vagrant