117 lines
5.4 KiB
Markdown
117 lines
5.4 KiB
Markdown
``` ██████ ██ ▄█▀▒███████▒ ▒█████ ██▓███ ▄▄▄ ▄████▄ ██ ▄█▀
|
|
▒██ ▒ ██▄█▒ ▒ ▒ ▒ ▄▀░ ▒██▒ ██▒▓██░ ██ ▒████▄ ▒██▀ ▀█ ██▄█▒
|
|
░ ▓██▄ ▓███▄░ ░ ▒ ▄▀▒ ▓▒█ ▒██░ ██▒▓██░ ██▓▒▒██ ▀█▄ ▒▓█ ▄ ▓███▄░
|
|
▒ ██▒▓██ █▄ ▄▀▒ ░▒ ▒██ ██░▒██▄█▓▒ ▒░██▄▄▄▄██ ▒▓▓▄ ▄██▒▓██ █▄
|
|
▒██████▒▒▒██▒ █▄▒███████▒░ ████▓▒░▒██▒ ░ ░ ▓█ ▓██▒▒ ▓███▀ ░▒██▒ █▄
|
|
▒ ▒▓▒ ▒ ░▒ ▒▒ ▓▒░▒▒ ▓░▒░▒░ ░ ▒░▒░▒░ ▒▓▒░ ░ ░ ▒▒ ▓▒█░░ ░▒ ▒ ░▒ ▒▒ ▓▒
|
|
░ ░▒ ░ ░░ ░▒ ▒░░░ https://git.sk4.nz/sk4nz/skz-opack ▒▒ ░ ░ ▒ ░ ░▒ ▒░
|
|
░ ░ ░ ░ ░ ░ ░ ░ ░░ ░ ░ ░
|
|
░ ░```
|
|
-----
|
|
*Samuel 'sk4nz' AUBERTIN*
|
|
|
|
**skz-opack** enables simple execution of [OpenBSD](https://www.openbsd.org) virtual machines from a Linux host or Google Cloud Compute, leveraging Packer and Vagrant, from a Makefile target named `opack`.
|
|
|
|
## 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 and manage OpenBSD virtual machines with Packer and Vagrant.
|
|
|
|
## Architecture
|
|
|
|
|
|
|
|
## Available make targets
|
|
Available make target are:
|
|
- `opack`
|
|
- `opack-cloud`
|
|
- `opack-clean`
|
|
- `opack-cleancache`
|
|
- `opack-cleanall`
|
|
|
|
## 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.
|
|
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 everythin, use `make cleancache`).
|
|
|
|
### Complex Example
|
|
|
|
In this example, we will demonstrate how to use **skz-opack** to create an OpenBSD -current virtual machine with 4 CPUs, 1GB of RAM, and name it "run-current."
|
|
|
|
```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. Every option ending with an `?` in "src/options.mk" can be overrided in the invoking Makefile.
|
|
|
|
### GCP example
|
|
|
|
TODO
|
|
|
|
## Troubleshooting
|
|
|
|
Overrides should happen before the include of "opack.mk".
|
|
|
|
## 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/)
|
|
|