From: Zbigniew Jędrzejewski-Szmek Date: Sun, 16 Apr 2023 12:35:37 +0000 (+0200) Subject: man: regenerate man page X-Git-Tag: v15~234^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c9048608937f86cdd32995ad8bb694fc5e0eaa2a;p=thirdparty%2Fmkosi.git man: regenerate man page --- diff --git a/man/mkosi.1 b/man/mkosi.1 index 8b8c4c00c..3e7f30d6e 100644 --- a/man/mkosi.1 +++ b/man/mkosi.1 @@ -1,5 +1,19 @@ -.\" Automatically generated by Pandoc 2.14.0.3 +.\" Automatically generated by Pandoc 2.19.2 .\" +.\" 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 "mkosi" "1" "2016-" "" "" .hy .SH NAME @@ -7,241 +21,166 @@ mkosi \[em] Build Bespoke OS Images .SH SYNOPSIS .PP -\f[C]mkosi [options\&...] summary\f[R] +\f[V]mkosi [options\&...] summary\f[R] .PP -\f[C]mkosi [options\&...] build [script parameters\&...]\f[R] +\f[V]mkosi [options\&...] build [script parameters\&...]\f[R] .PP -\f[C]mkosi [options\&...] shell [command line\&...]\f[R] +\f[V]mkosi [options\&...] shell [command line\&...]\f[R] .PP -\f[C]mkosi [options\&...] boot [nspawn settings\&...]\f[R] +\f[V]mkosi [options\&...] boot [nspawn settings\&...]\f[R] .PP -\f[C]mkosi [options\&...] qemu [qemu parameters\&...]\f[R] +\f[V]mkosi [options\&...] qemu [qemu parameters\&...]\f[R] .PP -\f[C]mkosi [options\&...] ssh [command line\&...]\f[R] +\f[V]mkosi [options\&...] ssh [command line\&...]\f[R] .PP -\f[C]mkosi [options\&...] clean\f[R] +\f[V]mkosi [options\&...] clean\f[R] .PP -\f[C]mkosi [options\&...] serve\f[R] +\f[V]mkosi [options\&...] serve\f[R] .PP -\f[C]mkosi [options\&...] bump\f[R] +\f[V]mkosi [options\&...] bump\f[R] .PP -\f[C]mkosi [options\&...] genkey\f[R] +\f[V]mkosi [options\&...] genkey\f[R] .PP -\f[C]mkosi [options\&...] help\f[R] +\f[V]mkosi [options\&...] help\f[R] .SH DESCRIPTION .PP -\f[C]mkosi\f[R] is a tool for easily building customized OS images. -It\[cq]s a fancy wrapper around \f[C]dnf --installroot\f[R], -\f[C]debootstrap\f[R], \f[C]pacman\f[R] and \f[C]zypper\f[R] that may -generate disk images with a number of bells and whistles. +\f[V]mkosi\f[R] is a tool for easily building customized OS images. +It\[cq]s a fancy wrapper around \f[V]dnf --installroot\f[R], +\f[V]apt\f[R], \f[V]pacman\f[R] and \f[V]zypper\f[R] that may generate +disk images with a number of bells and whistles. .SS Command Line Verbs .PP The following command line verbs are known: .TP -\f[B]\f[CB]summary\f[B]\f[R] +\f[V]summary\f[R] Outputs a human-readable summary of all options used for building an image. -This will parse the command line and \f[C]mkosi.conf\f[R] file as it -would do on \f[C]build\f[R], but only output what it is configured for +This will parse the command line and \f[V]mkosi.conf\f[R] file as it +would do on \f[V]build\f[R], but only output what it is configured for and not actually build anything.\[ga] .TP -\f[B]\f[CB]build\f[B]\f[R] +\f[V]build\f[R] This builds the image based on the settings passed in on the command -line or read from a \f[C]mkosi.conf\f[R] file. +line or read from a \f[V]mkosi.conf\f[R] file. This command is the default if no verb is explicitly specified. -This command must be executed as \f[C]root\f[R]. -Any arguments passed after the \f[C]build\f[R] verb are passed as +This command must be executed as \f[V]root\f[R]. +Any arguments passed after the \f[V]build\f[R] verb are passed as arguments to the build script (if there is one). .TP -\f[B]\f[CB]shell\f[B]\f[R] +\f[V]shell\f[R] This builds the image if it is not built yet, and then invokes -\f[C]systemd-nspawn\f[R] to acquire an interactive shell prompt in it. -An optional command line may be specified after the \f[C]shell\f[R] +\f[V]systemd-nspawn\f[R] to acquire an interactive shell prompt in it. +An optional command line may be specified after the \f[V]shell\f[R] verb, to be invoked in place of the shell in the container. -Use \f[C]-f\f[R] in order to rebuild the image unconditionally before +Use \f[V]-f\f[R] in order to rebuild the image unconditionally before acquiring the shell, see below. -This command must be executed as \f[C]root\f[R]. +This command must be executed as \f[V]root\f[R]. .TP -\f[B]\f[CB]boot\f[B]\f[R] -Similar to \f[C]shell\f[R], but boots the image using -\f[C]systemd-nspawn\f[R]. -An optional command line may be specified after the \f[C]boot\f[R] verb, +\f[V]boot\f[R] +Similar to \f[V]shell\f[R], but boots the image using +\f[V]systemd-nspawn\f[R]. +An optional command line may be specified after the \f[V]boot\f[R] verb, which is then passed as the \[lq]kernel command line\[rq] to the init system in the image. .TP -\f[B]\f[CB]qemu\f[B]\f[R] -Similar to \f[C]boot\f[R], but uses \f[C]qemu\f[R] to boot up the image, +\f[V]qemu\f[R] +Similar to \f[V]boot\f[R], but uses \f[V]qemu\f[R] to boot up the image, i.e.\ instead of container virtualization virtual machine virtualization is used. -This verb is only supported for images that contain a boot loader, -i.e.\ those built with \f[C]Bootable=yes\f[R] (see below). -This command must be executed as \f[C]root\f[R] unless the image already -exists and \f[C]-f\f[R] is not specified. -Any options specified after the \f[C]qemu\f[R] verb are appended to the -\f[C]qemu\f[R] invocation. -.TP -\f[B]\f[CB]ssh\f[B]\f[R] -When the image is built with the \f[C]Ssh=yes\f[R] option, this command -connects to a booted (\f[C]boot\f[R], \f[C]qemu\f[R] verbs) container or +This verb is only supported for disk images that contain a boot loader. +Any options specified after the \f[V]qemu\f[R] verb are appended to the +\f[V]qemu\f[R] invocation. +.TP +\f[V]ssh\f[R] +When the image is built with the \f[V]Ssh=yes\f[R] option, this command +connects to a booted (\f[V]boot\f[R], \f[V]qemu\f[R] verbs) container or VM via SSH. -Make sure to run \f[C]mkosi ssh\f[R] with the same config as -\f[C]mkosi build\f[R] was run with so that it has the necessary +Make sure to run \f[V]mkosi ssh\f[R] with the same config as +\f[V]mkosi build\f[R] was run with so that it has the necessary information available to connect to the running container/VM via SSH. -Any arguments passed after the \f[C]ssh\f[R] verb are passed as -arguments to the \f[C]ssh\f[R] invocation. +Any arguments passed after the \f[V]ssh\f[R] verb are passed as +arguments to the \f[V]ssh\f[R] invocation. .TP -\f[B]\f[CB]clean\f[B]\f[R] +\f[V]clean\f[R] Remove build artifacts generated on a previous build. -If combined with \f[C]-f\f[R], also removes incremental build cache +If combined with \f[V]-f\f[R], also removes incremental build cache images. -If \f[C]-f\f[R] is specified twice, also removes any package cache. +If \f[V]-f\f[R] is specified twice, also removes any package cache. .TP -\f[B]\f[CB]serve\f[B]\f[R] +\f[V]serve\f[R] This builds the image if it is not built yet, and then serves the output -directory (i.e.\ usually \f[C]mkosi.output/\f[R], see below) via a small +directory (i.e.\ usually \f[V]mkosi.output/\f[R], see below) via a small embedded HTTP server, listening on port 8081. -Combine with \f[C]-f\f[R] in order to rebuild the image unconditionally +Combine with \f[V]-f\f[R] in order to rebuild the image unconditionally before serving it. This command is useful for testing network based acquisition of OS -images, for example via \f[C]machinectl pull-raw \&...\f[R] and -\f[C]machinectl pull-tar \&...\f[R]. +images, for example via \f[V]machinectl pull-raw \&...\f[R] and +\f[V]machinectl pull-tar \&...\f[R]. .TP -\f[B]\f[CB]bump\f[B]\f[R] +\f[V]bump\f[R] Determines the current image version string (as configured with -\f[C]ImageVersion=\f[R]/\f[C]--image-version=\f[R]), increases its last +\f[V]ImageVersion=\f[R]/\f[V]--image-version=\f[R]), increases its last dot-separated component by one and writes the resulting version string -to \f[C]mkosi.version\f[R]. +to \f[V]mkosi.version\f[R]. This is useful for implementing a simple versioning scheme: each time this verb is called the version is bumped in preparation for the subsequent build. -Note that \f[C]--auto-bump\f[R]/\f[C]-B\f[R] may be used to +Note that \f[V]--auto-bump\f[R]/\f[V]-B\f[R] may be used to automatically bump the version after each successful build. .TP -\f[B]\f[CB]genkey\f[B]\f[R] +\f[V]genkey\f[R] Generate a pair of SecureBoot keys for usage with the -\f[C]SecureBootKey=\f[R]/\f[C]--secure-boot-key=\f[R] and -\f[C]SecureBootCertificate=\f[R]/\f[C]--secure-boot-certificate=\f[R] +\f[V]SecureBootKey=\f[R]/\f[V]--secure-boot-key=\f[R] and +\f[V]SecureBootCertificate=\f[R]/\f[V]--secure-boot-certificate=\f[R] options. .TP -\f[B]\f[CB]help\f[B]\f[R] -This verb is equivalent to the \f[C]--help\f[R] switch documented below: +\f[V]help\f[R] +This verb is equivalent to the \f[V]--help\f[R] switch documented below: it shows a brief usage explanation. -.SS Execution flow +.SS Execution Flow .PP -Execution flow for \f[C]mkosi build\f[R]. -Columns represent the execution context. +Execution flow for \f[V]mkosi build\f[R]. Default values/calls are shown in parentheses. -When building with \f[C]--incremental\f[R] mkosi creates a cache of the -distribution installation for both images if not already existing and -replaces the distribution installation in consecutive runs with data -from the cached one. -.IP -.nf -\f[C] - HOST . BUILD . FINAL - . IMAGE . IMAGE - . . - start . . - | . . - v . . -build script? -------exists-----> copy . - | . skeleton trees . - | . (mkosi.skeleton/) . - none . | . - | . v . - v . install . - skip . distribution, . - build image . packages and . - | . build packages, . - | . run . - | . prepare script . - | . (mkosi.prepare build) . - | . or if incremental . - | . use cached build image . - | . | . - | . v . - | . copy . - | . build sources . - | . (./) . - | . | . - | . v . - | . copy . - | . extra trees . - | . (mkosi.extra/) . - | . | . - | . v . - | . run . - | . postinstall script . - | . (mkosi.postinst build) . - | . | . - | .-------------------------\[aq] . - | | . . - | v . . - | run . . - | finalize script . . - |(mkosi.finalize build). . - | | . . - | \[aq]-------------------------. . - | . | . - | . v . - | . run . - | . build script . - | . (mkosi.build) . - | . | . - \[aq]-----------------------------------+------------------------. - . . | - . . v - . . copy - . . skeleton trees - . . (mkosi.skeleton/) - . . | - . . v - . . install - . . distribution - . . and packages, - . . run - . . prepare script - . . (mkosi.prepare final) - . . or if incremental - . . use cached final image - . . | - . . v - . . copy - . . build results - . . | - . . v - . . copy - . . extra trees - . . (mkosi.extra/) - . . | - . . v - . . run - . . postinstall script - . . (mkosi.postinst final) - . . | - . . v - . . | - . . perform cleanup - . . (remove files, packages, - . . package metadata) - . . | - .--------------------------------------------------\[aq] - | . . - v . . - run . . - finalize script . . - (mkosi.finalize final) . . - | . . - .---------\[aq] . . - | . . - v . . - end . . - . . - HOST . BUILD . FINAL - . IMAGE . IMAGE - . . -\f[R] -.fi +When building with \f[V]--incremental\f[R] mkosi creates a cache of the +distribution installation if not already existing and replaces the +distribution installation in consecutive runs with data from the cached +one. +.IP \[bu] 2 +Copy skeleton trees (\f[V]mkosi.skeleton\f[R]) into image +.IP \[bu] 2 +Install distribution and packages into image or use cache tree if +available +.IP \[bu] 2 +Install build packages in overlay if a build script is configured +.IP \[bu] 2 +Run prepare script on image and on image + build overlay if a build +script is configured (\f[V]mkosi.prepare\f[R]) +.IP \[bu] 2 +Run build script on image + build overlay if a build script is +configured (\f[V]mkosi.build\f[R]) +.IP \[bu] 2 +Copy the build script outputs into the image +.IP \[bu] 2 +Copy the extra trees into the image (\f[V]mkosi.extra\f[R]) +.IP \[bu] 2 +Run \f[V]kernel-install\f[R] +.IP \[bu] 2 +Install systemd-boot +.IP \[bu] 2 +Run post-install script (\f[V]mkosi.postinst\f[R]) +.IP \[bu] 2 +Run \f[V]systemctl preset-all\f[R] +.IP \[bu] 2 +Remove packages and files (\f[V]RemovePackages=\f[R], +\f[V]RemoveFiles=\f[R]) +.IP \[bu] 2 +Run finalize script (\f[V]mkosi.finalize\f[R]) +.IP \[bu] 2 +Run SELinux relabel is a SELinux policy is installed +.IP \[bu] 2 +Generate unified kernel image +.IP \[bu] 2 +Generate final output format .SS Supported output formats .PP The following output formats are supported: @@ -258,64 +197,121 @@ CPIO archive (\f[I]cpio\f[R]) in the format appropriate for a kernel initrd .PP When a \f[I]GPT\f[R] disk image is created, repart partition definition -files may be placed in \f[C]mkosi.repart/\f[R] to configure the +files may be placed in \f[V]mkosi.repart/\f[R] to configure the generated disk image. .SS Configuration Settings .PP The following settings can be set through configuration files (the -syntax with \f[C]SomeSetting=value\f[R]) and on the command line (the -syntax with \f[C]--some-setting=value\f[R]). +syntax with \f[V]SomeSetting=value\f[R]) and on the command line (the +syntax with \f[V]--some-setting=value\f[R]). For some command line parameters, a single-letter shortcut is also allowed. In the configuration files, the setting must be in the appropriate section, so the settings are grouped by section below. .PP +Configuration is parsed in the following order: +.IP \[bu] 2 +The command line arguments are parsed +.IP \[bu] 2 +\f[V]mkosi.conf\f[R] is parsed if it exists in the directory set with +\f[V]--directory=\f[R] or the current working directory if +\f[V]--directory=\f[R] is not used. +.IP \[bu] 2 +\f[V]mkosi.conf.d/\f[R] is parsed in the same directory if it exists. +Each directory and each file with the \f[V].conf\f[R] extension in +\f[V]mkosi.conf.d/\f[R] is parsed. +Any directory in \f[V]mkosi.conf.d\f[R] is parsed as if it were a +regular top level directory. +.IP \[bu] 2 +Any default paths (depending on the option) are configured if the +corresponding path exists. +.PP +If a setting is specified multiple times across the different sources of +configuration, the first assignment that is found is used. +For example, a setting specified on the command line will always take +precedence over the same setting configured in a config file. +To override settings in a dropin file, make sure your dropin file is +alphanumerically ordered before the config file that you\[cq]re trying +to override. +.PP +Settings that take a list of values are merged by prepending each value +to the previously configured values. +If a value of a list setting is prefixed with \f[V]!\f[R], if any later +assignment of that setting tries to add the same value, that value is +ignored. +Values prefixed with \f[V]!\f[R] can be globs to ignore more than one +value. +.PP +To conditionally include configuration files, the \f[V][Match]\f[R] +section can be used. +A configuration file is only included if all the conditions in the +\f[V][Match]\f[R] block are satisfied. +If a condition in \f[V][Match]\f[R] depends on a setting and the setting +has not been explicitly configured when the condition is evaluated, the +setting is assigned its default value. +.PP Command line options that take no argument are shown without \[lq]=\[rq] in their long version. In the config files, they should be specified with a boolean argument: either \[lq]1\[rq], \[lq]yes\[rq], or \[lq]true\[rq] to enable, or \[lq]0\[rq], \[lq]no\[rq], \[lq]false\[rq] to disable. +.SS [Match] Section. +.TP +\f[V]Distribution=\f[R] +Matches against the configured distribution. +.TP +\f[V]Release=\f[R] +Matches against the configured distribution release. +If this condition is used and no distribution has been explicitly +configured yet, the host distribution and release are used. +.TP +\f[V]PathExists=\f[R] +This condition is satisfied if the given path exists. +Relative paths are interpreted relative to the parent directory of the +config file that the condition is read from. .SS [Distribution] Section .TP -\f[B]\f[CB]Distribution=\f[B]\f[R], \f[B]\f[CB]--distribution=\f[B]\f[R], \f[B]\f[CB]-d\f[B]\f[R] +\f[V]Distribution=\f[R], \f[V]--distribution=\f[R], \f[V]-d\f[R] The distribution to install in the image. -Takes one of the following arguments: \f[C]fedora\f[R], -\f[C]debian\f[R], \f[C]ubuntu\f[R], \f[C]arch\f[R], \f[C]opensuse\f[R], -\f[C]mageia\f[R], \f[C]centos\f[R], \f[C]openmandriva\f[R], -\f[C]rocky\f[R], and \f[C]alma\f[R]. +Takes one of the following arguments: \f[V]fedora\f[R], +\f[V]debian\f[R], \f[V]ubuntu\f[R], \f[V]arch\f[R], \f[V]opensuse\f[R], +\f[V]mageia\f[R], \f[V]centos\f[R], \f[V]openmandriva\f[R], +\f[V]rocky\f[R], and \f[V]alma\f[R]. If not specified, defaults to the distribution of the host. +Whenever a distribution is assigned, the release is reset to the default +release configured for that distribution. .TP -\f[B]\f[CB]Release=\f[B]\f[R], \f[B]\f[CB]--release=\f[B]\f[R], \f[B]\f[CB]-r\f[B]\f[R] +\f[V]Release=\f[R], \f[V]--release=\f[R], \f[V]-r\f[R] The release of the distribution to install in the image. The precise syntax of the argument this takes depends on the distribution used, and is either a numeric string (in case of Fedora -Linux, CentOS, \&..., e.g.\ \f[C]29\f[R]), or a distribution version -name (in case of Debian, Ubuntu, \&..., e.g.\ \f[C]artful\f[R]). +Linux, CentOS, \&..., e.g.\ \f[V]29\f[R]), or a distribution version +name (in case of Debian, Ubuntu, \&..., e.g.\ \f[V]artful\f[R]). Defaults to a recent version of the chosen distribution. .TP -\f[B]\f[CB]Mirror=\f[B]\f[R], \f[B]\f[CB]--mirror=\f[B]\f[R], \f[B]\f[CB]-m\f[B]\f[R] +\f[V]Mirror=\f[R], \f[V]--mirror=\f[R], \f[V]-m\f[R] The mirror to use for downloading the distribution packages. Expects a mirror URL as argument. .TP -\f[B]\f[CB]LocalMirror=\f[B]\f[R], \f[B]\f[CB]--local-mirror=\f[B]\f[R] +\f[V]LocalMirror=\f[R], \f[V]--local-mirror=\f[R] The mirror will be used as a local, plain and direct mirror instead of using it as a prefix for the full set of repositories normally supported by distributions. Useful for fully offline builds with a single repository. Supported on deb/rpm/arch based distributions. -Overrides \f[C]--mirror=\f[R] but only for the local mkosi build, it -will not be configured inside the final image, \f[C]--mirror=\f[R] (or +Overrides \f[V]--mirror=\f[R] but only for the local mkosi build, it +will not be configured inside the final image, \f[V]--mirror=\f[R] (or the default repository) will be configured inside the final image instead. .TP -\f[B]\f[CB]RepositoryKeyCheck=\f[B]\f[R], \f[B]\f[CB]--repository-key-check=\f[B]\f[R] +\f[V]RepositoryKeyCheck=\f[R], \f[V]--repository-key-check=\f[R] Controls signature/key checks when using repositories, enabled by default. -Useful to disable checks when combined with \f[C]--local-mirror=\f[R] +Useful to disable checks when combined with \f[V]--local-mirror=\f[R] and using only a repository from a local filesystem. Not used for DNF-based distros yet. .TP -\f[B]\f[CB]Repositories=\f[B]\f[R], \f[B]\f[CB]--repositories=\f[B]\f[R] +\f[V]Repositories=\f[R], \f[V]--repositories=\f[R] Additional package repositories to use during installation. Expects one or more URLs as argument, separated by commas. This option may be used multiple times, in which case the list of @@ -323,9 +319,9 @@ repositories to use is combined. Use \[lq]!*\[rq] to remove all repositories from to the list or use e.g.\ \[lq]!repo-url\[rq] to remove just one specific repository. For Arch Linux, additional repositories must be passed in the form -\f[C]::\f[R] (e.g.\ \f[C]myrepo::https://myrepo.net\f[R]). +\f[V]::\f[R] (e.g.\ \f[V]myrepo::https://myrepo.net\f[R]). .TP -\f[B]\f[CB]RepositoryDirectories\f[B]\f[R], \f[B]\f[CB]--repository-directory\f[B]\f[R] +\f[V]RepositoryDirectories\f[R], \f[V]--repo-dir=\f[R] This option can (for now) only be used with RPM-based distributions and Arch Linux. It takes a comma separated list of directories containing extra @@ -334,73 +330,74 @@ The files are passed directly to the corresponding package manager and should be written in the format expected by the package manager of the image\[cq]s distro. .TP -\f[B]\f[CB]Architecture=\f[B]\f[R], \f[B]\f[CB]--architecture=\f[B]\f[R] +\f[V]Architecture=\f[R], \f[V]--architecture=\f[R] The architecture to build the image for. Note that this currently only works for architectures compatible with the host\[cq]s architecture. .SS [Output] Section .TP -\f[B]\f[CB]Format=\f[B]\f[R], \f[B]\f[CB]--format=\f[B]\f[R], \f[B]\f[CB]-t\f[B]\f[R] +\f[V]Format=\f[R], \f[V]--format=\f[R], \f[V]-t\f[R] The image format type to generate. -One of \f[C]directory\f[R] (for generating OS images inside a local -directory), \f[C]subvolume\f[R] (similar, but as a btrfs subvolume), -\f[C]tar\f[R] (similar, but a tarball of the image is generated), -\f[C]cpio\f[R] (similar, but a cpio archive is generated), -\f[C]disk\f[R] (a block device image with a GPT partition table). +One of \f[V]directory\f[R] (for generating OS images inside a local +directory), \f[V]subvolume\f[R] (similar, but as a btrfs subvolume), +\f[V]tar\f[R] (similar, but a tarball of the image is generated), +\f[V]cpio\f[R] (similar, but a cpio archive is generated), +\f[V]disk\f[R] (a block device image with a GPT partition table). .TP -\f[B]\f[CB]ManifestFormat=\f[B]\f[R], \f[B]\f[CB]--manifest-format=\f[B]\f[R] +\f[V]ManifestFormat=\f[R], \f[V]--manifest-format=\f[R] The manifest format type or types to generate. -A comma-delimited list consisting of \f[C]json\f[R] (the standard JSON +A comma-delimited list consisting of \f[V]json\f[R] (the standard JSON output format that describes the packages installed), -\f[C]changelog\f[R] (a human-readable text format designed for diffing). -Defaults to \f[C]json\f[R]. +\f[V]changelog\f[R] (a human-readable text format designed for diffing). +Defaults to \f[V]json\f[R]. .TP -\f[B]\f[CB]Output=\f[B]\f[R], \f[B]\f[CB]--output=\f[B]\f[R], \f[B]\f[CB]-o\f[B]\f[R] +\f[V]Output=\f[R], \f[V]--output=\f[R], \f[V]-o\f[R] Path for the output image file to generate. Takes a relative or absolute path where the generated image will be placed. -If neither this option nor \f[C]OutputDirectory=\f[R] is used, the image -is generated under the name \f[C]image\f[R], but its name suffixed with -an appropriate file suffix (e.g.\ \f[C]image.raw.xz\f[R] in case -\f[C]gpt_ext4\f[R] is used in combination with \f[C]xz\f[R] +If neither this option nor \f[V]OutputDirectory=\f[R] is used, the image +is generated under the name \f[V]image\f[R], but its name suffixed with +an appropriate file suffix (e.g.\ \f[V]image.raw.xz\f[R] in case +\f[V]gpt_ext4\f[R] is used in combination with \f[V]xz\f[R] compression). -If the \f[C]ImageId=\f[R] option is configured it is used instead of -\f[C]image\f[R] in the default output name. -If an image version is specified via \f[C]ImageVersion=\f[R], it is +If the \f[V]ImageId=\f[R] option is configured it is used instead of +\f[V]image\f[R] in the default output name. +If an image version is specified via \f[V]ImageVersion=\f[R], it is included in the default name, e.g.\ a specified image version of -\f[C]7.8\f[R] might result in an image file name of -\f[C]image_7.8.raw.xz\f[R]. +\f[V]7.8\f[R] might result in an image file name of +\f[V]image_7.8.raw.xz\f[R]. .TP -\f[B]\f[CB]OutputDirectory=\f[B]\f[R], \f[B]\f[CB]--output-dir=\f[B]\f[R], \f[B]\f[CB]-O\f[B]\f[R] +\f[V]OutputDirectory=\f[R], \f[V]--output-dir=\f[R], \f[V]-O\f[R] Path to a directory where to place all generated artifacts (i.e.\ the -generated image when an output path is not given, \f[C]SHA256SUMS\f[R] +generated image when an output path is not given, \f[V]SHA256SUMS\f[R] file, etc.). -If this is not specified and the directory \f[C]mkosi.output/\f[R] +If this is not specified and the directory \f[V]mkosi.output/\f[R] exists in the local directory, it is automatically used for this purpose. -If the setting is not used and \f[C]mkosi.output/\f[R] does not exist, +If the setting is not used and \f[V]mkosi.output/\f[R] does not exist, all output artifacts are placed adjacent to the output image file. If an output directory is configured, mkosi will create -\f[C]distro\[ti]release\f[R] subdirectories in it to store the +\f[V]distro\[ti]release\f[R] subdirectories in it to store the artfifacts per distro, release combination that\[cq]s built. .TP -\f[B]\f[CB]WorkspaceDirectory=\f[B]\f[R], \f[B]\f[CB]--workspace-dir=\f[B]\f[R] +\f[V]WorkspaceDirectory=\f[R], \f[V]--workspace-dir=\f[R] Path to a directory where to store data required temporarily while building the image. This directory should have enough space to store the full OS image, though in most modes the actually used disk space is smaller. -If not specified, and \f[C]mkosi.workspace/\f[R] exists in the local +If not specified, and \f[V]mkosi.workspace/\f[R] exists in the local directory, it is used for this purpose. -Otherwise, a subdirectory in the output directory is used. +Otherwise, hidden subdirectories of the current working directory are +used. The data in this directory is removed automatically after each build. It\[cq]s safe to manually remove the contents of this directory should -an \f[C]mkosi\f[R] invocation be aborted abnormally (for example, due to +an \f[V]mkosi\f[R] invocation be aborted abnormally (for example, due to reboot/power failure). .TP -\f[B]\f[CB]Force=\f[B]\f[R], \f[B]\f[CB]--force\f[B]\f[R], \f[B]\f[CB]-f\f[B]\f[R] +\f[V]Force=\f[R], \f[V]--force\f[R], \f[V]-f\f[R] Replace the output file if it already exists, when building an image. By default when building an image and an output artifact already exists -\f[C]mkosi\f[R] will refuse operation. +\f[V]mkosi\f[R] will refuse operation. Specify this option once to delete all build artifacts from a previous run before re-building the image. If incremental builds are enabled, specifying this option twice will @@ -409,370 +406,366 @@ re-build is initiated. If a package cache is used (also see the \[lq]Files\[rq] section below), specifying this option thrice will ensure the package cache is removed too, before the re-build is initiated. -For the \f[C]clean\f[R] operation this option has a slightly different +For the \f[V]clean\f[R] operation this option has a slightly different effect: by default the verb will only remove build artifacts from a previous run, when specified once the incremental cache files are deleted too, and when specified twice the package cache is also removed. .PP .TP -\f[B]\f[CB]Bootable=\f[B]\f[R], \f[B]\f[CB]--bootable\f[B]\f[R], \f[B]\f[CB]-b\f[B]\f[R] -Generate a bootable image for UEFI systems. -.TP -\f[B]\f[CB]KernelCommandLine=\f[B]\f[R], \f[B]\f[CB]--kernel-command-line=\f[B]\f[R] -Use the specified kernel command line when building bootable images. +\f[V]Bootable=\f[R], \f[V]--bootable=\f[R] +Takes a boolean or \f[V]auto\f[R]. +Enables or disable generating of a bootable image. +If enabled, mkosi will install systemd-boot, run kernel-install, +generate unified kernel images for installed kernels and add an ESP +partition when the disk image output is used. +If systemd-boot is not installed or no kernel images can be found, the +build will fail. +\f[V]auto\f[R] behaves as if the option was enabled, but the build +won\[cq]t fail if either no kernel images or systemd-boot can\[cq]t be +found. +If disabled, systemd-boot won\[cq]t be installed even if found inside +the image, kernel-install won\[cq]t be executed, no unified kernel +images will be generated and no ESP partition will be added to the image +if the disk output format is used. +.TP +\f[V]KernelCommandLine=\f[R], \f[V]--kernel-command-line=\f[R] +Use the specified kernel command line when building images. By default command line arguments get appended. To remove all arguments from the current list pass \[lq]!*\[rq]. To remove specific arguments add a space separated list of \[lq]!\[rq] prefixed arguments. For example adding \[lq]!* console=ttyS0 rw\[rq] to a -\f[C]mkosi.conf\f[R] file or the command line arguments passes +\f[V]mkosi.conf\f[R] file or the command line arguments passes \[lq]console=ttyS0 rw\[rq] to the kernel in any case. Just adding \[lq]console=ttyS0 rw\[rq] would append these two arguments to the kernel command line created by lower priority configuration files -or previous \f[C]KernelCommandLine=\f[R] command line arguments. +or previous \f[V]KernelCommandLine=\f[R] command line arguments. .TP -\f[B]\f[CB]SecureBoot=\f[B]\f[R], \f[B]\f[CB]--secure-boot\f[B]\f[R] +\f[V]SecureBoot=\f[R], \f[V]--secure-boot\f[R] Sign the resulting kernel/initrd image for UEFI SecureBoot. .TP -\f[B]\f[CB]SecureBootKey=\f[B]\f[R], \f[B]\f[CB]--secure-boot-key=\f[B]\f[R] +\f[V]SecureBootKey=\f[R], \f[V]--secure-boot-key=\f[R] Path to the PEM file containing the secret key for signing the UEFI -kernel image, if \f[C]SecureBoot=\f[R] is used. +kernel image, if \f[V]SecureBoot=\f[R] is used. .TP -\f[B]\f[CB]SecureBootCertificate=\f[B]\f[R], \f[B]\f[CB]--secure-boot-certificate=\f[B]\f[R] +\f[V]SecureBootCertificate=\f[R], \f[V]--secure-boot-certificate=\f[R] Path to the X.509 file containing the certificate for the signed UEFI -kernel image, if \f[C]SecureBoot=\f[R] is used. +kernel image, if \f[V]SecureBoot=\f[R] is used. .TP -\f[B]\f[CB]SecureBootCommonName=\f[B]\f[R], \f[B]\f[CB]--secure-boot-common-name=\f[B]\f[R] +\f[V]SecureBootCommonName=\f[R], \f[V]--secure-boot-common-name=\f[R] Common name to be used when generating SecureBoot keys via mkosi\[cq]s -\f[C]genkey\f[R] command. -Defaults to \f[C]mkosi of %u\f[R], where \f[C]%u\f[R] expands to the +\f[V]genkey\f[R] command. +Defaults to \f[V]mkosi of %u\f[R], where \f[V]%u\f[R] expands to the username of the user invoking mkosi. .TP -\f[B]\f[CB]SecureBootValidDays=\f[B]\f[R], \f[B]\f[CB]--secure-boot-valid-days=\f[B]\f[R] +\f[V]SecureBootValidDays=\f[R], \f[V]--secure-boot-valid-days=\f[R] Number of days that the keys should remain valid when generating -SecureBoot keys via mkosi\[cq]s \f[C]genkey\f[R] command. +SecureBoot keys via mkosi\[cq]s \f[V]genkey\f[R] command. Defaults to two years (730 days). .TP -\f[B]\f[CB]SignExpectedPCR=\f[B]\f[R], \f[B]\f[CB]--sign-expected-pcr\f[B]\f[R] +\f[V]SignExpectedPCR=\f[R], \f[V]--sign-expected-pcr\f[R] Measure the components of the unified kernel image (UKI) using -\f[C]systemd-measure\f[R] and embed the PCR signature into the unified +\f[V]systemd-measure\f[R] and embed the PCR signature into the unified kernel image. -This option takes a boolean value or the special value \f[C]auto\f[R], +This option takes a boolean value or the special value \f[V]auto\f[R], which is the default, which is equal to a true value if the -\f[C]cryptography\f[R] (https://cryptography.io/) module is importable -and the \f[C]systemd-measure\f[R] binary is in \f[C]PATH\f[R]. +\f[V]cryptography\f[R] (https://cryptography.io/) module is importable +and the \f[V]systemd-measure\f[R] binary is in \f[V]PATH\f[R]. .TP -\f[B]\f[CB]CompressOutput=\f[B]\f[R], \f[B]\f[CB]--compress-output=\f[B]\f[R] +\f[V]CompressOutput=\f[R], \f[V]--compress-output=\f[R] Configure compression for the resulting image or archive. The argument can be either a boolean or a compression algorithm -(\f[C]xz\f[R], \f[C]zstd\f[R]). -\f[C]xz\f[R] compression is used by default. +(\f[V]xz\f[R], \f[V]zstd\f[R]). +\f[V]xz\f[R] compression is used by default. Note that when applied to block device image types this means the image cannot be started directly but needs to be decompressed first. -This also means that the \f[C]shell\f[R], \f[C]boot\f[R], \f[C]qemu\f[R] +This also means that the \f[V]shell\f[R], \f[V]boot\f[R], \f[V]qemu\f[R] verbs are not available when this option is used. -Implied for \f[C]tar\f[R] and \f[C]cpio\f[R]. -.TP -\f[B]\f[CB]QCow2=\f[B]\f[R], \f[B]\f[CB]--qcow2\f[B]\f[R] -Encode the resulting image as QEMU QCOW2 image. -This only applies when generating disk images. -QCOW2 images can be read natively by \f[C]qemu\f[R], but not by the -Linux kernel. -This means the \f[C]shell\f[R] and \f[C]boot\f[R] verbs are not -available when this option is used, however \f[C]qemu\f[R] will work. -.TP -\f[B]\f[CB]Hostname=\f[B]\f[R], \f[B]\f[CB]--hostname=\f[B]\f[R] -Set the image\[cq]s hostname to the specified name. +Implied for \f[V]tar\f[R] and \f[V]cpio\f[R]. .TP -\f[B]\f[CB]ImageVersion=\f[B]\f[R], \f[B]\f[CB]--image-version=\f[B]\f[R] +\f[V]ImageVersion=\f[R], \f[V]--image-version=\f[R] Configure the image version. This accepts any string, but it is recommended to specify a series of dot separated components. -The version may also be configured in a file \f[C]mkosi.version\f[R] in -which case it may be conveniently managed via the \f[C]bump\f[R] verb or -the \f[C]--auto-bump\f[R] switch. +The version may also be configured in a file \f[V]mkosi.version\f[R] in +which case it may be conveniently managed via the \f[V]bump\f[R] verb or +the \f[V]--auto-bump\f[R] option. When specified the image version is included in the default output file -name, i.e.\ instead of \f[C]image.raw\f[R] the default will be -\f[C]image_0.1.raw\f[R] for version \f[C]0.1\f[R] of the image, and +name, i.e.\ instead of \f[V]image.raw\f[R] the default will be +\f[V]image_0.1.raw\f[R] for version \f[V]0.1\f[R] of the image, and similar. -The version is also passed via the \f[C]$IMAGE_VERSION\f[R] to any build +The version is also passed via the \f[V]$IMAGE_VERSION\f[R] to any build scripts invoked (which may be useful to patch it into -\f[C]/etc/os-release\f[R] or similar, in particular the -\f[C]IMAGE_VERSION=\f[R] field of it). +\f[V]/etc/os-release\f[R] or similar, in particular the +\f[V]IMAGE_VERSION=\f[R] field of it). .TP -\f[B]\f[CB]ImageId=\f[B]\f[R], \f[B]\f[CB]--image-id=\f[B]\f[R] +\f[V]AutoBump=\f[R], \f[V]--auto-bump=\f[R], \f[V]-B\f[R] +If specified, after each successful build the the version is bumped in a +fashion equivalent to the \f[V]bump\f[R] verb, in preparation for the +next build. +This is useful for simple, linear version management: each build in a +series will have a version number one higher then the previous one. +.TP +\f[V]ImageId=\f[R], \f[V]--image-id=\f[R] Configure the image identifier. This accepts a freeform string that shall be used to identify the image with. If set the default output file will be named after it (possibly suffixed with the version). -If this option is used the root, \f[C]/usr/\f[R] and Verity partitions +If this option is used the root, \f[V]/usr/\f[R] and Verity partitions in the image will have their labels set to this (possibly suffixed by the image version). -The identifier is also passed via the \f[C]$IMAGE_ID\f[R] to any build +The identifier is also passed via the \f[V]$IMAGE_ID\f[R] to any build scripts invoked (which may be useful to patch it into -\f[C]/etc/os-release\f[R] or similar, in particular the -\f[C]IMAGE_ID=\f[R] field of it). +\f[V]/etc/os-release\f[R] or similar, in particular the +\f[V]IMAGE_ID=\f[R] field of it). .TP -\f[B]\f[CB]CacheInitrd=\f[B]\f[R], \f[B]\f[CB]--cache-initrd\f[B]\f[R] +\f[V]CacheInitrd=\f[R], \f[V]--cache-initrd\f[R] If specified, and incremental mode is used, mkosi will build the initrd in the cache image and reuse it in the final image. Note that this means that any changes that are only applied to the final image and not the cached image won\[cq]t be included in the initrd. .TP -\f[B]\f[CB]SplitArtifacts=\f[B]\f[R], \f[B]\f[CB]--split-artifacts\f[B]\f[R] -If specified and building a disk image, pass \f[C]--split=yes\f[R] to +\f[V]SplitArtifacts=\f[R], \f[V]--split-artifacts\f[R] +If specified and building a disk image, pass \f[V]--split=yes\f[R] to systemd-repart to have it write out split partition files for each configured partition. Read the man (https://www.freedesktop.org/software/systemd/man/systemd-repart.html#--split=BOOL) page for more information. This is useful in A/B update scenarios where an existing disk image -shall be augmented with a new version of a root or \f[C]/usr\f[R] +shall be augmented with a new version of a root or \f[V]/usr\f[R] partition along with its Verity partition and unified kernel. .TP -\f[B]\f[CB]RepartDirectory=\f[B]\f[R], \f[B]\f[CB]--repart-directory\f[B]\f[R] +\f[V]RepartDirectory=\f[R], \f[V]--repart-dir=\f[R] Path to a directory containing systemd-repart partition definition files that are used when mkosi invokes systemd-repart when building a disk image. -If not specified and \f[C]mkosi.repart/\f[R] exists in the local +If not specified and \f[V]mkosi.repart/\f[R] exists in the local directory, it will be used instead. -Note that mkosi invokes repart with \f[C]--root=\f[R] set to the root of -the image root, so any \f[C]CopyFiles=\f[R] source paths in partition +Note that mkosi invokes repart with \f[V]--root=\f[R] set to the root of +the image root, so any \f[V]CopyFiles=\f[R] source paths in partition definition files will be relative to the image root directory. .TP -\f[B]\f[CB]TarStripSELinuxContext=\f[B]\f[R], \f[B]\f[CB]--tar-strip-selinux-context\f[B]\f[R] +\f[V]TarStripSELinuxContext=\f[R], \f[V]--tar-strip-selinux-context\f[R] If running on a SELinux-enabled system (Fedora Linux, CentOS, Rocky Linux, Alma Linux), files inside the container are tagged with SELinux -context extended attributes (\f[C]xattrs\f[R]), which may interfere with +context extended attributes (\f[V]xattrs\f[R]), which may interfere with host SELinux rules in building or further container import stages. This option strips SELinux context attributes from the resulting tar archive. +.TP +\f[V]Initrd=\f[R], \f[V]--initrd\f[R] +Use user-provided initrd(s). +Takes a comma separated list of paths to initrd files. +This option may be used multiple times in which case the initrd lists +are combined. .SS [Content] Section .TP -\f[B]\f[CB]BasePackages=\f[B]\f[R], \f[B]\f[CB]--base-packages\f[B]\f[R] -Takes a boolean or the special value \f[C]conditional\f[R]. -If true, automatically install packages to ensure basic functionality, -as appropriate for the given image type. -For example, \f[C]systemd\f[R] is always included, -\f[C]systemd-udev\f[R] and \f[C]dracut\f[R] if the image is bootable, -and so on. -If false, only packages specified with \f[C]Packages=\f[R] will be -installed. -If \f[C]conditional\f[R], the list of packages to install will be -extended with boolean dependencies (c.f. -https://rpm.org/user_doc/boolean_dependencies.html), to install specific -packages when \f[I]other\f[R] packages are in the list. -For example, \f[C]systemd-udev\f[R] may be automatically included if the -image is bootable and \f[C]systemd\f[R] is installed. -With this, various \[lq]base\[rq] packages still need to be specified if -they should be included, but the corresponding \[lq]extension\[rq] -packages will be added automatically when appropriate. -This feature depends on support in the package manager, so it is not -implemented for all distributions. -.TP -\f[B]\f[CB]Packages=\f[B]\f[R], \f[B]\f[CB]--package=\f[B]\f[R], \f[B]\f[CB]-p\f[B]\f[R] -Install the specified distribution packages (i.e.\ RPM, DEB, \&...) in -the image. +\f[V]Packages=\f[R], \f[V]--package=\f[R], \f[V]-p\f[R] +Install the specified distribution packages (i.e.\ RPM, DEB, \&...) +in the image. Takes a comma separated list of package specifications. This option may be used multiple times in which case the specified package lists are combined. Packages specified this way will be installed both in the development and the final image. -Use \f[C]BuildPackages=\f[R] to specify packages that shall only be used +Use \f[V]BuildPackages=\f[R] to specify packages that shall only be used for the image generated in the build image, but that shall not appear in the final image. The types and syntax of \[lq]package specifications\[rq] that are -allowed depend on the package installer (e.g.\ \f[C]dnf\f[R] or -\f[C]yum\f[R] for \f[C]rpm\f[R]-based distros or \f[C]apt\f[R] for -\f[C]deb\f[R]-based distros), but may include package names, package +allowed depend on the package installer (e.g.\ \f[V]dnf\f[R] or +\f[V]yum\f[R] for \f[V]rpm\f[R]-based distros or \f[V]apt\f[R] for +\f[V]deb\f[R]-based distros), but may include package names, package names with version and/or architecture, package name globs, paths to packages in the file system, package groups, and virtual provides, including file paths. -To remove a package e.g.\ added by a \f[C]mkosi.conf\f[R] configuration -file prepend the package name with \f[C]!\f[R]. +To remove a package e.g.\ added by a \f[V]mkosi.conf\f[R] configuration +file prepend the package name with \f[V]!\f[R]. For example -p \[lq]!apache2\[rq] would remove the apache2 package. To replace the apache2 package by the httpd package just add -p \[lq]!apache2,httpd\[rq] to the command line arguments. To remove all packages use \[lq]!*\[rq]. -Example: when using an distro that uses \f[C]dnf\f[R], -\f[C]Packages=meson libfdisk-devel.i686 git-* prebuilt/rpms/systemd-249-rc1.local.rpm /usr/bin/ld \[at]development-tools python3dist(mypy)\f[R] -would install the \f[C]meson\f[R] package (in the latest version), the -32-bit version of the \f[C]libfdisk-devel\f[R] package, all available -packages that start with the \f[C]git-\f[R] prefix, a \f[C]systemd\f[R] +Example: when using an distro that uses \f[V]dnf\f[R], +\f[V]Packages=meson libfdisk-devel.i686 git-* prebuilt/rpms/systemd-249-rc1.local.rpm /usr/bin/ld \[at]development-tools python3dist(mypy)\f[R] +would install the \f[V]meson\f[R] package (in the latest version), the +32-bit version of the \f[V]libfdisk-devel\f[R] package, all available +packages that start with the \f[V]git-\f[R] prefix, a \f[V]systemd\f[R] rpm from the local file system, one of the packages that provides -\f[C]/usr/bin/ld\f[R], the packages in the \[lq]Development Tools\[rq] -group, and the package that contains the \f[C]mypy\f[R] python module. +\f[V]/usr/bin/ld\f[R], the packages in the \[lq]Development Tools\[rq] +group, and the package that contains the \f[V]mypy\f[R] python module. .TP -\f[B]\f[CB]WithDocs=\f[B]\f[R], \f[B]\f[CB]--with-docs\f[B]\f[R] +\f[V]WithDocs=\f[R], \f[V]--with-docs\f[R] Include documentation in the image built. By default if the underlying distribution package manager supports it documentation is not included in the image built. -The \f[C]$WITH_DOCS\f[R] environment variable passed to the -\f[C]mkosi.build\f[R] script indicates whether this option was used or +The \f[V]$WITH_DOCS\f[R] environment variable passed to the +\f[V]mkosi.build\f[R] script indicates whether this option was used or not. .TP -\f[B]\f[CB]WithTests=\f[B]\f[R], \f[B]\f[CB]--without-tests\f[B]\f[R], \f[B]\f[CB]-T\f[B]\f[R] +\f[V]WithTests=\f[R], \f[V]--without-tests\f[R], \f[V]-T\f[R] If set to false (or when the command-line option is used), the -\f[C]$WITH_TESTS\f[R] environment variable is set to \f[C]0\f[R] when -the \f[C]mkosi.build\f[R] script is invoked. +\f[V]$WITH_TESTS\f[R] environment variable is set to \f[V]0\f[R] when +the \f[V]mkosi.build\f[R] script is invoked. This is supposed to be used by the build script to bypass any unit or integration tests that are normally run during the source build process. -Note that this option has no effect unless the \f[C]mkosi.build\f[R] +Note that this option has no effect unless the \f[V]mkosi.build\f[R] build script honors it. .TP -\f[B]\f[CB]Cache=\f[B]\f[R], \f[B]\f[CB]--cache=\f[B]\f[R] +\f[V]CacheDirectory=\f[R], \f[V]--cache-dir=\f[R] Takes a path to a directory to use as package cache for the distribution package manager used. -If this option is not used, but a \f[C]mkosi.cache/\f[R] directory is +If this option is not used, but a \f[V]mkosi.cache/\f[R] directory is found in the local directory it is automatically used for this purpose. The directory configured this way is mounted into both the development and the final image while the package manager is running. .TP -\f[B]\f[CB]SkeletonTree=\f[B]\f[R], \f[B]\f[CB]--skeleton-tree=\f[B]\f[R] -Takes a path to a directory to copy into the OS tree before invoking the -package manager. +\f[V]SkeletonTree=\f[R], \f[V]--skeleton-tree=\f[R] +Takes a colon separated pair of paths. +The first path refers to a directory to copy into the OS tree before +invoking the package manager. +The second path refers to the target directory inside the image. +If the second path is not provided, the directory is copied on top of +the root directory of the image. Use this to insert files and directories into the OS tree before the package manager installs any packages. -If this option is not used, but the \f[C]mkosi.skeleton/\f[R] directory +If this option is not used, but the \f[V]mkosi.skeleton/\f[R] directory is found in the local directory it is automatically used for this -purpose (also see the \[lq]Files\[rq] section below). +purpose with the root directory as target (also see the \[lq]Files\[rq] +section below). Instead of a directory, a tar file may be provided. In this case it is unpacked into the OS tree before the package manager is invoked. This mode of operation allows setting permissions and file ownership explicitly, in particular for projects stored in a version control -system such as \f[C]git\f[R] which retain full file ownership and access +system such as \f[V]git\f[R] which retain full file ownership and access mode metadata for committed files. -If the tar file \f[C]mkosi.skeleton.tar\f[R] is found in the local +If the tar file \f[V]mkosi.skeleton.tar\f[R] is found in the local directory it will be automatically used for this purpose. .TP -\f[B]\f[CB]ExtraTree=\f[B]\f[R], \f[B]\f[CB]--extra-tree=\f[B]\f[R] -Takes a path to a directory to copy on top of the OS tree the package -manager generated. +\f[V]ExtraTree=\f[R], \f[V]--extra-tree=\f[R] +Takes a colon separated pair of paths. +The first path refers to a directory to copy from the host into the +image. +The second path refers to the target directory inside the image. +If the second path is not provided, the directory is copied on top of +the root directory of the image. Use this to override any default configuration files shipped with the distribution. -If this option is not used, but the \f[C]mkosi.extra/\f[R] directory is +If this option is not used, but the \f[V]mkosi.extra/\f[R] directory is found in the local directory it is automatically used for this purpose +with the root directory as target. (also see the \[lq]Files\[rq] section below). As with the skeleton tree logic above, instead of a directory, a tar file may be provided too. -\f[C]mkosi.skeleton.tar\f[R] will be automatically used if found in the +\f[V]mkosi.skeleton.tar\f[R] will be automatically used if found in the local directory. .TP -\f[B]\f[CB]CleanPackageMetadata=\f[B]\f[R], \f[B]\f[CB]--clean-package-metadata=\f[B]\f[R] +\f[V]CleanPackageMetadata=\f[R], \f[V]--clean-package-metadata=\f[R] Enable/disable removal of package manager databases, caches, and logs at the end of installation. -Can be specified as true, false, or \[lq]\f[C]auto\f[R]\[rq] (the +Can be specified as true, false, or \[lq]\f[V]auto\f[R]\[rq] (the default). -With \[lq]\f[C]auto\f[R]\[rq], files will be removed if the respective +With \[lq]\f[V]auto\f[R]\[rq], files will be removed if the respective package manager executable is \f[I]not\f[R] present at the end of the installation. .TP -\f[B]\f[CB]RemoveFiles=\f[B]\f[R], \f[B]\f[CB]--remove-files=\f[B]\f[R] +\f[V]RemoveFiles=\f[R], \f[V]--remove-files=\f[R] Takes a comma-separated list of globs. Files in the image matching the globs will be purged at the end. .TP -\f[B]\f[CB]RemovePackages=\f[B]\f[R], \f[B]\f[CB]--remove-package=\f[B]\f[R] +\f[V]RemovePackages=\f[R], \f[V]--remove-package=\f[R] Takes a comma-separated list of package specifications for removal, in -the same format as \f[C]Packages=\f[R]. +the same format as \f[V]Packages=\f[R]. The removal will be performed as one of the last steps. -This step is skipped if \f[C]CleanPackageMetadata=no\f[R] is used. +This step is skipped if \f[V]CleanPackageMetadata=no\f[R] is used. This option is currently only implemented for distributions using -\f[C]dnf\f[R]. +\f[V]dnf\f[R]. .TP -\f[B]\f[CB]Environment=\f[B]\f[R], \f[B]\f[CB]--environment=\f[B]\f[R] +\f[V]Environment=\f[R], \f[V]--environment=\f[R] Adds variables to the environment that the build/prepare/postinstall/finalize scripts are executed with. Takes a space-separated list of variable assignments or just variable names. In the latter case, the values of those variables will be passed through -from the environment in which \f[C]mkosi\f[R] was invoked. +from the environment in which \f[V]mkosi\f[R] was invoked. This option may be specified more than once, in which case all listed variables will be set. If the same variable is set twice, the later setting overrides the earlier one. .TP -\f[B]\f[CB]BuildSources=\f[B]\f[R], \f[B]\f[CB]--build-sources=\f[B]\f[R] +\f[V]BuildSources=\f[R], \f[V]--build-sources=\f[R] Takes a path to a source tree to mount into the development image, if the build script is used. .TP -\f[B]\f[CB]BuildDirectory=\f[B]\f[R], \f[B]\f[CB]--build-dir=\f[B]\f[R] +\f[V]BuildDirectory=\f[R], \f[V]--build-dir=\f[R] Takes a path of a directory to use as build directory for build systems that support out-of-tree builds (such as Meson). The directory used this way is shared between repeated builds, and allows the build system to reuse artifacts (such as object files, -executable, \&...) generated on previous invocations. +executable, \&...) +generated on previous invocations. This directory is mounted into the development image when the build script is invoked. The build script can find the path to this directory in the -\f[C]$BUILDDIR\f[R] environment variable. +\f[V]$BUILDDIR\f[R] environment variable. If this option is not specified, but a directory -\f[C]mkosi.builddir/\f[R] exists in the local directory it is +\f[V]mkosi.builddir/\f[R] exists in the local directory it is automatically used for this purpose (also see the \[lq]Files\[rq] section below). .TP -\f[B]\f[CB]InstallDirectory=\f[B]\f[R], \f[B]\f[CB]--install-directory=\f[B]\f[R] +\f[V]InstallDirectory=\f[R], \f[V]--install-dir=\f[R] Takes a path of a directory to use as the install directory. The directory used this way is shared between builds and allows the build system to not have to reinstall files that were already installed by a previous build and didn\[cq]t change. The build script can find the path to this directory in the -\f[C]$DESTDIR\f[R] environment variable. +\f[V]$DESTDIR\f[R] environment variable. If this option is not specified, but a directory -\f[C]mkosi.installdir\f[R] exists in the local directory, it is +\f[V]mkosi.installdir\f[R] exists in the local directory, it is automatically used for this purpose (also see the \[lq]Files\[rq] section below). .TP -\f[B]\f[CB]BuildPackages=\f[B]\f[R], \f[B]\f[CB]--build-package=\f[B]\f[R] -Similar to \f[C]Packages=\f[R], but configures packages to install only +\f[V]BuildPackages=\f[R], \f[V]--build-package=\f[R] +Similar to \f[V]Packages=\f[R], but configures packages to install only in the first phase of the build, into the development image. This option should be used to list packages containing header files, compilers, build systems, linkers and other build tools the -\f[C]mkosi.build\f[R] script requires to operate. +\f[V]mkosi.build\f[R] script requires to operate. Note that packages listed here are only included in the image created during the first phase of the build, and are absent in the final image. -Use \f[C]Packages=\f[R] to list packages that shall be included in both. +Use \f[V]Packages=\f[R] to list packages that shall be included in both. Packages are appended to the list. Packages prefixed with \[lq]!\[rq] are removed from the list. \[lq]!*\[rq] removes all packages from the list. .TP -\f[B]\f[CB]Password=\f[B]\f[R], \f[B]\f[CB]--password=\f[B]\f[R] -Set the password of the \f[C]root\f[R] user. -By default the \f[C]root\f[R] account is locked. -If this option is not used, but a file \f[C]mkosi.rootpw\f[R] exists in +\f[V]Password=\f[R], \f[V]--password=\f[R] +Set the password of the \f[V]root\f[R] user. +By default the \f[V]root\f[R] account is locked. +If this option is not used, but a file \f[V]mkosi.rootpw\f[R] exists in the local directory, the root password is automatically read from it. .TP -\f[B]\f[CB]PasswordIsHashed=\f[B]\f[R], \f[B]\f[CB]--password-is-hashed\f[B]\f[R] -Indicate that the password supplied for the \f[C]root\f[R] user has +\f[V]PasswordIsHashed=\f[R], \f[V]--password-is-hashed\f[R] +Indicate that the password supplied for the \f[V]root\f[R] user has already been hashed, so that the string supplied with -\f[C]Password=\f[R] or \f[C]mkosi.rootpw\f[R] will be written to -\f[C]/etc/shadow\f[R] literally. -.TP -\f[B]\f[CB]Autologin=\f[B]\f[R], \f[B]\f[CB]--autologin\f[B]\f[R] -Enable autologin for the \f[C]root\f[R] user on \f[C]/dev/pts/0\f[R] -(nspawn), \f[C]/dev/tty1\f[R] (QEMU) and \f[C]/dev/ttyS0\f[R] (QEMU with -\f[C]QemuHeadless=yes\f[R]) by patching \f[C]/etc/pam.d/login\f[R]. +\f[V]Password=\f[R] or \f[V]mkosi.rootpw\f[R] will be written to +\f[V]/etc/shadow\f[R] literally. .TP -\f[B]\f[CB]SkipFinalPhase=\f[B]\f[R], \f[B]\f[CB]--skip-final-phase=\f[B]\f[R] -Causes the (second) final image build stage to be skipped. -This is useful in combination with a build script, for when you care -about the artifacts that were created locally in \f[C]$BUILDDIR\f[R], -but ultimately plan to discard the final image. +\f[V]Autologin=\f[R], \f[V]--autologin\f[R] +Enable autologin for the \f[V]root\f[R] user on \f[V]/dev/pts/0\f[R] +(nspawn), \f[V]/dev/tty1\f[R] and \f[V]/dev/hvc0\f[R]. .TP -\f[B]\f[CB]BuildScript=\f[B]\f[R], \f[B]\f[CB]--build-script=\f[B]\f[R] +\f[V]BuildScript=\f[R], \f[V]--build-script=\f[R] Takes a path to an executable that is used as build script for this image. -If this option is used the build process will be two-phased instead of -single-phased. The specified script is copied onto the development image and executed inside a namespaced chroot environment. -If this option is not used, but the \f[C]mkosi.build\f[R] file found in +If this option is not used, but the \f[V]mkosi.build\f[R] file found in the local directory it is automatically used for this purpose (also see the \[lq]Files\[rq] section below). Specify an empty value to disable automatic detection. .TP -\f[B]\f[CB]PrepareScript=\f[B]\f[R], \f[B]\f[CB]--prepare-script=\f[B]\f[R] +\f[V]PrepareScript=\f[R], \f[V]--prepare-script=\f[R] Takes a path to an executable that is invoked inside the image right after installing the software packages. It is the last step before the image is cached (if incremental mode is @@ -780,56 +773,57 @@ enabled). This script is invoked inside a namespaced chroot environment, and thus does not have access to host resources. If this option is not used, but an executable script -\f[C]mkosi.prepare\f[R] is found in the local directory, it is +\f[V]mkosi.prepare\f[R] is found in the local directory, it is automatically used for this purpose. Specify an empty value to disable automatic detection. .TP -\f[B]\f[CB]PostInstallationScript=\f[B]\f[R], \f[B]\f[CB]--postinst-script=\f[B]\f[R] +\f[V]PostInstallationScript=\f[R], \f[V]--postinst-script=\f[R] Takes a path to an executable that is invoked inside the final image right after copying in the build artifacts generated in the first phase of the build. This script is invoked inside a namespaced chroot environment, and thus does not have access to host resources. -If this option is not used, but an executable \f[C]mkosi.postinst\f[R] +If this option is not used, but an executable \f[V]mkosi.postinst\f[R] is found in the local directory, it is automatically used for this purpose. Specify an empty value to disable automatic detection. .TP -\f[B]\f[CB]FinalizeScript=\f[B]\f[R], \f[B]\f[CB]--finalize-script=\f[B]\f[R] +\f[V]FinalizeScript=\f[R], \f[V]--finalize-script=\f[R] Takes a path to an executable that is invoked outside the final image right after copying in the build artifacts generated in the first phase -of the build, and after having executed the \f[C]mkosi.postinst\f[R] -script (see \f[C]PostInstallationScript=\f[R]). +of the build, and after having executed the \f[V]mkosi.postinst\f[R] +script (see \f[V]PostInstallationScript=\f[R]). This script is invoked directly in the host environment, and hence has full access to the host\[cq]s resources. -If this option is not used, but an executable \f[C]mkosi.finalize\f[R] +If this option is not used, but an executable \f[V]mkosi.finalize\f[R] is found in the local directory, it is automatically used for this purpose. Specify an empty value to disable automatic detection. .TP -\f[B]\f[CB]WithNetwork=\f[B]\f[R], \f[B]\f[CB]--with-network\f[B]\f[R] +\f[V]WithNetwork=\f[R], \f[V]--with-network=\f[R] When true, enables network connectivity while the build script -\f[C]mkosi.build\f[R] is invoked. +\f[V]mkosi.build\f[R] is invoked. By default, the build script runs with networking turned off. -The \f[C]$WITH_NETWORK\f[R] environment variable is passed to the -\f[C]mkosi.build\f[R] build script indicating whether the build is done +The \f[V]$WITH_NETWORK\f[R] environment variable is passed to the +\f[V]mkosi.build\f[R] build script indicating whether the build is done with or without network. -If specified as \f[C]never\f[R], the package manager is instructed not -to contact the network for updating package data. +.TP +\f[V]CacheOnly=\f[R], \f[V]--cache-only=\f[R] +If specified, the package manager is instructed not to contact the +network for updating package data. This provides a minimal level of reproducibility, as long as the package data cache is already fully populated. .TP -\f[B]\f[CB]Settings=\f[B]\f[R], \f[B]\f[CB]--settings=\f[B]\f[R] -Specifies a \f[C].nspawn\f[R] settings file for \f[C]systemd-nspawn\f[R] -to use in the \f[C]boot\f[R] and \f[C]shell\f[R] verbs, and to place +\f[V]Settings=\f[R], \f[V]--settings=\f[R] +Specifies a \f[V].nspawn\f[R] settings file for \f[V]systemd-nspawn\f[R] +to use in the \f[V]boot\f[R] and \f[V]shell\f[R] verbs, and to place next to the generated image file. -This is useful to configure the \f[C]systemd-nspawn\f[R] environment +This is useful to configure the \f[V]systemd-nspawn\f[R] environment when the image is run. -If this setting is not used but an \f[C]mkosi.nspawn\f[R] file found in +If this setting is not used but an \f[V]mkosi.nspawn\f[R] file found in the local directory it is automatically used for this purpose. -.SS [Partitions] Section .TP -\f[B]\f[CB]BaseImage=\f[B]\f[R], \f[B]\f[CB]--base-image=\f[B]\f[R] +\f[V]BaseImage=\f[R], \f[V]--base-image=\f[R] Use the specified directory or file system image as the base image, and create the output image that consists only of changes from this base. The base image is attached as the lower file system in an overlayfs @@ -843,71 +837,50 @@ See https://systemd.io/PORTABLE_SERVICES/#extension-images for more information. .SS [Validation] Section .TP -\f[B]\f[CB]Checksum=\f[B]\f[R], \f[B]\f[CB]--checksum\f[B]\f[R] -Generate a \f[C]SHA256SUMS\f[R] file of all generated artifacts after +\f[V]Checksum=\f[R], \f[V]--checksum\f[R] +Generate a \f[V]SHA256SUMS\f[R] file of all generated artifacts after the build is complete. .TP -\f[B]\f[CB]Sign=\f[B]\f[R], \f[B]\f[CB]--sign\f[B]\f[R] -Sign the generated \f[C]SHA256SUMS\f[R] using \f[C]gpg\f[R] after +\f[V]Sign=\f[R], \f[V]--sign\f[R] +Sign the generated \f[V]SHA256SUMS\f[R] using \f[V]gpg\f[R] after completion. .TP -\f[B]\f[CB]Key=\f[B]\f[R], \f[B]\f[CB]--key=\f[B]\f[R] -Select the \f[C]gpg\f[R] key to use for signing \f[C]SHA256SUMS\f[R]. -This key must be already present in the \f[C]gpg\f[R] keyring. -.TP -\f[B]\f[CB]BMap=\f[B]\f[R], \f[B]\f[CB]--bmap\f[B]\f[R] -Generate a \f[C]bmap\f[R] file for usage with \f[C]bmaptool\f[R] from -the generated image file. +\f[V]Key=\f[R], \f[V]--key=\f[R] +Select the \f[V]gpg\f[R] key to use for signing \f[V]SHA256SUMS\f[R]. +This key must be already present in the \f[V]gpg\f[R] keyring. .SS [Host] Section .TP -\f[B]\f[CB]ExtraSearchPaths=\f[B]\f[R], \f[B]\f[CB]--extra-search-paths=\f[B]\f[R] +\f[V]ExtraSearchPaths=\f[R], \f[V]--extra-search-path=\f[R] List of colon-separated paths to look for tools in, before using the -regular \f[C]$PATH\f[R] search path. -.TP -\f[B]\f[CB]QemuHeadless=\f[B]\f[R], \f[B]\f[CB]--qemu-headless=\f[B]\f[R] -When used with the \f[C]build\f[R] verb, this option adds -\f[C]console=ttyS0\f[R] to the image\[cq]s kernel command line and sets -the terminal type of the serial console in the image to the terminal -type of the host (more specifically, the value of the \f[C]$TERM\f[R] -environment variable passed to mkosi). -This makes sure that all terminal features such as colors and shortcuts -still work as expected when connecting to the qemu VM over the serial -console (for example via \f[C]-nographic\f[R]). -When used with the \f[C]qemu\f[R] verb, this option adds the -\f[C]-nographic\f[R] option to \f[C]qemu\f[R]\[cq]s command line so qemu -starts a headless vm and connects to its serial console from the current -terminal instead of launching the VM in a separate window. -.TP -\f[B]\f[CB]QemuSmp=\f[B]\f[R], \f[B]\f[CB]--qemu-smp=\f[B]\f[R] -When used with the \f[C]qemu\f[R] verb, this options sets -\f[C]qemu\f[R]\[cq]s \f[C]-smp\f[R] argument which controls the number +regular \f[V]$PATH\f[R] search path. +.TP +\f[V]QemuGui=\f[R], \f[V]--qemu-gui=\f[R] +If enabled, qemu is executed with its graphical interface instead of +with a serial console. +.TP +\f[V]QemuSmp=\f[R], \f[V]--qemu-smp=\f[R] +When used with the \f[V]qemu\f[R] verb, this options sets +\f[V]qemu\f[R]\[cq]s \f[V]-smp\f[R] argument which controls the number of guest\[cq]s CPUs. -Defaults to \f[C]2\f[R]. +Defaults to \f[V]2\f[R]. .TP -\f[B]\f[CB]QemuMem=\f[B]\f[R], \f[B]\f[CB]--qemu-mem=\f[B]\f[R] -When used with the \f[C]qemu\f[R] verb, this options sets -\f[C]qemu\f[R]\[cq]s \f[C]-m\f[R] argument which controls the amount of +\f[V]QemuMem=\f[R], \f[V]--qemu-mem=\f[R] +When used with the \f[V]qemu\f[R] verb, this options sets +\f[V]qemu\f[R]\[cq]s \f[V]-m\f[R] argument which controls the amount of guest\[cq]s RAM. -Defaults to \f[C]1G\f[R]. +Defaults to \f[V]1G\f[R]. .TP -\f[B]\f[CB]QemuKvm=\f[B]\f[R], \f[B]\f[CB]--qemu-kvm=\f[B]\f[R] -When used with the \f[C]qemu\f[R] verb, this option specifies whether +\f[V]QemuKvm=\f[R], \f[V]--qemu-kvm=\f[R] +When used with the \f[V]qemu\f[R] verb, this option specifies whether QEMU should use KVM acceleration. Defaults to yes if the host machine supports KVM acceleration, no otherwise. .TP -\f[B]\f[CB]QemuArgs=\f[B]\f[R] +\f[V]QemuArgs=\f[R] Space-delimited list of additional arguments to pass when invoking qemu. .TP -\f[B]\f[CB]Netdev=\f[B]\f[R], \f[B]\f[CB]--netdev\f[B]\f[R] -When used with the boot or qemu verbs, this option creates a virtual -ethernet link between the host and the container/VM. -The host interface is automatically picked up by systemd-networkd as -documented in systemd-nspawn\[cq]s man page: -https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-n -.TP -\f[B]\f[CB]Ephemeral=\f[B]\f[R], \f[B]\f[CB]--ephemeral\f[B]\f[R] -When used with the \f[C]shell\f[R], \f[C]boot\f[R], or \f[C]qemu\f[R] +\f[V]Ephemeral=\f[R], \f[V]--ephemeral\f[R] +When used with the \f[V]shell\f[R], \f[V]boot\f[R], or \f[V]qemu\f[R] verbs, this option runs the specified verb on a temporary snapshot of the output image that is removed immediately when the container terminates. @@ -916,110 +889,93 @@ support subvolume snapshots or `reflinks' natively (\[lq]btrfs\[rq] or new \[lq]xfs\[rq]) than on more traditional file systems that do not (\[lq]ext4\[rq]). .TP -\f[B]\f[CB]Ssh=\f[B]\f[R], \f[B]\f[CB]--ssh\f[B]\f[R] -If specified, installs and enables \f[C]sshd\f[R] in the final image and -generates a SSH keypair and adds the public key to root\[cq]s -\f[C]authorized_keys\f[R] in the final image. -The private key is stored in mkosi\[cq]s output directory. +\f[V]Ssh=\f[R], \f[V]--ssh\f[R] +If specified, an sshd socket unit and matching service are installed in +the final image that expose sshd over VSock. When building with this option and running the image using -\f[C]mkosi boot\f[R] or \f[C]mkosi qemu\f[R], the \f[C]mkosi ssh\f[R] -command can be used to connect to the container/VM via SSH. -.TP -\f[B]\f[CB]SshKey=\f[B]\f[R], \f[B]\f[CB]--ssh-key=\f[B]\f[R] -If specified, use the given private key when connecting to the guest -machine via \f[C]mkosi ssh\f[R]. -This requires the public key counterpart to be present in the same -location, suffixed with \f[C].pub\f[R] (as done by -\f[C]ssh-keygen\f[R]). -If this option is not present, \f[C]mkosi\f[R] generates a new key pair -automatically. -.TP -\f[B]\f[CB]SshAgent=\f[B]\f[R], \f[B]\f[CB]--ssh-agent=\f[B]\f[R] -If specified as a path, use the given socket to connect to the ssh agent -when building an image and when connecting via \f[C]mkosi ssh\f[R] -instead of hard-coding a key. -If specified as \f[C]true\f[R], \f[C]$SSH_AUTH_SOCK\f[R] will be parsed -instead (hint: use \f[C]sudo\f[R] with \f[C]-E\f[R]). -The keys listed by \f[C]ssh-add -L\f[R] will be installed as authorized -keys in the built image. -The \f[C]ssh\f[R] invocation done by \f[C]mkosi ssh\f[R] will inherit -\f[C]$SSH_AUTH_SOCK\f[R] for authentication purposes. -.TP -\f[B]\f[CB]SshPort=\f[B]\f[R], \f[B]\f[CB]--ssh-port=\f[B]\f[R] -In the image, sshd will be configured to listen on this port. -\f[C]mkosi ssh\f[R] will connect to this port. -.TP -\f[B]\f[CB]SshTimeout=\f[B]\f[R], \f[B]\f[CB]--ssh-timeout=\f[B]\f[R] -When used with the \f[C]ssh\f[R] verb, \f[C]mkosi\f[R] will attempt to -retry the SSH connection up to given timeout (in seconds) in case it -fails. -This option is useful mainly in scripted environments where the -\f[C]qemu\f[R] and \f[C]ssh\f[R] verbs are used in a quick succession -and the virtual device might not get enough time to configure itself. -.TP -\f[B]\f[CB]Credentials=\f[B]\f[R], \f[B]\f[CB]--credential\f[B]\f[R] +\f[V]mkosi qemu\f[R], the \f[V]mkosi ssh\f[R] command can be used to +connect to the container/VM via SSH. +Note that you still have to make sure openssh is installed in the image +to make this option behave correctly. +Also note that mkosi doesn\[cq]t provision a public SSH key into the +image automatically. +One way to do this is by setting the \f[V]ssh.authorized_keys.root\f[R] +credential using the \f[V]Credential=\f[R] option or by copying it in +using \f[V]ExtraTrees=\f[R]. +To access images booted using \f[V]mkosi boot\f[R], use +\f[V]machinectl\f[R]. +.TP +\f[V]Credentials=\f[R], \f[V]--credential=\f[R] Set credentials to be passed to systemd-nspawn or qemu respectively when -\f[C]mkosi shell/boot\f[R] or \f[C]mkosi qemu\f[R] are used. +\f[V]mkosi shell/boot\f[R] or \f[V]mkosi qemu\f[R] are used. This option takes a space separated list of key=value assignments. +.TP +\f[V]KernelCommandLineExtra=\f[R], \f[V]--kernel-command-line-extra=\f[R] +Set extra kernel command line entries that are appended to the kernel +command line at runtime when booting the image. +When booting in a container, these are passed as extra arguments to +systemd. +When booting in a VM, these are appended to the kernel command line via +the SMBIOS io.systemd.stub.kernel-cmdline-extra OEM string. +This will only be picked up by systemd-boot/systemd-stub versions newer +than or equal to v254. +.TP +\f[V]Acl=\f[R], \f[V]--acl=\f[R] +If specified, ACLs will be set on any generated root filesystem +directories that allow the user running mkosi to remove them without +needing privileges. .SS Commandline-only Options .PP Those settings cannot be configured in the configuration files. .TP -\f[B]\f[CB]--directory=\f[B]\f[R], \f[B]\f[CB]-C\f[B]\f[R] +\f[V]--directory=\f[R], \f[V]-C\f[R] Takes a path to a directory. -\f[C]mkosi\f[R] switches to this directory before doing anything. -Note that the various \f[C]mkosi.*\f[R] files are searched for only +\f[V]mkosi\f[R] switches to this directory before doing anything. +Note that the various \f[V]mkosi.*\f[R] files are searched for only after changing to this directory, hence using this option is an effective way to build a project located in a specific directory. .TP -\f[B]\f[CB]--config=\f[B]\f[R] +\f[V]--config=\f[R] Loads additional settings from the specified settings file. Most command line options may also be configured in a settings file. See the table below to see which command line options match which settings file option. -If this option is not used, but a file \f[C]mkosi.conf\f[R] is found in +If this option is not used, but a file \f[V]mkosi.conf\f[R] is found in the local directory it is automatically used for this purpose. If a setting is configured both on the command line and in the settings file, the command line generally wins, except for options taking lists in which case both lists are combined. .TP -\f[B]\f[CB]--incremental\f[B]\f[R], \f[B]\f[CB]-i\f[B]\f[R] +\f[V]--incremental\f[R], \f[V]-i\f[R] Enable incremental build mode. -This only applies if the two-phase \f[C]mkosi.build\f[R] build script +This only applies if the two-phase \f[V]mkosi.build\f[R] build script logic is used. In this mode, a copy of the OS image is created immediately after all OS -packages are unpacked but before the \f[C]mkosi.build\f[R] script is +packages are unpacked but before the \f[V]mkosi.build\f[R] script is invoked in the development container. Similarly, a copy of the final image is created immediately before the -build artifacts from the \f[C]mkosi.build\f[R] script are copied in. -On subsequent invocations of \f[C]mkosi\f[R] with the \f[C]-i\f[R] +build artifacts from the \f[V]mkosi.build\f[R] script are copied in. +On subsequent invocations of \f[V]mkosi\f[R] with the \f[V]-i\f[R] switch these cached images may be used to skip the OS package unpacking, thus drastically speeding up repetitive build times. Note that when this is used and a pair of cached incremental images exists they are not automatically regenerated, even if options such as -\f[C]Packages=\f[R] are modified. +\f[V]Packages=\f[R] are modified. In order to force rebuilding of these cached images, combine -\f[C]-i\f[R] with \f[C]-ff\f[R] to ensure cached images are first +\f[V]-i\f[R] with \f[V]-ff\f[R] to ensure cached images are first removed and then re-created. .TP -\f[B]\f[CB]--debug=\f[B]\f[R] +\f[V]--debug=\f[R] Enable additional debugging output. Takes a comma-separated list of arguments specifying the area of interest. Pass any invalid value (e.g.\ empty) to list currently accepted values. .TP -\f[B]\f[CB]--version\f[B]\f[R] +\f[V]--version\f[R] Show package version. .TP -\f[B]\f[CB]--help\f[B]\f[R], \f[B]\f[CB]-h\f[B]\f[R] +\f[V]--help\f[R], \f[V]-h\f[R] Show brief usage information. -.TP -\f[B]\f[CB]--auto-bump\f[B]\f[R], \f[B]\f[CB]-B\f[B]\f[R] -If specified, after each successful build the the version is bumped in a -fashion equivalent to the \f[C]bump\f[R] verb, in preparation for the -next build. -This is useful for simple, linear version management: each build in a -series will have a version number one higher then the previous one. .SS Supported distributions .PP Images may be created containing installations of the following @@ -1050,59 +1006,21 @@ operating systems: In theory, any distribution may be used on the host for building images containing any other distribution, as long as the necessary tools are available. -Specifically, any distribution that packages \f[C]debootstrap\f[R] and -\f[C]apt\f[R] may be used to build \f[I]Debian\f[R] or \f[I]Ubuntu\f[R] -images. -Any distribution that packages \f[C]dnf\f[R] may be used to build +Specifically, any distribution that packages \f[V]apt\f[R] may be used +to build \f[I]Debian\f[R] or \f[I]Ubuntu\f[R] images. +Any distribution that packages \f[V]dnf\f[R] may be used to build \f[I]CentOS\f[R], \f[I]Alma Linux\f[R], \f[I]Rocky Linux\f[R], \f[I]Fedora Linux\f[R], \f[I]Mageia\f[R] or \f[I]OpenMandriva\f[R] images. -Any distro that packages \f[C]pacman\f[R] may be used to build \f[I]Arch +Any distro that packages \f[V]pacman\f[R] may be used to build \f[I]Arch Linux\f[R] images. -Any distribution that packages \f[C]zypper\f[R] may be used to build +Any distribution that packages \f[V]zypper\f[R] may be used to build \f[I]openSUSE\f[R] images. -Any distribution that packages \f[C]emerge\f[R] may be used to build +Any distribution that packages \f[V]emerge\f[R] may be used to build \f[I]Gentoo\f[R] images. .PP Currently, \f[I]Fedora Linux\f[R] packages all relevant tools as of Fedora 28. -.SS Compatibility -.PP -Legacy concepts are avoided: generated images use \f[I]GPT\f[R] disk -labels (and no \f[I]MBR\f[R] labels), and only systemd-based images may -be generated. -.PP -All generated \f[I]GPT\f[R] disk images may be booted in a local -container directly with: -.IP -.nf -\f[C] -systemd-nspawn -bi image.raw -\f[R] -.fi -.PP -Additionally, bootable \f[I]GPT\f[R] disk images (as created with the -\f[C]--bootable\f[R] flag) work when booted directly by \f[I]EFI\f[R] -systems, for example in \f[I]KVM\f[R] via: -.IP -.nf -\f[C] -qemu-kvm -m 512 -smp 2 -bios /usr/share/edk2/ovmf/OVMF_CODE.fd -drive format=raw,file=image.raw -\f[R] -.fi -.PP -\f[I]EFI\f[R] bootable \f[I]GPT\f[R] images are larger than plain -\f[I]GPT\f[R] images, as they additionally carry an \f[I]EFI\f[R] system -partition containing a boot loader, as well as a kernel, kernel modules, -udev and more. -.PP -All directory or btrfs subvolume images may be booted directly with: -.IP -.nf -\f[C] -systemd-nspawn -bD image -\f[R] -.fi .SH Files .PP To make it easy to build images for development versions of your @@ -1111,39 +1029,39 @@ under the assumption that it is invoked from a \f[I]source\f[R] tree. Specifically, the following files are used if they exist in the local directory: .IP \[bu] 2 -The \f[B]\f[CB]mkosi.conf\f[B]\f[R] file provides the default +The \f[B]\f[VB]mkosi.conf\f[B]\f[R] file provides the default configuration for the image building process. -For example, it may specify the distribution to use (\f[C]fedora\f[R], -\f[C]ubuntu\f[R], \f[C]debian\f[R], \f[C]arch\f[R], \f[C]opensuse\f[R], -\f[C]mageia\f[R], \f[C]openmandriva\f[R], \f[C]gentoo\f[R]) for the +For example, it may specify the distribution to use (\f[V]fedora\f[R], +\f[V]ubuntu\f[R], \f[V]debian\f[R], \f[V]arch\f[R], \f[V]opensuse\f[R], +\f[V]mageia\f[R], \f[V]openmandriva\f[R], \f[V]gentoo\f[R]) for the image, or additional distribution packages to install. Note that all options encoded in this configuration file may also be set on the command line, and this file is hence little more than a way to -make sure invoking \f[C]mkosi\f[R] without further parameters in your +make sure invoking \f[V]mkosi\f[R] without further parameters in your \f[I]source\f[R] tree is enough to get the right image of your choice set up. .RS 2 .PP -Additionally, if a \f[I]\f[CI]mkosi.conf.d/\f[I]\f[R] directory exists, +Additionally, if a \f[I]\f[VI]mkosi.conf.d/\f[I]\f[R] directory exists, each file in it is loaded in the same manner adding/overriding the -values specified in \f[C]mkosi.conf\f[R]. -If \f[C]mkosi.conf.d/\f[R] contains a directory named after the +values specified in \f[V]mkosi.conf\f[R]. +If \f[V]mkosi.conf.d/\f[R] contains a directory named after the distribution being built, each file in that directory is also processed. .PP -The file format is inspired by Windows \f[C].ini\f[R] files and supports +The file format is inspired by Windows \f[V].ini\f[R] files and supports multi-line assignments: any line with initial whitespace is considered a continuation line of the line before. Command-line arguments, as shown in the help description, have to be -included in a configuration block (e.g.\ \[lq]\f[C][Content]\f[R]\[rq]) -corresponding to the argument group (e.g.\ \[lq]\f[C]Content\f[R]\[rq]), +included in a configuration block (e.g.\ \[lq]\f[V][Content]\f[R]\[rq]) +corresponding to the argument group (e.g.\ \[lq]\f[V]Content\f[R]\[rq]), and the argument gets converted as follows: -\[lq]\f[C]--with-network\f[R]\[rq] becomes -\[lq]\f[C]WithNetwork=yes\f[R]\[rq]. +\[lq]\f[V]--with-network\f[R]\[rq] becomes +\[lq]\f[V]WithNetwork=yes\f[R]\[rq]. For further details see the table above. .RE .IP \[bu] 2 -The \f[B]\f[CB]mkosi.skeleton/\f[B]\f[R] directory or -\f[B]\f[CB]mkosi.skeleton.tar\f[B]\f[R] archive may be used to insert +The \f[B]\f[VB]mkosi.skeleton/\f[B]\f[R] directory or +\f[B]\f[VB]mkosi.skeleton.tar\f[B]\f[R] archive may be used to insert files into the image. The files are copied \f[I]before\f[R] the distribution packages are installed into the image. @@ -1156,12 +1074,12 @@ copied will be owned by root. To preserve ownership, use a tar archive. .RE .IP \[bu] 2 -The \f[B]\f[CB]mkosi.extra/\f[B]\f[R] directory or -\f[B]\f[CB]mkosi.extra.tar\f[B]\f[R] archive may be used to insert +The \f[B]\f[VB]mkosi.extra/\f[B]\f[R] directory or +\f[B]\f[VB]mkosi.extra.tar\f[B]\f[R] archive may be used to insert additional files into the image, on top of what the distribution includes in its packages. -They are similar to \f[C]mkosi.skeleton/\f[R] and -\f[C]mkosi.skeleton.tar\f[R], but the files are copied into the +They are similar to \f[V]mkosi.skeleton/\f[R] and +\f[V]mkosi.skeleton.tar\f[R], but the files are copied into the directory tree of the image \f[I]after\f[R] the OS was installed. .RS 2 .PP @@ -1170,49 +1088,49 @@ copied will be owned by root. To preserve ownership, use a tar archive. .RE .IP \[bu] 2 -\f[B]\f[CB]mkosi.build\f[B]\f[R] may be an executable script. +\f[B]\f[VB]mkosi.build\f[B]\f[R] may be an executable script. If it exists, the image will be built twice: the first iteration will be the \f[I]development\f[R] image, the second iteration will be the \f[I]final\f[R] image. The \f[I]development\f[R] image is used to build the project in the current working directory (the \f[I]source\f[R] tree). For that the whole directory is copied into the image, along with the -\f[C]mkosi.build\f[R] script. -The script is then invoked inside the image, with \f[C]$SRCDIR\f[R] +\f[V]mkosi.build\f[R] script. +The script is then invoked inside the image, with \f[V]$SRCDIR\f[R] pointing to the \f[I]source\f[R] tree. -\f[C]$DESTDIR\f[R] points to a directory where the script should place +\f[V]$DESTDIR\f[R] points to a directory where the script should place any files generated it would like to end up in the \f[I]final\f[R] image. -Note that \f[C]make\f[R]/\f[C]automake\f[R]/\f[C]meson\f[R] based build -systems generally honor \f[C]$DESTDIR\f[R], thus making it very natural +Note that \f[V]make\f[R]/\f[V]automake\f[R]/\f[V]meson\f[R] based build +systems generally honor \f[V]$DESTDIR\f[R], thus making it very natural to build \f[I]source\f[R] trees from the build script. After the \f[I]development\f[R] image was built and the build script ran inside of it, it is removed again. After that the \f[I]final\f[R] image is built, without any \f[I]source\f[R] tree or build script copied in. -However, this time the contents of \f[C]$DESTDIR\f[R] are added into the +However, this time the contents of \f[V]$DESTDIR\f[R] are added into the image. .RS 2 .PP When the source tree is copied into the \f[I]build\f[R] image, all files -are copied, except for \f[C]mkosi.builddir/\f[R], \f[C]mkosi.cache/\f[R] -and \f[C]mkosi.output/\f[R]. -That said, \f[C].gitignore\f[R] is respected if the source tree is a -\f[C]git\f[R] checkout. +are copied, except for \f[V]mkosi.builddir/\f[R], \f[V]mkosi.cache/\f[R] +and \f[V]mkosi.output/\f[R]. +That said, \f[V].gitignore\f[R] is respected if the source tree is a +\f[V]git\f[R] checkout. If multiple different images shall be built from the same source tree it is essential to exclude their output files from this copy operation, as otherwise a version of an image built earlier might be included in a later build, which is usually not intended. -An alternative to excluding these built images via \f[C].gitignore\f[R] -entries is to use the \f[C]mkosi.output/\f[R] directory, which is an +An alternative to excluding these built images via \f[V].gitignore\f[R] +entries is to use the \f[V]mkosi.output/\f[R] directory, which is an easy way to exclude all build artifacts. .PP -The \f[C]$MKOSI_CONFIG\f[R] environment variable will be set inside of -this script so that you know which \f[C]mkosi.conf\f[R] (if any) was +The \f[V]$MKOSI_CONFIG\f[R] environment variable will be set inside of +this script so that you know which \f[V]mkosi.conf\f[R] (if any) was passed in. .RE .IP \[bu] 2 -The \f[B]\f[CB]mkosi.prepare\f[B]\f[R] script is invoked directly after +The \f[B]\f[VB]mkosi.prepare\f[B]\f[R] script is invoked directly after the software packages are installed, from within the image context, if it exists. It is once called for the \f[I]development\f[R] image (if this is @@ -1222,18 +1140,18 @@ It is called a second time for the \f[I]final\f[R] image with the \[lq]final\[rq] command line parameter. This script has network access and may be used to install packages from other sources than the distro\[cq]s package manager -(e.g.\ \f[C]pip\f[R], \f[C]npm\f[R], \&...), after all software packages +(e.g.\ \f[V]pip\f[R], \f[V]npm\f[R], \&...), after all software packages are installed but before the image is cached (if incremental mode is enabled). -This script is executed within \f[C]$SRCDIR\f[R]. +This script is executed within \f[V]$SRCDIR\f[R]. In contrast to a general purpose installation, it is safe to install -packages to the system (\f[C]pip install\f[R], -\f[C]npm install -g\f[R]) instead of in \f[C]$SRCDIR\f[R] itself +packages to the system (\f[V]pip install\f[R], +\f[V]npm install -g\f[R]) instead of in \f[V]$SRCDIR\f[R] itself because the build image is only used for a single project and can easily be thrown away and rebuilt so there\[cq]s no risk of conflicting dependencies and no risk of polluting the host system. .IP \[bu] 2 -The \f[B]\f[CB]mkosi.postinst\f[B]\f[R] script is invoked as the +The \f[B]\f[VB]mkosi.postinst\f[B]\f[R] script is invoked as the penultimate step of preparing an image, from within the image context, if it exists. It is called first for the \f[I]development\f[R] image (if this is @@ -1246,75 +1164,75 @@ This script may be used to alter the images without any restrictions, after all software packages and built sources have been installed. Note that this script is executed directly in the image context with the final root directory in place, without any -\f[C]$SRCDIR\f[R]/\f[C]$DESTDIR\f[R] setup. +\f[V]$SRCDIR\f[R]/\f[V]$DESTDIR\f[R] setup. .IP \[bu] 2 -The \f[B]\f[CB]mkosi.finalize\f[B]\f[R] script, if it exists, is invoked +The \f[B]\f[VB]mkosi.finalize\f[B]\f[R] script, if it exists, is invoked as last step of preparing an image, from the host system. It is once called for the \f[I]development\f[R] image (if this is enabled, see above) with the \[lq]build\[rq] command line parameter, as the last step before invoking the build script, after the -\f[C]mkosi.postinst\f[R] script is invoked. +\f[V]mkosi.postinst\f[R] script is invoked. It is called the second time with the \[lq]final\[rq] command line parameter as the last step before the image is considered complete. -The environment variable \f[C]$BUILDROOT\f[R] points to the root +The environment variable \f[V]$BUILDROOT\f[R] points to the root directory of the installation image. Additional verbs may be added in the future, the script should be prepared for that. This script may be used to alter the images without any restrictions, after all software packages and built sources have been installed. -This script is more flexible than \f[C]mkosi.postinst\f[R] in two +This script is more flexible than \f[V]mkosi.postinst\f[R] in two regards: it has access to the host file system so it\[cq]s easier to copy in additional files or to modify the image based on external configuration, and the script is run in the host, so it can be used even without emulation even if the image has a foreign architecture. .IP \[bu] 2 -The \f[B]\f[CB]mkosi.nspawn\f[B]\f[R] nspawn settings file will be +The \f[B]\f[VB]mkosi.nspawn\f[B]\f[R] nspawn settings file will be copied into the same place as the output image file, if it exists. This is useful since nspawn looks for settings files next to image files it boots, for additional container runtime settings. .IP \[bu] 2 -The \f[B]\f[CB]mkosi.cache/\f[B]\f[R] directory, if it exists, is +The \f[B]\f[VB]mkosi.cache/\f[B]\f[R] directory, if it exists, is automatically used as package download cache, in order to speed repeated runs of the tool. .IP \[bu] 2 -The \f[B]\f[CB]mkosi.builddir/\f[B]\f[R] directory, if it exists, is +The \f[B]\f[VB]mkosi.builddir/\f[B]\f[R] directory, if it exists, is automatically used as out-of-tree build directory, if the build commands -in the \f[C]mkosi.build\f[R] script support it. +in the \f[V]mkosi.build\f[R] script support it. Specifically, this directory will be mounted into the build container, -and the \f[C]$BUILDDIR\f[R] environment variable will be set to it when +and the \f[V]$BUILDDIR\f[R] environment variable will be set to it when the build script is invoked. The build script may then use this directory as build directory, for automake-style or ninja-style out-of-tree builds. -This speeds up builds considerably, in particular when \f[C]mkosi\f[R] -is used in incremental mode (\f[C]-i\f[R]): not only the disk images, +This speeds up builds considerably, in particular when \f[V]mkosi\f[R] +is used in incremental mode (\f[V]-i\f[R]): not only the disk images, but also the build tree is reused between subsequent invocations. -Note that if this directory does not exist the \f[C]$BUILDDIR\f[R] +Note that if this directory does not exist the \f[V]$BUILDDIR\f[R] environment variable is not set, and it is up to build script to decide whether to do in in-tree or an out-of-tree build, and which build directory to use. .IP \[bu] 2 -The \f[B]\f[CB]mkosi.includedir/\f[B]\f[R] directory, if it exists, is +The \f[B]\f[VB]mkosi.includedir/\f[B]\f[R] directory, if it exists, is automatically used as an out-of-tree include directory for header files. Specifically, it will be mounted in the build container at -\f[C]/usr/include/\f[R] when building the build image and when running +\f[V]/usr/include/\f[R] when building the build image and when running the build script. After building the (cached) build image, this directory will contain all -the files installed to \f[C]/usr/include\f[R]. +the files installed to \f[V]/usr/include\f[R]. Language servers or other tools can use these files to provide a better editing experience for developers working on a project. .IP \[bu] 2 -The \f[B]\f[CB]mkosi.installdir/\f[B]\f[R] directory, if it exists, is +The \f[B]\f[VB]mkosi.installdir/\f[B]\f[R] directory, if it exists, is automatically used as the install directory. Specifically, this directory will be mounted into the container at -\f[C]/root/dest\f[R] when running the build script. +\f[V]/root/dest\f[R] when running the build script. After running the build script, the contents of this directory are installed into the final image. This is useful to cache the install step of the build. If used, subsequent builds will only have to reinstall files that have changed since the previous build. .IP \[bu] 2 -The \f[B]\f[CB]mkosi.rootpw\f[B]\f[R] file can be used to provide the -password or hashed password (if \f[C]--password-is-hashed\f[R] is set) +The \f[B]\f[VB]mkosi.rootpw\f[B]\f[R] file can be used to provide the +password or hashed password (if \f[V]--password-is-hashed\f[R] is set) for the root user of the image. The password may optionally be followed by a newline character which is implicitly removed. @@ -1323,26 +1241,26 @@ If this file does not exist, the distribution\[cq]s default root password is set (which usually means access to the root user is blocked). .IP \[bu] 2 -The \f[B]\f[CB]mkosi.passphrase\f[B]\f[R] file provides the passphrase +The \f[B]\f[VB]mkosi.passphrase\f[B]\f[R] file provides the passphrase to use when LUKS encryption is selected. It should contain the passphrase literally, and not end in a newline character (i.e.\ in the same format as cryptsetup and -\f[C]/etc/crypttab\f[R] expect the passphrase files). +\f[V]/etc/crypttab\f[R] expect the passphrase files). The file must have an access mode of 0600 or less. If this file does not exist and encryption is requested, the user is queried instead. .IP \[bu] 2 -The \f[B]\f[CB]mkosi.secure-boot.crt\f[B]\f[R] and -\f[B]\f[CB]mkosi.secure-boot.key\f[B]\f[R] files contain an X.509 +The \f[B]\f[VB]mkosi.secure-boot.crt\f[B]\f[R] and +\f[B]\f[VB]mkosi.secure-boot.key\f[B]\f[R] files contain an X.509 certificate and PEM private key to use when UEFI SecureBoot support is enabled. All EFI binaries included in the image\[cq]s ESP are signed with this key, as a late step in the build process. .IP \[bu] 2 -The \f[B]\f[CB]mkosi.output/\f[B]\f[R] directory will be used for all +The \f[B]\f[VB]mkosi.output/\f[B]\f[R] directory will be used for all build artifacts, if the image output path is not configured (i.e.\ no -\f[C]--output=\f[R] setting specified), or configured to a filename -(i.e.\ a path containing no \f[C]/\f[R] character). +\f[V]--output=\f[R] setting specified), or configured to a filename +(i.e.\ a path containing no \f[V]/\f[R] character). This includes the image itself, the root hash file in case Verity is used, the checksum and its signature if that\[cq]s enabled, and the nspawn settings file if there is any. @@ -1353,87 +1271,64 @@ be built from the same working directory, as otherwise the build result of a preceding run might be copied into a build image as part of the source tree (see above). .IP \[bu] 2 -The \f[B]\f[CB]mkosi.reposdir/\f[B]\f[R] directory, if it exists, is +The \f[B]\f[VB]mkosi.reposdir/\f[B]\f[R] directory, if it exists, is automatically used as the repository directory for extra repository files. -See the \f[C]RepositoryDirectories\f[R] option for more information. +See the \f[V]RepositoryDirectories\f[R] option for more information. +.IP \[bu] 2 +The \f[B]\f[VB]mkosi.credentials/\f[B]\f[R] directory is used as a +source of extra credentials similar to the \f[V]Credentials=\f[R] +option. +For each file in the directory, the filename will be used as the +credential name and the file contents become the credential value, or, +if the file is executable, mkosi will execute the file and the +command\[cq]s output to stdout will be used as the credential value. +Output to stderr will be ignored. +Credentials configured with \f[V]Credentials=\f[R] take precedence over +files in \f[V]mkosi.credentials\f[R]. .PP All these files are optional. .PP Note that the location of all these files may also be configured during invocation via command line switches, and as settings in -\f[C]mkosi.conf\f[R], in case the default settings are not acceptable +\f[V]mkosi.conf\f[R], in case the default settings are not acceptable for a project. -.SH BUILD PHASES -.PP -If no build script \f[C]mkosi.build\f[R] (see above) is used the build -consists of a single phase only: the final image is generated as the -combination of \f[C]mkosi.skeleton/\f[R] (see above), the unpacked -distribution packages and \f[C]mkosi.extra/\f[R]. -.PP -If a build script \f[C]mkosi.build\f[R] is used the build consists of -two phases: in the the first \f[C]development\f[R] phase an image that -includes necessary build tools (i.e.\ the combination of -\f[C]Packages=\f[R] and \f[C]BuildPackages=\f[R] is installed) is -generated (i.e.\ the combination of \f[C]mkosi.skeleton/\f[R] and -unpacked distribution packages). -Into this image the source tree is copied and \f[C]mkosi.build\f[R] -executed. -The artifacts the \f[C]mkosi.build\f[R] generates are saved. -Then, the second \f[C]final\f[R] phase starts: an image that excludes -the build tools (i.e.\ only \f[C]Packages=\f[R] is installed, -\f[C]BuildPackages=\f[R] is not) is generated. -This time the build artifacts saved from the first phase are copied in, -and \f[C]mkosi.extra\f[R] copied on top, thus generating the final -image. -.PP -The two-phased approach ensures that source tree is executed in a clean -and comprehensive environment, while at the same the final image remains -minimal and contains only those packages necessary at runtime, but -avoiding those necessary at build-time. -.PP -Note that only the package cache \f[C]mkosi.cache/\f[R] is shared -between the two phases. -The distribution package manager is executed exactly once in each phase, -always starting from a directory tree that is populated with -\f[C]mkosi.skeleton\f[R] but nothing else. .SH CACHING .PP -\f[C]mkosi\f[R] supports three different caches for speeding up +\f[V]mkosi\f[R] supports three different caches for speeding up repetitive re-building of images. Specifically: .IP "1." 3 The package cache of the distribution package manager may be cached between builds. -This is configured with the \f[C]--cache=\f[R] option or the -\f[C]mkosi.cache/\f[R] directory. +This is configured with the \f[V]--cache-dir=\f[R] option or the +\f[V]mkosi.cache/\f[R] directory. This form of caching relies on the distribution\[cq]s package manager, -and caches distribution packages (RPM, DEB, \&...) after they are -downloaded, but before they are unpacked. +and caches distribution packages (RPM, DEB, \&...) +after they are downloaded, but before they are unpacked. .IP "2." 3 -If an \f[C]mkosi.build\f[R] script is used, by enabling incremental -build mode with \f[C]--incremental\f[R], a cached copy of the -development and final images can be made immediately before the build -sources are copied in (for the development image) or the artifacts -generated by \f[C]mkosi.build\f[R] are copied in (in case of the final -image). +If the incremental build mode is enabled with \f[V]--incremental\f[R], +cached copies of the final image and build overlay are made immediately +before the build sources are copied in (for the build overlay) or the +artifacts generated by \f[V]mkosi.build\f[R] are copied in (in case of +the final image). This form of caching allows bypassing the time-consuming package unpacking step of the distribution package managers, but is only effective if the list of packages to use remains stable, but the build sources and its scripts change regularly. Note that this cache requires manual flushing: whenever the package list is modified the cached images need to be explicitly removed before the -next re-build, using the \f[C]-f\f[R] switch. +next re-build, using the \f[V]-f\f[R] switch. .IP "3." 3 Finally, between multiple builds the build artifact directory may be -shared, using the \f[C]mkosi.builddir/\f[R] directory. +shared, using the \f[V]mkosi.builddir/\f[R] directory. This directory allows build systems such as Meson to reuse already compiled sources from a previous built, thus speeding up the build -process of the \f[C]mkosi.build\f[R] build script. +process of the \f[V]mkosi.build\f[R] build script. .PP The package cache (i.e.\ the first item above) is unconditionally useful. -The latter two caches only apply to uses of \f[C]mkosi\f[R] with a +The latter two caches only apply to uses of \f[V]mkosi\f[R] with a source tree and build script. When all three are enabled together turn-around times for complete image builds are minimal, as only changed source files need to be recompiled: @@ -1441,56 +1336,56 @@ an OS image rebuilt will be almost as quick to build the source tree only. .SH ENVIRONMENT VARIABLES .PP -The build script \f[C]mkosi.build\f[R] receives the following +The build script \f[V]mkosi.build\f[R] receives the following environment variables: .IP \[bu] 2 -\f[C]$SRCDIR\f[R] contains the path to the sources to build. +\f[V]$SRCDIR\f[R] contains the path to the sources to build. .IP \[bu] 2 -\f[C]$DESTDIR\f[R] is a directory into which any artifacts generated by +\f[V]$DESTDIR\f[R] is a directory into which any artifacts generated by the build script shall be placed. .IP \[bu] 2 -\f[C]$BUILDDIR\f[R] is only defined if \f[C]mkosi.builddir\f[R] and +\f[V]$BUILDDIR\f[R] is only defined if \f[V]mkosi.builddir\f[R] and points to the build directory to use. This is useful for all build systems that support out-of-tree builds to reuse already built artifacts from previous runs. .IP \[bu] 2 -\f[C]$WITH_DOCS\f[R] is either \f[C]0\f[R] or \f[C]1\f[R] depending on +\f[V]$WITH_DOCS\f[R] is either \f[V]0\f[R] or \f[V]1\f[R] depending on whether a build without or with installed documentation was requested -(\f[C]WithDocs=yes\f[R]). +(\f[V]WithDocs=yes\f[R]). The build script should suppress installation of any package -documentation to \f[C]$DESTDIR\f[R] in case \f[C]$WITH_DOCS\f[R] is set -to \f[C]0\f[R]. +documentation to \f[V]$DESTDIR\f[R] in case \f[V]$WITH_DOCS\f[R] is set +to \f[V]0\f[R]. .IP \[bu] 2 -\f[C]$WITH_TESTS\f[R] is either \f[C]0\f[R]or \f[C]1\f[R] depending on +\f[V]$WITH_TESTS\f[R] is either \f[V]0\f[R]or \f[V]1\f[R] depending on whether a build without or with running the test suite was requested -(\f[C]WithTests=no\f[R]). +(\f[V]WithTests=no\f[R]). The build script should avoid running any unit or integration tests in -case \f[C]$WITH_TESTS\f[R] is \f[C]0\f[R]. +case \f[V]$WITH_TESTS\f[R] is \f[V]0\f[R]. .IP \[bu] 2 -\f[C]$WITH_NETWORK\f[R] is either \f[C]0\f[R]or \f[C]1\f[R] depending on +\f[V]$WITH_NETWORK\f[R] is either \f[V]0\f[R]or \f[V]1\f[R] depending on whether a build without or with networking is being executed -(\f[C]WithNetwork=no\f[R]). +(\f[V]WithNetwork=no\f[R]). The build script should avoid any network communication in case -\f[C]$WITH_NETWORK\f[R] is \f[C]0\f[R]. +\f[V]$WITH_NETWORK\f[R] is \f[V]0\f[R]. .IP \[bu] 2 \f[V]$MKOSI_LESS\f[R] overrides options for \f[V]less\f[R] when it is invoked by \f[V]mkosi\f[R] to page output. .SH EXAMPLES .PP Create and run a raw \f[I]GPT\f[R] image with \f[I]ext4\f[R], as -\f[C]image.raw\f[R]: +\f[V]image.raw\f[R]: .IP .nf \f[C] -# mkosi --bootable --incremental boot +# mkosi -p systemd --incremental boot \f[R] .fi .PP -Create and run a bootable \f[I]GPT\f[R] image, as \f[C]foobar.raw\f[R]: +Create and run a bootable \f[I]GPT\f[R] image, as \f[V]foobar.raw\f[R]: .IP .nf \f[C] -# mkosi --format disk --bootable -o foobar.raw +# mkosi -d fedora -p kernel -p systemd -p udev -o foobar.raw # mkosi --output foobar.raw boot # mkosi --output foobar.raw qemu \f[R] @@ -1504,7 +1399,7 @@ Create and run a \f[I]Fedora Linux\f[R] image into a plain directory: \f[R] .fi .PP -Create a compressed image \f[C]image.raw.xz\f[R] and add a checksum +Create a compressed image \f[V]image.raw.xz\f[R] and add a checksum file, and install \f[I]SSH\f[R] into it: .IP .nf @@ -1513,8 +1408,8 @@ file, and install \f[I]SSH\f[R] into it: \f[R] .fi .PP -Inside the source directory of an \f[C]automake\f[R]-based project, -configure \f[I]mkosi\f[R] so that simply invoking \f[C]mkosi\f[R] +Inside the source directory of an \f[V]automake\f[R]-based project, +configure \f[I]mkosi\f[R] so that simply invoking \f[V]mkosi\f[R] without any parameters builds an OS image containing a built version of the project in its current state: .IP @@ -1527,10 +1422,9 @@ Release=24 [Output] Format=disk -Bootable=yes [Content] -Packages=openssh-clients,httpd +Packages=kernel,systemd,systemd-udev,openssh-clients,httpd BuildPackages=make,gcc,libcurl-devel EOF # cat >mkosi.build <