diff --git a/README.md b/README.md index 6e1c08af..42338697 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# debos - Debian OS images builder +# debos - Debian OS image builder ## Synopsis @@ -27,14 +27,15 @@ Application Options: debos is a tool to make the creation of various Debian-based OS images simpler. While most other tools focus on specific use-cases, debos is -more meant as a tool-chain to make common actions trivial while providing -enough rope to do whatever tweaking that might be required behind the scene. +designed to be a toolchain making common actions trivial while providing +enough rope to do whatever tweaking which might be required behind the +scenes. -debos expects a YAML file as input and will run the actions listed in the +debos expects a YAML file as input and runs the actions listed in the file sequentially. These actions should be self-contained and independent of each other. -Some of the actions provided by debos to customize and produce images are: +Some of the actions provided by debos to customise and produce images are: * apt: install packages and their dependencies with 'apt' * debootstrap: construct the target rootfs with debootstrap @@ -57,14 +58,14 @@ https://godoc.org/github.com/go-debos/debos/actions ## Installation (Docker container) -Official debos container is available: +An official debos container is available: ``` docker pull godebos/debos ``` See [docker/README.md](https://github.com/go-debos/debos/blob/master/docker/README.md) for usage. -## Installation (under Debian) +## Installation from source (under Debian) sudo apt install golang git libglib2.0-dev libostree-dev qemu-system-x86 \ qemu-user-static debootstrap systemd-container @@ -74,9 +75,9 @@ See [docker/README.md](https://github.com/go-debos/debos/blob/master/docker/READ ## Simple example -The following example will create a arm64 image, install several +The following example will create an arm64 image, install several packages in it, change the file /etc/hostname to "debian" and finally -make a tarball. +make a tarball of the complete system. {{- $image := or .image "debian.tgz" -}} @@ -107,8 +108,8 @@ To run it, create a file named `example.yaml` and run: debos example.yaml The final tarball will be named "debian.tgz" if you would like to modify -this name, you can provided a different name for the variable image like -this: +the fileame, you can provided a different name for the variable image +like this: debos -t image:"debian-arm64.tgz" example.yaml @@ -120,10 +121,11 @@ https://github.com/go-debos/debos-recipes ## Environment variables -debos read a predefined list of environment variables from the host and -propagates it to fakemachine. The set of environment variables is defined by -environ_vars on cmd/debos/debos.go. Currently the list of environment variables -includes the proxy environment variables as documented at: +debos reads a predefined list of environment variables from the host and +propagates them to the fakemachine build environemnt. The set of +environment variables is defined by `environ_vars` in +`cmd/debos/debos.go`. Currently the list of environment variables includes +the proxy environment variables documented at: https://wiki.archlinux.org/index.php/proxy_settings @@ -131,48 +133,57 @@ The list of environment variables currently exported to fakemachine is: http_proxy, https_proxy, ftp_proxy, rsync_proxy, all_proxy, no_proxy -While the elements of environ_vars are in lower case, for each element both -lower and upper case variants are probed on the host, and if found propagated -to fakemachine. So if the host has the environment variables HTTP_PROXY and -no_proxy defined, both will be propagated to fakemachine respecting the case. +While the elements of `environ_vars` are in lower case, for each element +both lower and upper case variants are probed on the host and if found +propagated to fakemachine. So if the host has the environment variables +HTTP_PROXY and no_proxy defined, both will be propagated to fakemachine +respecting the case. -The command line options --environ-var and -e can be used to specify, -overwrite, and unset environment variables for fakemachine with the syntax: +The command line options `--environ-var` and `-e` can be used to specify, +overwrite and unset environment variables for fakemachine with the syntax: $ debos -e ENVIRONVAR:VALUE ... -To unset an enviroment variable, or in other words, to prevent an environment -variable to be propagated to fakemachine, use the same syntax without a value. -debos accept multiple -e simultaneously. +To unset an environment variable, or in other words, to prevent an +environment variable being propagated to fakemachine, use the same syntax +without a value. debos accepts multiple -e simultaneously. ## Proxy configuration -While the proxy related environment variables are exported from the host to -fakemachine, there are two known sources of issues: +While the proxy related environment variables are exported from the host +to fakemachine, there are two known sources of issues: -* Using localhost will not work from fakemachine. Prefer using an address that is valid on your network. debos will warn if environment variables contain localhost. +* Using localhost will not work from fakemachine. Use an address which + is valid on your network. debos will warn if the environment variables + contain localhost. -* In case you are running applications and/or scripts inside fakemachine you may need to check which are the proxy environment variables they use. Different apps are known to use different environment variable names and different case for environment variable names. +* In case you are running applications and/or scripts inside fakemachine + you may need to check which are the proxy environment variables they + use. Different apps are known to use different environment variable + names and different case for environment variable names. ## Fakemachine Backend -debos (unless running debos with the `--disable-fakemachine` argument) creates -and spawns a virtual machine using [fakemachine](https://github.com/go-debos/fakemachine) -and executes the actions defined by the recipe inside the virtual machine. This -helps ensure recipes are reproducible no matter the host environment. +debos (unless running debos with the `--disable-fakemachine` argument) +creates and spawns a virtual machine using [fakemachine](https://github.com/go-debos/fakemachine) +and executes the actions defined by the recipe inside the virtual machine. +This helps ensure recipes are reproducible no matter the host environment. -Fakemachine can use different virtualisation backends to spawn the virtualmachine, -for more information see the documentation under the [fakemachine repository](https://github.com/go-debos/fakemachine). +Fakemachine can use different virtualisation backends to spawn the virtual +machine, for more information see the [fakemachine documentation](https://github.com/go-debos/fakemachine). -By default the backend will automatically be selected based on what is supported -on the host machine, but this can be overridden using the `--fakemachine-backend` / `-b` -option. If no backends are supported, debos reverts to running the recipe on the -host without creating a fakemachine. +By default the backend will automatically be selected based on what is +supported by the host machine, but this can be overridden using the +`--fakemachine-backend` / `-b` option. If no backends are supported, +debos reverts to running the recipe on the host without creating a +fakemachine. -Performance of the backends is roughly as follows: `kvm` is faster than `uml` is faster than `qemu`. -Using `--disable-fakemachine` is slightly faster than `kvm`, but requires root permissions. +Performance of the backends is roughly as follows: `kvm` is faster than +`uml` is faster than `qemu`. Using `--disable-fakemachine` is slightly +faster than `kvm`, but requires root permissions. -Numbers for running [pine-a64-plus/debian.yaml](https://github.com/go-debos/debos-recipes/blob/9a25b4be6c9136f4a27e542f39ab7e419fc852c9/pine-a64-plus/debian.yaml) on an Intel Pentium G4560T with SSD: +Benchmark times for running [pine-a64-plus/debian.yaml](https://github.com/go-debos/debos-recipes/blob/9a25b4be6c9136f4a27e542f39ab7e419fc852c9/pine-a64-plus/debian.yaml) +on an Intel Pentium G4560T with SSD: | Backend | Wall Time | Prerequisites | | --- | --- | --- | diff --git a/doc/man/debos.1 b/doc/man/debos.1 index de3fd27c..bc4575dd 100644 --- a/doc/man/debos.1 +++ b/doc/man/debos.1 @@ -1,5 +1,20 @@ -.\" Automatically generated by Pandoc 2.9.2.1 +'\" t +.\" Automatically generated by Pandoc 3.1.3 .\" +.\" Define V font for inline verbatim, using C font in formats +.\" that render this, and otherwise B font. +.ie "\f[CB]x\f[]"x" \{\ +. ftr V B +. ftr VI BI +. ftr VB B +. ftr VBI BI +.\} +.el \{\ +. ftr V CR +. ftr VI CI +. ftr VB CB +. ftr VBI CBI +.\} .TH "debos" "1" "" "" "" .hy .SH NAME @@ -38,15 +53,15 @@ Application Options: .PP debos is a tool to make the creation of various Debian-based OS images simpler. -While most other tools focus on specific use-cases, debos is more meant -as a tool-chain to make common actions trivial while providing enough -rope to do whatever tweaking that might be required behind the scene. +While most other tools focus on specific use-cases, debos is designed to +be a toolchain making common actions trivial while providing enough rope +to do whatever tweaking which might be required behind the scenes. .PP -debos expects a YAML file as input and will run the actions listed in -the file sequentially. +debos expects a YAML file as input and runs the actions listed in the +file sequentially. These actions should be self-contained and independent of each other. .PP -Some of the actions provided by debos to customize and produce images +Some of the actions provided by debos to customise and produce images are: .IP \[bu] 2 apt: install packages and their dependencies with `apt' @@ -85,7 +100,7 @@ A full syntax description of all the debos actions can be found at: https://godoc.org/github.com/go-debos/debos/actions .SH INSTALLATION (DOCKER CONTAINER) .PP -Official debos container is available: +An official debos container is available: .IP .nf \f[C] @@ -96,22 +111,22 @@ docker pull godebos/debos See docker/README.md (https://github.com/go-debos/debos/blob/master/docker/README.md) for usage. -.SH INSTALLATION (UNDER DEBIAN) +.SH INSTALLATION FROM SOURCE (UNDER DEBIAN) .IP .nf \f[C] sudo apt install golang git libglib2.0-dev libostree-dev qemu-system-x86 \[rs] qemu-user-static debootstrap systemd-container -export GOPATH=/opt/src/gocode # or whatever suites your needs -go get -u github.com/go-debos/debos/cmd/debos +export GOPATH=/opt/src/gocode # or whatever suits your needs +go install -v github.com/go-debos/debos/cmd/debos\[at]latest /opt/src/gocode/bin/debos --help \f[R] .fi .SH SIMPLE EXAMPLE .PP -The following example will create a arm64 image, install several +The following example will create an arm64 image, install several packages in it, change the file /etc/hostname to \[lq]debian\[rq] and -finally make a tarball. +finally make a tarball of the complete system. .IP .nf \f[C] @@ -121,10 +136,10 @@ architecture: arm64 actions: - action: debootstrap - suite: \[dq]buster\[dq] + suite: bookworm components: - main - - non-free + - non-free-firmware mirror: https://deb.debian.org/debian variant: minbase @@ -141,7 +156,7 @@ actions: \f[R] .fi .PP -To run it, create a file named \f[C]example.yaml\f[R] and run: +To run it, create a file named \f[V]example.yaml\f[R] and run: .IP .nf \f[C] @@ -150,8 +165,8 @@ debos example.yaml .fi .PP The final tarball will be named \[lq]debian.tgz\[rq] if you would like -to modify this name, you can provided a different name for the variable -image like this: +to modify the fileame, you can provided a different name for the +variable image like this: .IP .nf \f[C] @@ -160,16 +175,17 @@ debos -t image:\[dq]debian-arm64.tgz\[dq] example.yaml .fi .SH OTHER EXAMPLES .PP -This example builds a customized image for a Raspberry Pi 3. +Example recipes are collected in a separate repository: +.PP https://github.com/go-debos/debos-recipes .SH ENVIRONMENT VARIABLES .PP -debos read a predefined list of environment variables from the host and -propagates it to fakemachine. -The set of environment variables is defined by environ_vars on -cmd/debos/debos.go. +debos reads a predefined list of environment variables from the host and +propagates them to the fakemachine build environemnt. +The set of environment variables is defined by \f[V]environ_vars\f[R] in +\f[V]cmd/debos/debos.go\f[R]. Currently the list of environment variables includes the proxy -environment variables as documented at: +environment variables documented at: .PP https://wiki.archlinux.org/index.php/proxy_settings .PP @@ -181,30 +197,34 @@ http_proxy, https_proxy, ftp_proxy, rsync_proxy, all_proxy, no_proxy \f[R] .fi .PP -While the elements of environ_vars are in lower case, for each element -both lower and upper case variants are probed on the host, and if found -propagated to fakemachine. +While the elements of \f[V]environ_vars\f[R] are in lower case, for each +element both lower and upper case variants are probed on the host and if +found propagated to fakemachine. So if the host has the environment variables HTTP_PROXY and no_proxy defined, both will be propagated to fakemachine respecting the case. .PP -The command line options \[en]environ-var and -e can be used to specify, -overwrite, and unset environment variables for fakemachine with the -syntax: -.PP -$ debos -e ENVIRONVAR:VALUE \&... +The command line options \f[V]--environ-var\f[R] and \f[V]-e\f[R] can be +used to specify, overwrite and unset environment variables for +fakemachine with the syntax: +.IP +.nf +\f[C] +$ debos -e ENVIRONVAR:VALUE ... +\f[R] +.fi .PP -To unset an enviroment variable, or in other words, to prevent an -environment variable to be propagated to fakemachine, use the same +To unset an environment variable, or in other words, to prevent an +environment variable being propagated to fakemachine, use the same syntax without a value. -debos accept multiple -e simultaneously. +debos accepts multiple -e simultaneously. .SH PROXY CONFIGURATION .PP While the proxy related environment variables are exported from the host to fakemachine, there are two known sources of issues: .IP \[bu] 2 Using localhost will not work from fakemachine. -Prefer using an address that is valid on your network. -debos will warn if environment variables contain localhost. +Use an address which is valid on your network. +debos will warn if the environment variables contain localhost. .IP \[bu] 2 In case you are running applications and/or scripts inside fakemachine you may need to check which are the proxy environment variables they @@ -213,7 +233,7 @@ Different apps are known to use different environment variable names and different case for environment variable names. .SH FAKEMACHINE BACKEND .PP -debos (unless running debos with the \f[C]--disable-fakemachine\f[R] +debos (unless running debos with the \f[V]--disable-fakemachine\f[R] argument) creates and spawns a virtual machine using fakemachine (https://github.com/go-debos/fakemachine) and executes the actions defined by the recipe inside the virtual machine. @@ -221,11 +241,61 @@ This helps ensure recipes are reproducible no matter the host environment. .PP Fakemachine can use different virtualisation backends to spawn the -virtualmachine, for more information see the documentation under the -fakemachine repository (https://github.com/go-debos/fakemachine). +virtual machine, for more information see the fakemachine +documentation (https://github.com/go-debos/fakemachine). .PP By default the backend will automatically be selected based on what is -supported on the host machine, but this can be overridden using the -\f[C]--fakemachine-backend\f[R] option. +supported by the host machine, but this can be overridden using the +\f[V]--fakemachine-backend\f[R] / \f[V]-b\f[R] option. If no backends are supported, debos reverts to running the recipe on the host without creating a fakemachine. +.PP +Performance of the backends is roughly as follows: \f[V]kvm\f[R] is +faster than \f[V]uml\f[R] is faster than \f[V]qemu\f[R]. +Using \f[V]--disable-fakemachine\f[R] is slightly faster than +\f[V]kvm\f[R], but requires root permissions. +.PP +Benchmark times for running +pine-a64-plus/debian.yaml (https://github.com/go-debos/debos-recipes/blob/9a25b4be6c9136f4a27e542f39ab7e419fc852c9/pine-a64-plus/debian.yaml) +on an Intel Pentium G4560T with SSD: +.PP +.TS +tab(@); +l l l. +T{ +Backend +T}@T{ +Wall Time +T}@T{ +Prerequisites +T} +_ +T{ +\f[V]--disable-fakemachine\f[R] +T}@T{ +8 min +T}@T{ +root permissions +T} +T{ +\f[V]-b kvm\f[R] +T}@T{ +9 min +T}@T{ +access to \f[V]/dev/kvm\f[R] +T} +T{ +\f[V]-b uml\f[R] +T}@T{ +18 min +T}@T{ +package \f[V]user-mode-linux\f[R] installed +T} +T{ +\f[V]-b qemu\f[R] +T}@T{ +166 min +T}@T{ +none +T} +.TE