██████  ██ ▄█▀▒███████▒      ▒█████   ██▓███   ██▄       ▄████▄   ██ ▄█▀
 ▒██    ▒  ██▄█▒ ▒ ▒ ▒ ▄▀░     ▒██▒  ██▒▓██░  ██ ▒████▄    ▒██▀ ▀█   ██▄█▒
 ░ ▓██▄   ▓███▄░ ░ ▒ ▄▀▒   ▓▒█ ▒██░  ██▒▓██░ ██▓▒▒██  ▀█▄  ▒▓█    ▄ ▓███▄░
   ▒   ██▒▓██ █▄   ▄▀▒      ░▒ ▒██   ██░▒██▄█▓▒ ▒░██▄▄▄▄██ ▒▓▓▄ ▄██▒▓██ █▄
 ▒██████▒▒▒██▒ █▄▒███████▒░      ████▓▒░▒██▒ ░  ░ ▓█   ▓██▒▒ ▓███▀ ░▒██▒ █▄
 ▒ ▒▓▒ ▒ ░▒ ▒▒ ▓▒░▒▒ ▓░▒░▒░ ░    ▒░▒░▒░ ▒▓▒░ ░  ░ ▒▒   ▓▒█░░ ░▒ ▒  ░▒ ▒▒ ▓▒
 ░ ░▒  ░ ░░ ░▒ ▒░░░ 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
   • Terraform (for opack-cloud)

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 excerpt 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
• OPACK_GCE_PROJECT: The Google Cloud project name where the VM will be created
• OPACK_GCE_JSON_KEY: The filename of the Google Cloud service account JSON key
• OPACK_GCE_BUCKET: The Google Cloud Storage bucket name to use for the image import

Examples

A few examples are located in the examples directory:

Quick example

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

OPACK_TARGET=       demo
include path/to/src/opack.mk

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 opack-clean will remove the VM, but not the vagrant box (in order to clean everything, use make opack-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 -n 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.

GCE example

Before using this example, you need to prepare the cloud environment:

1. Create a GCP project and declare its name by overriding OPACK_GCE_PROJECT.
2. Create a service account and obtain its key, which path should be declared with OPACK_GCE_JSON_KEY.
3. Create a GCS Bucket and declare its name with OPACK_GCE_BUCKET (defaults to OPACK_GCE_PROJECT).
4. Enable the Cloud Ressource Manager API in order for the service account to use it with its key.

OPACK_TARGET=                   testopack-cloud
OPACK_SYS_VERSION=              snapshots
OPACK_SYS_DISK_SIZE=            10000

OPACK_GCE_PROJECT=              testopack
OPACK_GCE_JSON_KEY=             testopack-342b60ffed47.json

OPACK_AUTODISKLABEL_FILE=       $(shell realpath ./autodisklabel)

include ../../src/opack.mk

all: opack-cloud
        ssh -i $(OPACK_SYS_SSH_PRIVATE_KEY) \
                -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
                $(OPACK_SYS_USER)@$(shell cat opack-cloud) \
                "sysctl -n kern.version; uptime;" 2> /dev/null

Here, a custom disklabel path is used (see its source).

Alongside the disk size which is increased to 10GB (corresponding to the GCP allocation for e2-micro instance), OpenBSD -current is used.

Once opack-cloud is finished, the VM is up and running in your GCP project. Upon calling opack-clean, the VM instance and its boot image will be destroyed.

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 default 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.
• packer-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 Compute Platform 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.