180 lines
9.6 KiB
Markdown
180 lines
9.6 KiB
Markdown
```
|
|
██████ ██ ▄█▀▒███████▒ ▒█████ ██▓███ ██▄ ▄████▄ ██ ▄█▀
|
|
▒██ ▒ ██▄█▒ ▒ ▒ ▒ ▄▀░ ▒██▒ ██▒▓██░ ██ ▒████▄ ▒██▀ ▀█ ██▄█▒
|
|
░ ▓██▄ ▓███▄░ ░ ▒ ▄▀▒ ▓▒█ ▒██░ ██▒▓██░ ██▓▒▒██ ▀█▄ ▒▓█ ▄ ▓███▄░
|
|
▒ ██▒▓██ █▄ ▄▀▒ ░▒ ▒██ ██░▒██▄█▓▒ ▒░██▄▄▄▄██ ▒▓▓▄ ▄██▒▓██ █▄
|
|
▒██████▒▒▒██▒ █▄▒███████▒░ ████▓▒░▒██▒ ░ ░ ▓█ ▓██▒▒ ▓███▀ ░▒██▒ █▄
|
|
▒ ▒▓▒ ▒ ░▒ ▒▒ ▓▒░▒▒ ▓░▒░▒░ ░ ▒░▒░▒░ ▒▓▒░ ░ ░ ▒▒ ▓▒█░░ ░▒ ▒ ░▒ ▒▒ ▓▒
|
|
░ ░▒ ░ ░░ ░▒ ▒░░░ 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://developer.hashicorp.com/vagrant/downloads)
|
|
- [Vagrant-Libvirt module](https://github.com/vagrant-libvirt/vagrant-libvirt)
|
|
- [Terraform](https://developer.hashicorp.com/terraform/downloads) (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](examples) directory:
|
|
|
|
### Quick example
|
|
|
|
Here is the shortest Makefile that can be used to leverage skz-opack:
|
|
|
|
```make
|
|
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.
|
|
|
|
```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 -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](https://cloud.google.com/resource-manager/docs/creating-managing-projects) and declare its name by overriding `OPACK_GCE_PROJECT`.
|
|
2. [Create a service account](https://cloud.google.com/iam/docs/service-accounts-create) and [obtain its key](https://cloud.google.com/iam/docs/keys-create-delete), which path should be declared with `OPACK_GCE_JSON_KEY`.
|
|
3. [Create a GCS Bucket](https://cloud.google.com/storage/docs/creating-buckets) and declare its name with `OPACK_GCE_BUCKET` (defaults to `OPACK_GCE_PROJECT`).
|
|
4. Enable the [Cloud Ressource Manager API](https://console.cloud.google.com/marketplace/product/google/cloudresourcemanager.googleapis.com) in order for the service account to use it with its key.
|
|
|
|
```make
|
|
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](https://man.openbsd.org/disklabel#AUTOMATIC_DISK_ALLOCATION) path is used (see its [source](./examples/cloud/autodisklabel)).
|
|
|
|
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](https://www.openbsd.org/policy.html). See the [LICENSE](LICENSE) file for more details.
|
|
|