``` ██████ ██ ▄█▀▒███████▒ ▒█████ ██▓███ ██▄ ▄████▄ ██ ▄█▀ ▒██ ▒ ██▄█▒ ▒ ▒ ▒ ▄▀░ ▒██▒ ██▒▓██░ ██ ▒████▄ ▒██▀ ▀█ ██▄█▒ ░ ▓██▄ ▓███▄░ ░ ▒ ▄▀▒ ▓▒█ ▒██░ ██▒▓██░ ██▓▒▒██ ▀█▄ ▒▓█ ▄ ▓███▄░ ▒ ██▒▓██ █▄ ▄▀▒ ░▒ ▒██ ██░▒██▄█▓▒ ▒░██▄▄▄▄██ ▒▓▓▄ ▄██▒▓██ █▄ ▒██████▒▒▒██▒ █▄▒███████▒░ ████▓▒░▒██▒ ░ ░ ▓█ ▓██▒▒ ▓███▀ ░▒██▒ █▄ ▒ ▒▓▒ ▒ ░▒ ▒▒ ▓▒░▒▒ ▓░▒░▒░ ░ ▒░▒░▒░ ▒▓▒░ ░ ░ ▒▒ ▓▒█░░ ░▒ ▒ ░▒ ▒▒ ▓▒ ░ ░▒ ░ ░░ ░▒ ▒░░░ https://git.sk4.nz/sk4nz/skz-opack ▒▒ ░ ░ ▒ ░ ░▒ ▒░ ░ ░ ░ ░ ░ ░ ░ ░ ░░ ░ ░ ░ ░ ░ ``` ----- *Samuel 'sk4nz' AUBERTIN* **skz-opack** is an automated [OpenBSD](https://www.openbsd.org) 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: ```sh git clone https://git.sk4.nz/sk4nz/skz-opack.git ``` 2. Ensure you have the following dependencies installed: - [GNU Make](https://www.gnu.org/software/make/) - [libvirt](https://libvirt.org/) - [Vagrant](https://www.vagrantup.com/) - [Vagrant-Libvirt module](https://github.com/vagrant-libvirt/vagrant-libvirt) 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: ```make 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. ```make 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](https://www.openbsd.org/policy.html). See the [LICENSE](LICENSE) file for more details. ## References For more information on the tools used in this project, refer to the following resources: - [Packer](https://www.packer.io/) - [Vagrant](https://www.vagrantup.com/)