Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 3558 insertions, 0 deletions

diff --git a/upstream/debian-bookworm/man1/mkosi.1 b/upstream/debian-bookworm/man1/mkosi.1
new file mode 100644
index 00000000..717545e2
--- /dev/null
+++ b/upstream/debian-bookworm/man1/mkosi.1
@@ -0,0 +1,3558 @@
+'\" t
+.\" Automatically generated by Pandoc 2.17.1.1
+.\"
+.\" 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" "" "" ""
+.hy
+.SH NAME
+.PP
+mkosi \[em] Build Bespoke OS Images
+.SH SYNOPSIS
+.PP
+\f[V]mkosi [options\&...] summary\f[R]
+.PP
+\f[V]mkosi [options\&...] build [command line\&...]\f[R]
+.PP
+\f[V]mkosi [options\&...] shell [command line\&...]\f[R]
+.PP
+\f[V]mkosi [options\&...] boot [nspawn settings\&...]\f[R]
+.PP
+\f[V]mkosi [options\&...] qemu [qemu parameters\&...]\f[R]
+.PP
+\f[V]mkosi [options\&...] ssh [command line\&...]\f[R]
+.PP
+\f[V]mkosi [options\&...] journalctl [command line\&...]\f[R]
+.PP
+\f[V]mkosi [options\&...] coredumpctl [command line\&...]\f[R]
+.PP
+\f[V]mkosi [options\&...] clean\f[R]
+.PP
+\f[V]mkosi [options\&...] serve\f[R]
+.PP
+\f[V]mkosi [options\&...] burn <device>\f[R]
+.PP
+\f[V]mkosi [options\&...] bump\f[R]
+.PP
+\f[V]mkosi [options\&...] genkey\f[R]
+.PP
+\f[V]mkosi [options\&...] documentation\f[R]
+.PP
+\f[V]mkosi [options\&...] help\f[R]
+.SH DESCRIPTION
+.PP
+\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[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[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.
+.TP
+\f[V]build\f[R]
+This builds the image based on the settings passed in on the command
+line or read from configuration files.
+This command is the default if no verb is explicitly specified.
+If any command line arguments are specified, these are passed directly
+to the build script if one is defined.
+.TP
+\f[V]shell\f[R]
+This builds the image if it is not built yet, and then invokes
+\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[V]-f\f[R] in order to rebuild the image unconditionally before
+acquiring the shell, see below.
+This command must be executed as \f[V]root\f[R].
+.TP
+\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 can contain extra nspawn options as well as arguments which are
+passed as the \f[I]kernel command line\f[R] to the init system in the
+image.
+.TP
+\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 disk images that contain a boot loader
+and cpio images in which a kernel was installed.
+For cpio images a kernel can also be provided by passing the
+\f[V]-kernel\f[R] qemu argument to the \f[V]qemu\f[R] verb.
+Any arguments 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 virtual machine (\f[V]qemu\f[R]) via SSH.
+Make sure to run \f[V]mkosi ssh\f[R] with the same config as
+\f[V]mkosi build\f[R] so that it has the necessary information available
+to connect to the running virtual machine via SSH.
+Specifically, the SSH private key from the \f[V]SshKey=\f[R] setting is
+used to connect to the virtual machine.
+Use \f[V]mkosi genkey\f[R] to automatically generate a key and
+certificate that will be picked up by mkosi.
+Any arguments passed after the \f[V]ssh\f[R] verb are passed as
+arguments to the \f[V]ssh\f[R] invocation.
+To connect to a container, use \f[V]machinectl login\f[R] or
+\f[V]machinectl shell\f[R].
+.TP
+\f[V]journalctl\f[R]
+Uses \f[V]journalctl\f[R] to inspect the journal inside the image.
+Any arguments specified after the \f[V]journalctl\f[R] verb are appended
+to the \f[V]journalctl\f[R] invocation.
+.TP
+\f[V]coredumpctl\f[R]
+Uses \f[V]coredumpctl\f[R] to look for coredumps inside the image.
+Any arguments specified after the \f[V]coredumpctl\f[R] verb are
+appended to the \f[V]coredumpctl\f[R] invocation.
+.TP
+\f[V]clean\f[R]
+Remove build artifacts generated on a previous build.
+If combined with \f[V]-f\f[R], also removes incremental build cache
+images.
+If \f[V]-f\f[R] is specified twice, also removes any package cache.
+.TP
+\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[V]mkosi.output/\f[R], see below) via a small
+embedded HTTP server, listening on port 8081.
+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[V]machinectl pull-raw \&...\f[R] and
+\f[V]machinectl   pull-tar \&...\f[R].
+.TP
+\f[V]burn <device>\f[R]
+This builds the image if it is not built yet, and then writes it to the
+specified block device.
+The partition contents are written as-is, but the GPT partition table is
+corrected to match sector and disk size of the specified medium.
+.TP
+\f[V]bump\f[R]
+Bumps the image version from \f[V]mkosi.version\f[R] and writes the
+resulting version string 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[V]--auto-bump\f[R]/\f[V]-B\f[R] may be used to
+automatically bump the version after each successful build.
+.TP
+\f[V]genkey\f[R]
+Generate a pair of SecureBoot keys for usage with the
+\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[V]documentation\f[R]
+Show mkosi\[cq]s documentation.
+By default this verb will try several ways to output the documentation,
+but a specific option can be chosen with the \f[V]--doc-format\f[R]
+option.
+Distro packagers are encouraged to add a file \f[V]mkosi.1\f[R] into the
+\f[V]mkosi/resources\f[R] directory of the Python package, if it is
+missing, as well as to install it in the appropriate search path for man
+pages.
+The man page can be generated from the markdown file
+\f[V]mkosi/resources/mkosi.md\f[R] e.g via
+\f[V]pandoc -t man -s -o mkosi.1 mkosi.md\f[R].
+.TP
+\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 Commandline-only Options
+.PP
+Those settings cannot be configured in the configuration files.
+.TP
+\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[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
+ensure the intermediary cache files are removed, too, before the
+re-build is initiated.
+If a package cache is used (also see the \f[B]Files\f[R] section below),
+specifying this option thrice will ensure the package cache is removed
+too, before the re-build is initiated.
+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.
+.TP
+\f[V]--directory=\f[R], \f[V]-C\f[R]
+Takes a path to a directory.
+\f[V]mkosi\f[R] switches to this directory before doing anything.
+Note that the various configuration files are searched for in this
+directory, hence using this option is an effective way to build a
+project located in a specific directory.
+.TP
+\f[V]--debug=\f[R]
+Enable additional debugging output.
+.TP
+\f[V]--debug-shell=\f[R]
+When executing a command in the image fails, mkosi will start an
+interactive shell in the image allowing further debugging.
+.TP
+\f[V]--debug-workspace=\f[R]
+When an error occurs, the workspace directory will not be deleted.
+.TP
+\f[V]--version\f[R]
+Show package version.
+.TP
+\f[V]--help\f[R], \f[V]-h\f[R]
+Show brief usage information.
+.TP
+\f[V]--genkey-common-name=\f[R]
+Common name to be used when generating keys via mkosi\[cq]s
+\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[V]--genkey-valid-days=\f[R]
+Number of days that the keys should remain valid when generating keys
+via mkosi\[cq]s \f[V]genkey\f[R] command.
+Defaults to two years (730 days).
+.TP
+\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]--doc-format\f[R]
+The format to show the documentation in.
+Supports the values \f[V]markdown\f[R], \f[V]man\f[R], \f[V]pandoc\f[R],
+\f[V]system\f[R] and \f[V]auto\f[R].
+In the case of \f[V]markdown\f[R] the documentation is shown in the
+original Markdown format.
+\f[V]man\f[R] shows the documentation in man page format, if it is
+available.
+\f[V]pandoc\f[R] will generate the man page format on the fly, if
+\f[V]pandoc\f[R] is available.
+\f[V]system\f[R] will show the system-wide man page for mkosi, which may
+or may not correspond to the version you are using, depending on how you
+installed mkosi.
+\f[V]auto\f[R], which is the default, will try all methods in the order
+\f[V]man\f[R], \f[V]pandoc\f[R], \f[V]markdown\f[R], \f[V]system\f[R].
+.TP
+\f[V]--json\f[R]
+Show the summary output as JSON-SEQ.
+.SS Supported output formats
+.PP
+The following output formats are supported:
+.IP \[bu] 2
+Raw \f[I]GPT\f[R] disk image, created using systemd-repart
+(\f[I]disk\f[R])
+.IP \[bu] 2
+Plain directory, containing the OS tree (\f[I]directory\f[R])
+.IP \[bu] 2
+Tar archive (\f[I]tar\f[R])
+.IP \[bu] 2
+CPIO archive (\f[I]cpio\f[R])
+.PP
+The output format may also be set to \f[I]none\f[R] to have mkosi
+produce no image at all.
+This can be useful if you only want to use the image to produce another
+output in the build scripts (e.g.\ build an rpm).
+.PP
+When a \f[I]GPT\f[R] disk image is created, repart partition definition
+files may be placed in \f[V]mkosi.repart/\f[R] to configure the
+generated disk image.
+.PP
+It is highly recommended to run \f[V]mkosi\f[R] on a file system that
+supports reflinks such as XFS and btrfs and to keep all related
+directories on the same file system.
+This allows mkosi to create images very quickly by using reflinks to
+perform copying via copy-on-write operations.
+.SS Configuration Settings
+.PP
+The following settings can be set through configuration files (the
+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.local.conf\f[R] is parsed if it exists.
+This file should be in the gitignore (or equivalent) and is intended for
+local configuration.
+.IP \[bu] 2
+Any default paths (depending on the option) are configured if the
+corresponding path exists.
+.IP \[bu] 2
+\f[V]mkosi.conf\f[R] is parsed if it exists in the directory configured
+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.
+.PP
+Note that if the same setting is configured twice, the later assignment
+overrides the earlier assignment unless the setting is a list based
+setting.
+Also note that before v16, we used to do the opposite, where the earlier
+assignment would be used instead of later assignments.
+.PP
+Settings that take a list of values are merged by appending the new
+values to the previously configured values.
+Assigning the empty string to such a setting removes all previously
+assigned values, and overrides any configured default values as well.
+.PP
+If a setting\[cq]s name in the configuration file is prefixed with
+\f[V]\[at]\f[R], it configures the default value used for that setting
+if no explicit default value is set.
+This can be used to set custom default values in configuration files
+that can still be overridden by specifying the setting explicitly via
+the CLI.
+.PP
+To conditionally include configuration files, the \f[V][Match]\f[R]
+section can be used.
+Matches can use a pipe symbol (\f[V]|\f[R]) after the equals sign
+(\f[V]\&...=|\&...\f[R]), which causes the match to become a triggering
+match.
+The config file will be included if the logical AND of all
+non-triggering matches and the logical OR of all triggering matches is
+satisfied.
+To negate the result of a match, prefix the argument with an exclamation
+mark.
+If an argument is prefixed with the pipe symbol and an exclamation mark,
+the pipe symbol must be passed first, and the exclamation second.
+.PP
+Note that \f[V][Match]\f[R] settings match against the current values of
+specific settings, and do not take into account changes made to the
+setting in configuration files that have not been parsed yet.
+Also note that matching against a setting and then changing its value
+afterwards in a different config file may lead to unexpected results.
+.PP
+The \f[V][Match]\f[R] section of a \f[V]mkosi.conf\f[R] file in a
+directory applies to the entire directory.
+If the conditions are not satisfied, the entire directory is skipped.
+The \f[V][Match]\f[R] sections of files in \f[V]mkosi.conf.d/\f[R] and
+\f[V]mkosi.local.conf\f[R] only apply to the file itself.
+.PP
+If there are multiple \f[V][Match]\f[R] sections in the same
+configuration file, each of them has to be satisfied in order for the
+configuration file to be included.
+Specifically, triggering matches only apply to the current
+\f[V][Match]\f[R] section and are reset between multiple
+\f[V][Match]\f[R] sections.
+As an example, the following will only match if the output format is one
+of \f[V]disk\f[R] or \f[V]directory\f[R] and the architecture is one of
+\f[V]x86-64\f[R] or \f[V]arm64\f[R]:
+.IP
+.nf
+\f[C]
+[Match]
+Format=|disk
+Format=|directory
+
+[Match]
+Architecture=|x86-64
+Architecture=|arm64
+\f[R]
+.fi
+.PP
+Command line options that take no argument are shown without \f[V]=\f[R]
+in their long version.
+In the config files, they should be specified with a boolean argument:
+either \f[V]1\f[R], \f[V]yes\f[R], or \f[V]true\f[R] to enable, or
+\f[V]0\f[R], \f[V]no\f[R], \f[V]false\f[R] to disable.
+.SS [Match] Section.
+.TP
+\f[V]Profile=\f[R]
+Matches against the configured profile.
+.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]Architecture=\f[R]
+Matches against the configured architecture.
+If this condition is used and no architecture has been explicitly
+configured yet, the host architecture is 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.
+.TP
+\f[V]ImageId=\f[R]
+Matches against the configured image ID, supporting globs.
+If this condition is used and no image ID has been explicitly configured
+yet, this condition fails.
+.TP
+\f[V]ImageVersion=\f[R]
+Matches against the configured image version.
+Image versions can be prepended by the operators \f[V]==\f[R],
+\f[V]!=\f[R], \f[V]>=\f[R], \f[V]<=\f[R], \f[V]<\f[R], \f[V]>\f[R] for
+rich version comparisons according to the UAPI group version format
+specification.
+If no operator is prepended, the equality operator is assumed by
+default.
+If this condition is used and no image version has been explicitly
+configured yet, this condition fails.
+.TP
+\f[V]Bootable=\f[R]
+Matches against the configured value for the \f[V]Bootable=\f[R]
+feature.
+Takes a boolean value or \f[V]auto\f[R].
+.TP
+\f[V]Format=\f[R]
+Matches against the configured value for the \f[V]Format=\f[R] option.
+Takes an output format (see the \f[V]Format=\f[R] option).
+.TP
+\f[V]SystemdVersion=\f[R]
+Matches against the systemd version on the host (as reported by
+\f[V]systemctl --version\f[R]).
+Values can be prepended by the operators \f[V]==\f[R], \f[V]!=\f[R],
+\f[V]>=\f[R], \f[V]<=\f[R], \f[V]<\f[R], \f[V]>\f[R] for rich version
+comparisons according to the UAPI group version format specification.
+If no operator is prepended, the equality operator is assumed by
+default.
+.TP
+\f[V]BuildSources=\f[R]
+Takes a build source target path (see \f[V]BuildSources=\f[R]).
+This match is satisfied if any of the configured build sources uses this
+target path.
+For example, if we have a \f[V]mkosi.conf\f[R] file containing:
+.IP
+.nf
+\f[C]
+[Content]
+BuildSources=../abc/qed:kernel
+\f[R]
+.fi
+.PP
+and a drop-in containing:
+.IP
+.nf
+\f[C]
+[Match]
+BuildSources=kernel
+\f[R]
+.fi
+.TP
+The drop-in will be included.
+Any absolute paths passed to this setting are interpreted relative to
+the current working directory.
+.TP
+\f[V]HostArchitecture=\f[R]
+Matches against the host\[cq]s native architecture.
+See the \f[V]Architecture=\f[R] setting for a list of possible values.
+.PP
+.TS
+tab(@);
+lw(20.7n) lw(6.9n) lw(17.7n) lw(24.6n).
+T{
+Matcher
+T}@T{
+Globs
+T}@T{
+Rich Comparisons
+T}@T{
+Default
+T}
+_
+T{
+\f[V]Profile=\f[R]
+T}@T{
+no
+T}@T{
+no
+T}@T{
+match fails
+T}
+T{
+\f[V]Distribution=\f[R]
+T}@T{
+no
+T}@T{
+no
+T}@T{
+match host distribution
+T}
+T{
+\f[V]Release=\f[R]
+T}@T{
+no
+T}@T{
+no
+T}@T{
+match host release
+T}
+T{
+\f[V]Architecture=\f[R]
+T}@T{
+no
+T}@T{
+no
+T}@T{
+match host architecture
+T}
+T{
+\f[V]PathExists=\f[R]
+T}@T{
+no
+T}@T{
+no
+T}@T{
+n/a
+T}
+T{
+\f[V]ImageId=\f[R]
+T}@T{
+yes
+T}@T{
+no
+T}@T{
+match fails
+T}
+T{
+\f[V]ImageVersion=\f[R]
+T}@T{
+no
+T}@T{
+yes
+T}@T{
+match fails
+T}
+T{
+\f[V]Bootable=\f[R]
+T}@T{
+no
+T}@T{
+no
+T}@T{
+match auto feature
+T}
+T{
+\f[V]Format=\f[R]
+T}@T{
+no
+T}@T{
+no
+T}@T{
+match default format
+T}
+T{
+\f[V]SystemdVersion=\f[R]
+T}@T{
+no
+T}@T{
+yes
+T}@T{
+n/a
+T}
+T{
+\f[V]BuildSources=\f[R]
+T}@T{
+no
+T}@T{
+no
+T}@T{
+match fails
+T}
+T{
+\f[V]HostArchitecture=\f[R]
+T}@T{
+no
+T}@T{
+no
+T}@T{
+n/a
+T}
+.TE
+.SS [Config] Section
+.TP
+\f[V]Profile=\f[R], \f[V]--profile=\f[R]
+Select the given profile.
+A profile is a configuration file or directory in the
+\f[V]mkosi.profiles/\f[R] directory.
+When selected, this configuration file or directory is included after
+parsing the \f[V]mkosi.conf\f[R] file, but before any
+\f[V]mkosi.conf.d/*.conf\f[R] drop in configuration.
+.TP
+\f[V]Include=\f[R], \f[V]--include=\f[R]
+Include extra configuration from the given file or directory.
+The extra configuration is included immediately after parsing the
+setting, except when a default is set using \f[V]\[at]Include=\f[R], in
+which case the configuration is included after parsing all the other
+configuration files.
+Note that each path containing extra configuration is only parsed once,
+even if included more than once with \f[V]Include=\f[R].
+.TP
+\f[V]InitrdInclude=\f[R], \f[V]--initrd-include=\f[R]
+Same as \f[V]Include=\f[R], but the extra configuration files or
+directories are included when building the default initrd.
+.TP
+\f[V]Images=\f[R], \f[V]--image=\f[R]
+If specified, only build the given image.
+Can be specified multiple times to build multiple images.
+All the given images and their dependencies are built.
+If not specified, all images are built.
+See the \f[B]Building multiple images\f[R] section for more information.
+Note that this section only takes effect when specified in the global
+configuration files.
+It has no effect if specified as an image specific setting.
+.TP
+\f[V]Dependencies=\f[R], \f[V]--dependency=\f[R]
+The images that this image depends on specified as a comma-separated
+list.
+All images configured in this option will be built before this image and
+will be pulled in as dependencies of this image when \f[V]Images=\f[R]
+is used.
+.TP
+\f[V]MinimumVersion=\f[R], \f[V]--minimum-version=\f[R]
+The minimum mkosi version required to build this configuration.
+If specified multiple times, the highest specified version is used.
+.SS [Distribution] Section
+.TP
+\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[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]rhel\f[R], \f[V]rhel-ubi\f[R],
+\f[V]openmandriva\f[R], \f[V]rocky\f[R], \f[V]alma\f[R],
+\f[V]custom\f[R].
+If not specified, defaults to the distribution of the host or
+\f[V]custom\f[R] if the distribution of the host is not a supported
+distribution.
+.TP
+\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[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, or the version
+of the distribution running on the host if it matches the configured
+distribution.
+.TP
+\f[V]Architecture=\f[R], \f[V]--architecture=\f[R]
+The architecture to build the image for.
+The architectures that are actually supported depends on the
+distribution used and whether a bootable image is requested or not.
+When building for a foreign architecture, you\[cq]ll also need to
+install and register a user mode emulator for that architecture.
+One of the following architectures can be specified per image built:
+\f[V]alpha\f[R], \f[V]arc\f[R], \f[V]arm\f[R], \f[V]arm64\f[R],
+\f[V]ia64\f[R], \f[V]loongarch64\f[R], \f[V]mips64-le\f[R],
+\f[V]mips-le\f[R], \f[V]parisc\f[R], \f[V]ppc\f[R], \f[V]ppc64\f[R],
+\f[V]ppc64-le\f[R], \f[V]riscv32\f[R], \f[V]riscv64\f[R],
+\f[V]s390\f[R], \f[V]s390x\f[R], \f[V]tilegx\f[R], \f[V]x86\f[R],
+\f[V]x86-64\f[R].
+.TP
+\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.
+If not provided, the default mirror for the distribution is used.
+The default mirrors for each distribution are as follows (unless
+specified, the same mirror is used for all architectures):
+.PP
+.TS
+tab(@);
+lw(13.5n) lw(29.5n) lw(27.0n).
+T{
+T}@T{
+x86-64
+T}@T{
+aarch64
+T}
+_
+T{
+\f[V]debian\f[R]
+T}@T{
+http://deb.debian.org/debian
+T}@T{
+T}
+T{
+\f[V]arch\f[R]
+T}@T{
+https://geo.mirror.pkgbuild.com
+T}@T{
+http://mirror.archlinuxarm.org
+T}
+T{
+\f[V]opensuse\f[R]
+T}@T{
+http://download.opensuse.org
+T}@T{
+T}
+T{
+\f[V]ubuntu\f[R]
+T}@T{
+http://archive.ubuntu.com
+T}@T{
+http://ports.ubuntu.com
+T}
+T{
+\f[V]centos\f[R]
+T}@T{
+https://mirrors.centos.org
+T}@T{
+T}
+T{
+\f[V]rocky\f[R]
+T}@T{
+https://mirrors.rockylinux.org
+T}@T{
+T}
+T{
+\f[V]alma\f[R]
+T}@T{
+https://mirrors.almalinux.org
+T}@T{
+T}
+T{
+\f[V]fedora\f[R]
+T}@T{
+https://mirrors.fedoraproject.org
+T}@T{
+T}
+T{
+\f[V]rhel-ubi\f[R]
+T}@T{
+https://cdn-ubi.redhat.com
+T}@T{
+T}
+T{
+\f[V]mageia\f[R]
+T}@T{
+https://www.mageia.org
+T}@T{
+T}
+T{
+\f[V]openmandriva\f[R]
+T}@T{
+http://mirrors.openmandriva.org
+T}@T{
+T}
+.TE
+.TP
+\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[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[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[V]--local-mirror=\f[R]
+and using only a repository from a local filesystem.
+Not used for DNF-based distros yet.
+.TP
+\f[V]Repositories=\f[R], \f[V]--repositories=\f[R]
+Enable package repositories that are disabled by default.
+This can be used to enable the EPEL repos for CentOS or different
+components of the Debian/Ubuntu repositories.
+.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
+cache is already fully populated.
+.TP
+\f[V]PackageManagerTrees=\f[R], \f[V]--package-manager-tree=\f[R]
+This option mirrors the above \f[V]SkeletonTrees=\f[R] option and
+defaults to the same value if not configured otherwise, but installs the
+files to a subdirectory of the workspace directory instead of the OS
+tree.
+This subdirectory of the workspace is used to configure the package
+manager.
+\f[V]mkosi\f[R] will look for the package manager configuration and
+related files in the configured package manager trees.
+Unless specified otherwise, it will use the configuration files from
+their canonical locations in \f[V]/usr\f[R] or \f[V]/etc\f[R] in the
+package manager trees.
+For example, it will look for \f[V]etc/dnf/dnf.conf\f[R] in the package
+manager trees if \f[V]dnf\f[R] is used to install packages.
+\f[V]SkeletonTrees=\f[R] and \f[V]PackageManagerTrees=\f[R] fulfill
+similar roles.
+Use \f[V]SkeletonTrees=\f[R] if you want the files to be present in the
+final image.
+Use \f[V]PackageManagerTrees=\f[R] if you don\[cq]t want the files to be
+present in the final image, e.g.\ when building an initrd or if you want
+to refer to paths outside of the image in your repository configuration.
+.SS [Output] Section
+.TP
+\f[V]Format=\f[R], \f[V]--format=\f[R], \f[V]-t\f[R]
+The image format type to generate.
+One of \f[V]directory\f[R] (for generating an OS image directly in a
+local directory), \f[V]tar\f[R] (similar, but a tarball of the OS image
+is generated), \f[V]cpio\f[R] (similar, but a cpio archive is
+generated), \f[V]disk\f[R] (a block device OS image with a GPT partition
+table), \f[V]uki\f[R] (a unified kernel image with the OS image in the
+\f[V].initrd\f[R] PE section), \f[V]esp\f[R] (\f[V]uki\f[R] but wrapped
+in a disk image with only an ESP partition), \f[V]sysext\f[R],
+\f[V]confext\f[R], \f[V]portable\f[R] or \f[V]none\f[R] (the OS image is
+solely intended as a build image to produce another artifact).
+If the \f[V]disk\f[R] output format is used, the disk image is generated
+using \f[V]systemd-repart\f[R].
+The repart partition definition files to use can be configured using the
+\f[V]RepartDirectories=\f[R] setting or via \f[V]mkosi.repart/\f[R].
+When verity partitions are configured using systemd-repart\[cq]s
+\f[V]Verity=\f[R] setting, mkosi will automatically parse the verity
+hash partition\[cq]s roothash from systemd-repart\[cq]s JSON output and
+include it in the kernel command line of every unified kernel image
+built by mkosi.
+.TP
+\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[V]json\f[R] (the standard JSON
+output format that describes the packages installed),
+\f[V]changelog\f[R] (a human-readable text format designed for diffing).
+By default no manifest is generated.
+.TP
+\f[V]Output=\f[R], \f[V]--output=\f[R], \f[V]-o\f[R]
+Name to use for the generated output image file or directory.
+All outputs will be prefixed with the given name.
+Defaults to \f[V]image\f[R] or, if \f[V]ImageId=\f[R] is specified, it
+is used as the default output name, optionally suffixed with the version
+set with \f[V]ImageVersion=\f[R].
+Note that this option does not allow configuring the output directory,
+use \f[V]OutputDirectory=\f[R] for that.
+Note that this only specifies the output prefix, depending on the
+specific output format, compression and image version used, the full
+output name might be \f[V]image_7.8.raw.xz\f[R].
+.TP
+\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[V]xz\f[R], \f[V]zstd\f[R]).
+\f[V]zstd\f[R] compression is used by default, except CentOS and
+derivatives up to version 8, which default to \f[V]xz\f[R].
+Note that when applied to block device image types, compression means
+the image cannot be started directly but needs to be decompressed first.
+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[V]tar\f[R], \f[V]cpio\f[R], \f[V]uki\f[R], and
+\f[V]esp\f[R].
+.TP
+\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.
+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.
+.TP
+\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, a subdirectory of \f[V]$XDG_CACHE_HOME\f[R] (if set),
+\f[V]$HOME/.cache\f[R] (if set) or \f[V]/var/tmp\f[R] is 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[V]mkosi\f[R] invocation be aborted abnormally (for example, due to
+reboot/power failure).
+.TP
+\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[V]mkosi.cache/\f[R] directory is
+found in the local directory it is automatically used for this purpose.
+.TP
+\f[V]BuildDirectory=\f[R], \f[V]--build-dir=\f[R]
+Takes a path to a directory to use as the 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.
+The build scripts can find the path to this directory in the
+\f[V]$BUILDDIR\f[R] environment variable.
+This directory is mounted into the image\[cq]s root directory when
+\f[V]mkosi-chroot\f[R] is invoked during execution of the build scripts.
+If this option is not specified, but a directory
+\f[V]mkosi.builddir/\f[R] exists in the local directory it is
+automatically used for this purpose (also see the \f[B]Files\f[R]
+section below).
+.TP
+\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[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[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[V]$IMAGE_VERSION\f[R] to any build
+scripts invoked (which may be useful to patch it into
+\f[V]/etc/os-release\f[R] or similar, in particular the
+\f[V]IMAGE_VERSION=\f[R] field of it).
+.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).
+The identifier is also passed via the \f[V]$IMAGE_ID\f[R] to any build
+scripts invoked.
+The image ID is automatically added to \f[V]/usr/lib/os-release\f[R].
+.TP
+\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[V]/usr\f[R]
+partition along with its Verity partition and unified kernel.
+.TP
+\f[V]RepartDirectories=\f[R], \f[V]--repart-dir=\f[R]
+Paths to directories containing systemd-repart partition definition
+files that are used when mkosi invokes systemd-repart when building a
+disk image.
+If \f[V]mkosi.repart/\f[R] exists in the local directory, it will be
+used for this purpose as well.
+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[V]SectorSize=\f[R], \f[V]--sector-size=\f[R]
+Override the default sector size that systemd-repart uses when building
+a disk image.
+.TP
+\f[V]RepartOffline=\f[R], \f[V]--repart-offline=\f[R]
+Specifies whether to build disk images using loopback devices.
+Enabled by default.
+When enabled, \f[V]systemd-repart\f[R] will not use loopback devices to
+build disk images.
+When disabled, \f[V]systemd-repart\f[R] will always use loopback devices
+to build disk images.
+Note that when using \f[V]RepartOffline=no\f[R] mkosi cannot run
+unprivileged and the image build has to be done as the root user outside
+of any containers and with loopback devices available on the host
+system.
+There are currently two known scenarios where \f[V]RepartOffline=no\f[R]
+has to be used.
+The first is when using \f[V]Subvolumes=\f[R] in a repart partition
+definition file, as subvolumes cannot be created without using loopback
+devices.
+The second is when creating a system with SELinux and an XFS root
+partition.
+Because \f[V]mkfs.xfs\f[R] does not support populating an XFS filesystem
+with extended attributes, loopback devices have to be used to ensure the
+SELinux extended attributes end up in the generated XFS filesystem.
+.TP
+\f[V]Overlay=\f[R], \f[V]--overlay\f[R]
+When used together with \f[V]BaseTrees=\f[R], the output will consist
+only out of changes to the specified base trees.
+Each base tree is attached as a lower layer in an overlayfs structure,
+and the output becomes the upper layer, initially empty.
+Thus files that are not modified compared to the base trees will not be
+present in the final output.
+This option may be used to create systemd \f[I]system extensions\f[R] or
+\f[I]portable
+services\f[R] (https://uapi-group.org/specifications/specs/extension_image).
+.TP
+\f[V]UseSubvolumes=\f[R], \f[V]--use-subvolumes=\f[R]
+Takes a boolean or \f[V]auto\f[R].
+Enables or disables use of btrfs subvolumes for directory tree outputs.
+If enabled, mkosi will create the root directory as a btrfs subvolume
+and use btrfs subvolume snapshots where possible to copy base or cached
+trees which is much faster than doing a recursive copy.
+If explicitly enabled and \f[V]btrfs\f[R] is not installed or subvolumes
+cannot be created, an error is raised.
+If \f[V]auto\f[R], missing \f[V]btrfs\f[R] or failures to create
+subvolumes are ignored.
+.TP
+\f[V]Seed=\f[R], \f[V]--seed=\f[R]
+Takes a UUID as argument or the special value \f[V]random\f[R].
+Overrides the seed that
+\f[V]systemd-repart(8)\f[R] (https://www.freedesktop.org/software/systemd/man/systemd-repart.service.html)
+uses when building a disk image.
+This is useful to achieve reproducible builds, where deterministic UUIDs
+and other partition metadata should be derived on each build.
+.TP
+\f[V]SourceDateEpoch=\f[R], \f[V]--source-date-epoch=\f[R]
+Takes a timestamp as argument.
+Resets file modification times of all files to this timestamp.
+The variable is also propagated to systemd-repart and scripts executed
+by mkosi.
+If not set explicitly, \f[V]SOURCE_DATE_EPOCH\f[R] from
+\f[V]--environment\f[R] and from the host environment are tried in that
+order.
+This is useful to make builds reproducible.
+See
+SOURCE_DATE_EPOCH (https://reproducible-builds.org/specs/source-date-epoch/)
+for more information.
+.SS [Content] Section
+.TP
+\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.
+Use \f[V]BuildPackages=\f[R] to specify packages that shall only be
+installed in an overlay that is mounted when the prepare scripts are
+executed with the \f[V]build\f[R] argument and when the build scripts
+are executed.
+The types and syntax of \f[I]package specifications\f[R] that are
+allowed depend on the package installer (e.g.\ \f[V]dnf\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.
+Example: when using a distro that uses \f[V]dnf\f[R], the following
+configuration 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[V]/usr/bin/ld\f[R], the packages in the
+\f[I]Development Tools\f[R] group, and the package that contains the
+\f[V]mypy\f[R] python module.
+.IP
+.nf
+\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]
+.fi
+.PP
+: Note that since mkosi runs in a sandbox with most of the host files
+unavailable, any local packages have to be mounted into the sandbox
+explicitly using \f[V]BuildSources=\f[R].
+For example, let\[cq]s say we have a local package located at
+\f[V]../my-packages/abc.rpm\f[R] relative to the mkosi working
+directory, then we\[cq]d be able to install it as follows:
+.IP
+.nf
+\f[C]
+BuildSources=../my-packages:my-packages-in-sandbox
+Packages=my-packages-in-sandbox/abc.rpm
+\f[R]
+.fi
+.TP
+\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 an overlay that is made available on top of the image to the prepare
+scripts when executed with the \f[V]build\f[R] argument and the build
+scripts.
+This option should be used to list packages containing header files,
+compilers, build systems, linkers and other build tools the
+\f[V]mkosi.build\f[R] scripts require to operate.
+Note that packages listed here will be absent in the final image.
+.TP
+\f[V]PackageDirectories=\f[R], \f[V]--package-directory=\f[R]
+Specify directories containing extra packages to be made available
+during the build.
+\f[V]mkosi\f[R] will create a local repository containing all packages
+in these directories and make it available when installing packages or
+running scripts.
+Note that this local repository is also made available when running
+scripts.
+Build scripts can add more packages to the local repository by placing
+the built packages in \f[V]$PACKAGEDIR\f[R].
+.TP
+\f[V]WithRecommends=\f[R], \f[V]--with-recommends=\f[R]
+Configures whether to install recommended or weak dependencies,
+depending on how they are named by the used package manager, or not.
+By default, recommended packages are not installed.
+This is only used for package managers that support the concept, which
+are currently apt, dnf and zypper.
+.TP
+\f[V]WithDocs=\f[R], \f[V]--with-docs\f[R]
+Include documentation in the image.
+Enabled by default.
+When disabled, if the underlying distribution package manager supports
+it documentation is not included in the image.
+The \f[V]$WITH_DOCS\f[R] environment variable passed to the
+\f[V]mkosi.build\f[R] scripts is set to \f[V]0\f[R] or \f[V]1\f[R]
+depending on whether this option is enabled or disabled.
+.TP
+\f[V]BaseTrees=\f[R], \f[V]--base-tree=\f[R]
+Takes a comma separated list of paths to use as base trees.
+When used, these base trees are each copied into the OS tree and form
+the base distribution instead of installing the distribution from
+scratch.
+Only extra packages are installed on top of the ones already installed
+in the base trees.
+Note that for this to work properly, the base image still needs to
+contain the package manager metadata (see
+\f[V]CleanPackageMetadata=\f[R]).
+Instead of a directory, a tar file or a disk image may be provided.
+In this case it is unpacked into the OS tree.
+This mode of operation allows setting permissions and file ownership
+explicitly, in particular for projects stored in a version control
+system such as \f[V]git\f[R] which retain full file ownership and access
+mode metadata for committed files.
+.TP
+\f[V]SkeletonTrees=\f[R], \f[V]--skeleton-tree=\f[R]
+Takes a comma separated list of colon separated path pairs.
+The first path of each pair refers to a directory to copy into the OS
+tree before invoking the package manager.
+The second path of each pair 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.
+The second path is always interpreted as an absolute path.
+Use this to insert files and directories into the OS tree before the
+package manager installs any packages.
+If the \f[V]mkosi.skeleton/\f[R] directory is found in the local
+directory it is also used for this purpose with the root directory as
+target (also see the \f[B]Files\f[R] section below).
+Note that skeleton trees are cached and any changes to skeleton trees
+after a cached image has been built (when using \f[V]Incremental=\f[R])
+are only applied when the cached image is rebuilt (by using
+\f[V]-ff\f[R] or running \f[V]mkosi -f clean\f[R]).
+As with the base tree logic above, instead of a directory, a tar file
+may be provided too.
+\f[V]mkosi.skeleton.tar\f[R] will be automatically used if found in the
+local directory.
+.TP
+\f[V]ExtraTrees=\f[R], \f[V]--extra-tree=\f[R]
+Takes a comma separated list of colon separated path pairs.
+The first path of each pair refers to a directory to copy from the host
+into the image.
+The second path of each pair 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.
+The second path is always interpreted as an absolute path.
+Use this to override any default configuration files shipped with the
+distribution.
+If the \f[V]mkosi.extra/\f[R] directory is found in the local directory
+it is also used for this purpose with the root directory as target.
+(also see the \f[B]Files\f[R] section below).
+As with the base tree logic above, instead of a directory, a tar file
+may be provided too.
+\f[V]mkosi.extra.tar\f[R] will be automatically used if found in the
+local directory.
+.TP
+\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[V]Packages=\f[R].
+The removal will be performed as one of the last steps.
+This step is skipped if \f[V]CleanPackageMetadata=no\f[R] is used.
+.TP
+\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[V]CleanPackageMetadata=\f[R], \f[V]--clean-package-metadata=\f[R]
+Enable/disable removal of package manager databases at the end of
+installation.
+Can be specified as \f[V]true\f[R], \f[V]false\f[R], or \f[V]auto\f[R]
+(the default).
+With \f[V]auto\f[R], 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[V]PrepareScripts=\f[R], \f[V]--prepare-script=\f[R]
+Takes a comma-separated list of paths to executables that are used as
+the prepare scripts for this image.
+See the \f[B]Scripts\f[R] section for more information.
+.TP
+\f[V]BuildScripts=\f[R], \f[V]--build-script=\f[R]
+Takes a comma-separated list of paths to executables that are used as
+the build scripts for this image.
+See the \f[B]Scripts\f[R] section for more information.
+.TP
+\f[V]PostInstallationScripts=\f[R], \f[V]--postinst-script=\f[R]
+Takes a comma-separated list of paths to executables that are used as
+the post-installation scripts for this image.
+See the \f[B]Scripts\f[R] section for more information.
+.TP
+\f[V]FinalizeScripts=\f[R], \f[V]--finalize-script=\f[R]
+Takes a comma-separated list of paths to executables that are used as
+the finalize scripts for this image.
+See the \f[B]Scripts\f[R] section for more information.
+.TP
+\f[V]BuildSources=\f[R], \f[V]--build-sources=\f[R]
+Takes a comma separated list of colon separated path pairs.
+The first path of each pair refers to a directory to mount from the
+host.
+The second path of each pair refers to the directory where the source
+directory should be mounted when running scripts.
+Every target path is prefixed with \f[V]/work/src\f[R] and all build
+sources are sorted lexicographically by their target before mounting, so
+that top level paths are mounted first.
+If not configured explicitly, the current working directory is mounted
+to \f[V]/work/src\f[R].
+.TP
+\f[V]BuildSourcesEphemeral=\f[R], \f[V]--build-sources-ephemeral=\f[R]
+Takes a boolean.
+Disabled by default.
+Configures whether changes to source directories (The working directory
+and configured using \f[V]BuildSources=\f[R]) are persisted.
+If enabled, all source directories will be reset to their original state
+after scripts finish executing.
+.TP
+\f[V]Environment=\f[R], \f[V]--environment=\f[R]
+Adds variables to the environment that package managers and the
+prepare/build/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[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[V]EnvironmentFiles=\f[R], \f[V]--env-file=\f[R]
+Takes a comma-separated list of paths to files that contain environment
+variable definitions to be added to the scripting environment.
+Uses \f[V]mkosi.env\f[R] if it is found in the local directory.
+The variables are first read from \f[V]mkosi.env\f[R] if it exists, then
+from the given list of files and then from the \f[V]Environment=\f[R]
+settings.
+.TP
+\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[V]$WITH_TESTS\f[R] environment variable is set to \f[V]0\f[R] when
+the \f[V]mkosi.build\f[R] scripts are invoked.
+This is supposed to be used by the build scripts 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[V]mkosi.build\f[R]
+build scripts honor it.
+.TP
+\f[V]WithNetwork=\f[R], \f[V]--with-network=\f[R]
+When true, enables network connectivity while the build scripts
+\f[V]mkosi.build\f[R] are invoked.
+By default, the build scripts run with networking turned off.
+The \f[V]$WITH_NETWORK\f[R] environment variable is passed to the
+\f[V]mkosi.build\f[R] build scripts indicating whether the build is done
+with or without network.
+.TP
+\f[V]Bootable=\f[R], \f[V]--bootable=\f[R]
+Takes a boolean or \f[V]auto\f[R].
+Enables or disables generation of a bootable image.
+If enabled, mkosi will install an EFI bootloader, and add an ESP
+partition when the disk image output is used.
+If the selected EFI bootloader (See \f[V]Bootloader=\f[R]) 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 the selected EFI bootloader
+can\[cq]t be found.
+If disabled, no bootloader will be installed even if found inside the
+image, 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]Bootloader=\f[R], \f[V]--bootloader=\f[R]
+Takes one of \f[V]none\f[R], \f[V]systemd-boot\f[R], \f[V]uki\f[R] or
+\f[V]grub\f[R].
+Defaults to \f[V]systemd-boot\f[R].
+If set to \f[V]none\f[R], no EFI bootloader will be installed into the
+image.
+If set to \f[V]systemd-boot\f[R], systemd-boot will be installed and for
+each installed kernel, a UKI will be generated and stored in
+\f[V]EFI/Linux\f[R] in the ESP.
+If set to \f[V]uki\f[R], a single UKI will be generated for the latest
+installed kernel (the one with the highest version) which is installed
+to \f[V]EFI/BOOT/BOOTX64.EFI\f[R] in the ESP.
+If set to \f[V]grub\f[R], for each installed kernel, a UKI will be
+generated and stored in \f[V]EFI/Linux\f[R] in the ESP.
+For each generated UKI, a menu entry is appended to the grub
+configuration in \f[V]grub/grub.cfg\f[R] in the ESP which chainloads
+into the UKI.
+A shim grub.cfg is also written to \f[V]EFI/<distribution>/grub.cfg\f[R]
+in the ESP which loads \f[V]grub/grub.cfg\f[R] in the ESP for
+compatibility with signed versions of grub which load the grub
+configuration from this location.
+Note that we do not yet install grub to the ESP when
+\f[V]Bootloader=\f[R] is set to \f[V]grub\f[R].
+This has to be done manually in a postinst or finalize script.
+The grub EFI binary should be installed to
+\f[V]/efi/EFI/BOOT/BOOTX64.EFI\f[R] (or similar depending on the
+architecture) and should be configured to load its configuration from
+\f[V]EFI/<distribution>/grub.cfg\f[R] in the ESP.
+Signed versions of grub shipped by distributions will load their
+configuration from this location by default.
+.TP
+\f[V]BiosBootloader=\f[R], \f[V]--bios-bootloader=\f[R]
+Takes one of \f[V]none\f[R] or \f[V]grub\f[R].
+Defaults to \f[V]none\f[R].
+If set to \f[V]none\f[R], no BIOS bootloader will be installed.
+If set to \f[V]grub\f[R], grub is installed as the BIOS boot loader if a
+bootable image is requested with the \f[V]Bootable=\f[R] option.
+If no repart partition definition files are configured, mkosi will add a
+grub BIOS boot partition and an EFI system partition to the default
+partition definition files.
+Note that this option is not mutually exclusive with
+\f[V]Bootloader=\f[R].
+It is possible to have an image that is both bootable on UEFI and BIOS
+by configuring both \f[V]Bootloader=\f[R] and \f[V]BiosBootloader=\f[R].
+The grub BIOS boot partition should have UUID
+\f[V]21686148-6449-6e6f-744e-656564454649\f[R] and should be at least
+1MB.
+Even if no EFI bootloader is installed, we still need an ESP for BIOS
+boot as that\[cq]s where we store the kernel, initrd and grub modules.
+.TP
+\f[V]ShimBootloader=\f[R], \f[V]--shim-bootloader=\f[R]
+Takes one of \f[V]none\f[R], \f[V]unsigned\f[R], or \f[V]signed\f[R].
+Defaults to \f[V]none\f[R].
+If set to \f[V]none\f[R], shim and MokManager will not be installed to
+the ESP.
+If set to \f[V]unsigned\f[R], mkosi will search for unsigned shim and
+MokManager EFI binaries and install them.
+If \f[V]SecureBoot=\f[R] is enabled, mkosi will sign the unsigned EFI
+binaries before installing thel.
+If set to \f[V]signed\f[R], mkosi will search for signed EFI binaries
+and install those.
+Even if \f[V]SecureBoot=\f[R] is enabled, mkosi won\[cq]t sign these
+binaries again.
+Note that this option only takes effect when an image that is bootable
+on UEFI firmware is requested using other options (\f[V]Bootable=\f[R],
+\f[V]Bootloader=\f[R]).
+.TP
+\f[V]Initrds=\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.
+If no initrds are specified and a bootable image is requested, mkosi
+will automatically build a default initrd.
+.TP
+\f[V]InitrdPackages=\f[R], \f[V]--initrd-package=\f[R]
+Extra packages to install into the default initrd.
+Takes a comma separated list of package specifications.
+This option may be used multiple times in which case the specified
+package lists are combined.
+.TP
+\f[V]KernelCommandLine=\f[R], \f[V]--kernel-command-line=\f[R]
+Use the specified kernel command line when building images.
+.TP
+\f[V]KernelModulesInclude=\f[R], \f[V]--kernel-modules-include=\f[R]
+Takes a list of regex patterns that specify kernel modules to include in
+the image.
+Patterns should be relative to the
+\f[V]/usr/lib/modules/<kver>/kernel\f[R] directory.
+mkosi checks for a match anywhere in the module path
+(e.g.\ \f[V]i915\f[R] will match against
+\f[V]drivers/gpu/drm/i915.ko\f[R]).
+All modules that match any of the specified patterns are included in the
+image.
+All module and firmware dependencies of the matched modules are included
+in the image as well.
+This setting takes priority over \f[V]KernelModulesExclude=\f[R] and
+only makes sense when used in combination with it because all kernel
+modules are included in the image by default.
+.TP
+\f[V]KernelModulesExclude=\f[R], \f[V]--kernel-modules-exclude=\f[R]
+Takes a list of regex patterns that specify modules to exclude from the
+image.
+Behaves the same as \f[V]KernelModulesInclude=\f[R] except that all
+modules that match any of the specified patterns are excluded from the
+image.
+.TP
+\f[V]KernelModulesIncludeHost=\f[R], \f[V]--kernel-modules-include-host=\f[R]
+Takes a boolean.
+Specifies whether to include the currently loaded modules on the host
+system in the image.
+This setting takes priority over \f[V]KernelModulesExclude=\f[R] and
+only makes sense when used in combination with it because all kernel
+modules are included in the image by default.
+.TP
+\f[V]KernelModulesInitrd=\f[R], \f[V]--kernel-modules-initrd=\f[R]
+Enable/Disable generation of the kernel modules initrd when building a
+bootable image.
+Enabled by default.
+If enabled, when building a bootable image, for each kernel that we
+assemble a unified kernel image for we generate an extra initrd
+containing only the kernel modules for that kernel version and append it
+to the prebuilt initrd.
+This allows generating kernel independent initrds which are augmented
+with the necessary kernel modules when the UKI is assembled.
+.TP
+\f[V]KernelModulesInitrdInclude=\f[R], \f[V]--kernel-modules-initrd-include=\f[R]
+Like \f[V]KernelModulesInclude=\f[R], but applies to the kernel modules
+included in the kernel modules initrd.
+.TP
+\f[V]KernelModulesInitrdExclude=\f[R], \f[V]--kernel-modules-initrd-exclude=\f[R]
+Like \f[V]KernelModulesExclude=\f[R], but applies to the kernel modules
+included in the kernel modules initrd.
+.TP
+\f[V]KernelModulesInitrdIncludeHost=\f[R], \f[V]--kernel-modules-initrd-include-host=\f[R]
+Like \f[V]KernelModulesIncludeHost=\f[R], but applies to the kernel
+modules included in the kernel modules initrd.
+.TP
+\f[V]Locale=\f[R], \f[V]--locale=\f[R], \f[V]LocaleMessages=\f[R], \f[V]--locale-messages=\f[R], \f[V]Keymap=\f[R], \f[V]--keymap=\f[R], \f[V]Timezone=\f[R], \f[V]--timezone=\f[R], \f[V]Hostname=\f[R], \f[V]--hostname=\f[R], \f[V]RootShell=\f[R], \f[V]--root-shell=\f[R]
+The settings \f[V]Locale=\f[R], \f[V]--locale=\f[R],
+\f[V]LocaleMessages=\f[R], \f[V]--locale-messages=\f[R],
+\f[V]Keymap=\f[R], \f[V]--keymap=\f[R], \f[V]Timezone=\f[R],
+\f[V]--timezone=\f[R], \f[V]Hostname=\f[R], \f[V]--hostname=\f[R],
+\f[V]RootShell=\f[R], \f[V]--root-shell=\f[R] correspond to the
+identically named systemd-firstboot options.
+See the systemd firstboot
+manpage (https://www.freedesktop.org/software/systemd/man/systemd-firstboot.html)
+for more information.
+Additionally, where applicable, the corresponding systemd credentials
+for these settings are written to \f[V]/usr/lib/credstore\f[R], so that
+they apply even if only \f[V]/usr\f[R] is shipped in the image.
+.TP
+\f[V]RootPassword=\f[R], \f[V]--root-password=\f[R],
+Set the system root password.
+If this option is not used, but a \f[V]mkosi.rootpw\f[R] file is found
+in the local directory, the password is automatically read from it.
+If the password starts with \f[V]hashed:\f[R], it is treated as an
+already hashed root password.
+The root password is also stored in \f[V]/usr/lib/credstore\f[R] under
+the appropriate systemd credential so that it applies even if only
+\f[V]/usr\f[R] is shipped in the image.
+To create an unlocked account without any password use \f[V]hashed:\f[R]
+without a hash.
+.TP
+\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/ttyS0\f[R].
+.TP
+\f[V]MakeInitrd=\f[R], \f[V]--make-initrd\f[R]
+Add \f[V]/etc/initrd-release\f[R] and \f[V]/init\f[R] to the image so
+that it can be used as an initramfs.
+.TP
+\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 SSH over VSock.
+When building with this option and running the image using
+\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.
+Run \f[V]mkosi genkey\f[R] to automatically generate an X509 certificate
+and private key to be used by mkosi to enable SSH access to any virtual
+machines via \f[V]mkosi ssh\f[R].
+To access images booted using \f[V]mkosi boot\f[R], use
+\f[V]machinectl\f[R].
+.TP
+\f[V]SELinuxRelabel=\f[R], \f[V]--selinux-relabel=\f[R]
+Specifies whether to relabel files to match the image\[cq]s SELinux
+policy.
+Takes a boolean value or \f[V]auto\f[R].
+Defaults to \f[V]auto\f[R].
+If disabled, files will not relabeled.
+If enabled, an SELinux policy has to be installed in the image and
+\f[V]setfiles\f[R] has to be available to relabel files.
+If any errors occur during \f[V]setfiles\f[R], the build will fail.
+If set to \f[V]auto\f[R], files will be relabeled if an SELinux policy
+is installed in the image and if \f[V]setfiles\f[R] is available.
+Any errors occurred during \f[V]setfiles\f[R] will be ignored.
+Note that when running unprivileged, \f[V]setfiles\f[R] will fail to set
+any labels that are not in the host\[cq]s SELinux policy.
+To ensure \f[V]setfiles\f[R] succeeds without errors, make sure to run
+mkosi as root or build from a host system with the same SELinux policy
+as the image you\[cq]re building.
+.SS [Validation] Section
+.TP
+\f[V]SecureBoot=\f[R], \f[V]--secure-boot\f[R]
+Sign systemd-boot (if it is not signed yet) and any generated unified
+kernel images for UEFI SecureBoot.
+.TP
+\f[V]SecureBootAutoEnroll=\f[R], \f[V]--secure-boot-auto-enroll=\f[R]
+Set up automatic enrollment of the secure boot keys in virtual machines
+as documented in the systemd-boot man
+page (https://www.freedesktop.org/software/systemd/man/systemd-boot.html)
+if \f[V]SecureBoot=\f[R] is used.
+Note that systemd-boot will only do automatic secure boot key enrollment
+in virtual machines starting from systemd v253.
+To do auto enrollment on systemd v252 or on bare metal machines, write a
+systemd-boot configuration file to \f[V]/efi/loader/loader.conf\f[R]
+using an extra tree with \f[V]secure-boot-enroll force\f[R] or
+\f[V]secure-boot-enroll manual\f[R] in it.
+Auto enrollment is not supported on systemd versions older than v252.
+Defaults to \f[V]yes\f[R].
+.TP
+\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[V]SecureBoot=\f[R] is used.
+.TP
+\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[V]SecureBoot=\f[R] is used.
+.TP
+\f[V]SecureBootSignTool=\f[R], \f[V]--secure-boot-sign-tool\f[R]
+Tool to use to sign secure boot PE binaries.
+Takes one of \f[V]sbsign\f[R], \f[V]pesign\f[R] or \f[V]auto\f[R].
+Defaults to \f[V]auto\f[R].
+If set to \f[V]auto\f[R], either sbsign or pesign are used if available,
+with sbsign being preferred if both are installed.
+.TP
+\f[V]VerityKey=\f[R], \f[V]--verity-key=\f[R]
+Path to the PEM file containing the secret key for signing the verity
+signature, if a verity signature partition is added with systemd-repart.
+.TP
+\f[V]VerityCertificate=\f[R], \f[V]--verity-certificate=\f[R]
+Path to the X.509 file containing the certificate for signing the verity
+signature, if a verity signature partition is added with systemd-repart.
+.TP
+\f[V]SignExpectedPcr=\f[R], \f[V]--sign-expected-pcr\f[R]
+Measure the components of the unified kernel image (UKI) using
+\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[V]auto\f[R],
+which is the default, which is equal to a true value if the
+\f[V]systemd-measure\f[R] binary is in \f[V]PATH\f[R].
+.TP
+\f[V]Passphrase=\f[R], \f[V]--passphrase\f[R]
+Specify the path to a file containing the passphrase to use for LUKS
+encryption.
+It should contain the passphrase literally, and not end in a newline
+character (i.e.\ in the same format as cryptsetup and
+\f[V]/etc/crypttab\f[R] expect the passphrase files).
+The file must have an access mode of 0600 or less.
+.TP
+\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[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[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[V]Incremental=\f[R], \f[V]--incremental=\f[R], \f[V]-i\f[R]
+Enable incremental build mode.
+In this mode, a copy of the OS image is created immediately after all OS
+packages are installed and the prepare scripts have executed but before
+the \f[V]mkosi.build\f[R] scripts are invoked (or anything that happens
+after it).
+On subsequent invocations of \f[V]mkosi\f[R] with the \f[V]-i\f[R]
+switch this cached image may be used to skip the OS package
+installation, thus drastically speeding up repetitive build times.
+Note that while there is some rudimentary cache invalidation, it is
+definitely not perfect.
+In order to force rebuilding of the cached image, combine \f[V]-i\f[R]
+with \f[V]-ff\f[R] to ensure the cached image is first removed and then
+re-created.
+.TP
+\f[V]NSpawnSettings=\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[V]systemd-nspawn\f[R] environment
+when the image is run.
+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.
+.TP
+\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[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[V]2\f[R].
+.TP
+\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[V]2G\f[R].
+.TP
+\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.
+Takes a boolean value or \f[V]auto\f[R].
+Defaults to \f[V]auto\f[R].
+.TP
+\f[V]QemuVsock=\f[R], \f[V]--qemu-vsock=\f[R]
+When used with the \f[V]qemu\f[R] verb, this option specifies whether
+QEMU should be configured with a vsock.
+Takes a boolean value or \f[V]auto\f[R].
+Defaults to \f[V]auto\f[R].
+.TP
+\f[V]QemuVsockConnectionId=\f[R], \f[V]--qemu-vsock-cid=\f[R]
+When used with the \f[V]qemu\f[R] verb, this option specifies the vsock
+connection ID to use.
+Takes a number in the interval \f[V][3, 0xFFFFFFFF)\f[R] or
+\f[V]hash\f[R] or \f[V]auto\f[R].
+Defaults to \f[V]hash\f[R].
+When set to \f[V]hash\f[R], the connection ID will be derived from the
+full path to the image.
+When set to \f[V]auto\f[R], \f[V]mkosi\f[R] will try to find a free
+connection ID automatically.
+Otherwise, the provided number will be used as is.
+Note that when set to \f[V]auto\f[R], \f[V]mkosi ssh\f[R] cannot be used
+as we cannot figure out which free connection ID we found when booting
+the image earlier.
+.TP
+\f[V]QemuSwtpm=\f[R], \f[V]--qemu-swtpm=\f[R]
+When used with the \f[V]qemu\f[R] verb, this option specifies whether to
+start an instance of swtpm to be used as a TPM with qemu.
+This requires swtpm to be installed on the host.
+Takes a boolean value or \f[V]auto\f[R].
+Defaults to \f[V]auto\f[R].
+.TP
+\f[V]QemuCdrom=\f[R], \f[V]--qemu-cdrom=\f[R]
+When used with the \f[V]qemu\f[R] verb, this option specifies whether to
+attach the image to the virtual machine as a CD-ROM device.
+Takes a boolean.
+Defaults to \f[V]no\f[R].
+.TP
+\f[V]QemuFirmware=\f[R], \f[V]--qemu-firmware=\f[R]
+When used with the \f[V]qemu\f[R] verb, this option specifies which
+firmware to use.
+Takes one of \f[V]uefi\f[R], \f[V]bios\f[R], \f[V]linux\f[R], or
+\f[V]auto\f[R].
+Defaults to \f[V]auto\f[R].
+When set to \f[V]uefi\f[R], the OVMF firmware is used.
+When set to \f[V]bios\f[R], the default SeaBIOS firmware is used.
+When set to \f[V]linux\f[R], direct kernel boot is used.
+See the \f[V]QemuKernel=\f[R] option for more details on which kernel
+image is used with direct kernel boot.
+When set to \f[V]auto\f[R], \f[V]linux\f[R] is used if a cpio image is
+being booted, \f[V]uefi\f[R] otherwise.
+.TP
+\f[V]QemuFirmwareVariables=\f[R], \f[V]--qemu-firmware-variables=\f[R]
+When used with the \f[V]qemu\f[R] verb, this option specifies the path
+to the the firmware variables file to use.
+Currently, this option is only taken into account when the
+\f[V]uefi\f[R] firmware is used.
+If not specified, mkosi will search for the default variables file and
+use that instead.
+\f[V]virt-fw-vars\f[R] from the
+virt-firmware (https://gitlab.com/kraxel/virt-firmware) project can be
+used to customize OVMF variable files.
+Some distributions also provide variable files which already have
+Microsoft\[cq]s certificates for secure boot enrolled.
+For Fedora and Debian these are \f[V]OVMF_VARS.secboot.fd\f[R] and
+\f[V]OVMF_VARS_4M.ms.fd\f[R] under \f[V]/usr/share/OVMF\f[R]
+respectively.
+You can use \f[V]locate\f[R] and look under
+\f[V]/usr/share/qemu/firmware\f[R] for hints on where to find these
+files if your distribution ships them.
+.TP
+\f[V]QemuKernel=\f[R], \f[V]--qemu-kernel=\f[R]
+Set the kernel image to use for qemu direct kernel boot.
+If not specified, mkosi will use the kernel provided via the command
+line (\f[V]-kernel\f[R] option) or latest the kernel that was installed
+into the image (or fail if no kernel was installed into the image).
+Note that when the \f[V]cpio\f[R] output format is used, direct kernel
+boot is used regardless of the configured firmware.
+Depending on the configured firmware, qemu might boot the kernel itself
+or using the configured firmware.
+.TP
+\f[V]QemuDrives=\f[R], \f[V]--qemu-drive=\f[R]
+Add a qemu drive.
+Takes a colon-delimited string of format
+\f[V]<id>:<size>[:<directory>[:<options>]]\f[R].
+\f[V]id\f[R] specifies the qemu id we assign to the drive.
+This can be used as the \f[V]drive=\f[R] property in various qemu
+devices.
+\f[V]size\f[R] specifies the size of the drive.
+This takes a size in bytes.
+Additionally, the suffixes \f[V]K\f[R], \f[V]M\f[R] and \f[V]G\f[R] can
+be used to specify a size in kilobytes, megabytes and gigabytes
+respectively.
+\f[V]directory\f[R] optionally specifies the directory in which to
+create the file backing the drive.
+\f[V]options\f[R] optionally specifies extra comma-delimited properties
+which are passed verbatime to qemu\[cq]s \f[V]-drive\f[R] option.
+.TP
+\f[V]QemuArgs=\f[R]
+Space-delimited list of additional arguments to pass when invoking qemu.
+.TP
+\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.
+Taking the temporary snapshot is more efficient on file systems that
+support reflinks natively (btrfs or xfs) than on more traditional file
+systems that do not (ext4).
+.TP
+\f[V]Credentials=\f[R], \f[V]--credential=\f[R]
+Set credentials to be passed to systemd-nspawn or qemu respectively when
+\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.
+.TP
+\f[V]ToolsTree=\f[R], \f[V]--tools-tree=\f[R]
+If specified, programs executed by mkosi are looked up inside the given
+tree instead of in the host system.
+Use this option to make image builds more reproducible by always using
+the same versions of programs to build the final image instead of
+whatever version is installed on the host system.
+If this option is not used, but the \f[V]mkosi.tools/\f[R] directory is
+found in the local directory it is automatically used for this purpose
+with the root directory as target.
+Note that when looking up binaries in \f[V]--tools-tree=\f[R], only
+\f[V]/usr/bin\f[R] and \f[V]/usr/sbin\f[R] are considered.
+Specifically, paths specified by \f[V]--extra-search-path=\f[R] are
+ignored when looking up binaries in the given tools tree.
+If set to \f[V]default\f[R], mkosi will automatically add an extra tools
+tree image and use it as the tools tree.
+The following table shows for which distributions default tools tree
+packages are defined and which packages are included in those default
+tools trees:
+.PP
+.TS
+tab(@);
+lw(24.0n) lw(7.7n) lw(7.7n) lw(7.7n) lw(7.7n) lw(5.8n) lw(9.6n).
+T{
+T}@T{
+Fedora
+T}@T{
+CentOS
+T}@T{
+Debian
+T}@T{
+Ubuntu
+T}@T{
+Arch
+T}@T{
+openSUSE
+T}
+_
+T{
+\f[V]apt\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+T}
+T{
+\f[V]archlinux-keyring\f[R]
+T}@T{
+X
+T}@T{
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+T}
+T{
+\f[V]bash\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]btrfs-progs\f[R]
+T}@T{
+X
+T}@T{
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]bubblewrap\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]ca-certificates\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]coreutils\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]cpio\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]curl\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]debian-keyring\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+T}
+T{
+\f[V]diffutils\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]distribution-gpg-keys\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+T}@T{
+T}@T{
+T}@T{
+X
+T}
+T{
+\f[V]dnf\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]dnf-plugins-core\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+T}@T{
+T}@T{
+T}@T{
+X
+T}
+T{
+\f[V]dnf5\f[R]
+T}@T{
+X
+T}@T{
+T}@T{
+T}@T{
+T}@T{
+T}@T{
+T}
+T{
+\f[V]dnf5-plugins\f[R]
+T}@T{
+X
+T}@T{
+T}@T{
+T}@T{
+T}@T{
+T}@T{
+T}
+T{
+\f[V]dosfstools\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]e2fsprogs\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]edk2-ovmf\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]erofs-utils\f[R]
+T}@T{
+X
+T}@T{
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]kmod\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]less\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]mtools\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]nano\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]openssh\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]openssl\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]pacman\f[R]
+T}@T{
+X
+T}@T{
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+T}
+T{
+\f[V]pesign\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]policycoreutils\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+T}@T{
+X
+T}
+T{
+\f[V]qemu\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]sbsigntools\f[R]
+T}@T{
+X
+T}@T{
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]socat\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]squashfs-tools\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]strace\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]swtpm\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]systemd\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]ukify\f[R]
+T}@T{
+X
+T}@T{
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]tar\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]ubuntu-keyring\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+T}
+T{
+\f[V]util-linux\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]virtiofsd\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+T}@T{
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]xfsprogs\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]xz\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]zstd\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]zypper\f[R]
+T}@T{
+X
+T}@T{
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+T}
+.TE
+.TP
+\f[V]ToolsTreeDistribution=\f[R], \f[V]--tools-tree-distribution=\f[R]
+Set the distribution to use for the default tools tree.
+By default, the same distribution as the image that\[cq]s being built is
+used, except for CentOS and Ubuntu images, in which case Fedora and
+Debian are used respectively.
+.TP
+\f[V]ToolsTreeRelease=\f[R], \f[V]--tools-tree-release=\f[R]
+Set the distribution release to use for the default tools tree.
+By default, the hardcoded default release in mkosi for the distribution
+is used.
+.TP
+\f[V]ToolsTreeMirror=\f[R], \f[V]--tools-tree-mirror=\f[R]
+Set the mirror to use for the default tools tree.
+By default, the default mirror for the tools tree distribution is used.
+.TP
+\f[V]ToolsTreePackages=\f[R], \f[V]--tools-tree-packages=\f[R]
+Extra packages to install into the default tools tree.
+Takes a comma separated list of package specifications.
+This option may be used multiple times in which case the specified
+package lists are combined.
+.TP
+\f[V]RuntimeTrees=\f[R], \f[V]--runtime-tree=\f[R]
+Takes a colon separated pair of paths.
+The first path refers to a directory to mount into any machine
+(container or VM) started by mkosi.
+The second path refers to the target directory inside the machine.
+If the second path is not provided, the directory is mounted below
+\f[V]/root/src\f[R] in the machine.
+If the second path is relative, it is interpreted relative to
+\f[V]/root/src\f[R] in the machine.
+For each mounted directory, the uid and gid of the user running mkosi
+are mapped to the root user in the machine.
+This means that all the files and directories will appear as if
+they\[cq]re owned by root in the machine, and all new files and
+directories created by root in the machine in these directories will be
+owned by the user running mkosi on the host.
+Note that when using \f[V]mkosi qemu\f[R] with this feature systemd v254
+or newer has to be installed in the image.
+.TP
+\f[V]RuntimeSize=\f[R], \f[V]--runtime-size=\f[R]
+If specified, disk images are grown to the specified size before
+they\[cq]re booted with systemd-nspawn or qemu.
+Takes a size in bytes.
+Additionally, the suffixes \f[V]K\f[R], \f[V]M\f[R] and \f[V]G\f[R] can
+be used to specify a size in kilobytes, megabytes and gigabytes
+respectively.
+.TP
+\f[V]RuntimeScratch=\f[R]: \f[V]--runtime-scratch=\f[R]
+Takes a boolean value or \f[V]auto\f[R].
+Specifies whether to mount extra scratch space to \f[V]/var/tmp\f[R].
+If enabled, practically unlimited scratch space is made available under
+\f[V]/var/tmp\f[R] when booting the image with \f[V]mkosi qemu\f[R],
+\f[V]mkosi boot\f[R] or \f[V]mkosi shell\f[R].
+Note that using this feature with \f[V]mkosi qemu\f[R] requires systemd
+v254 or newer in the guest.
+.TP
+\f[V]SshKey=\f[R], \f[V]--ssh-key=\f[R]
+Path to the X509 private key in PEM format to use to connect to a
+virtual machine started with \f[V]mkosi qemu\f[R] and built with the
+\f[V]Ssh=\f[R] option enabled via the \f[V]mkosi ssh\f[R] command.
+If not configured and \f[V]mkosi.key\f[R] exists in the working
+directory, it will automatically be used for this purpose.
+Run \f[V]mkosi genkey\f[R] to automatically generate a key in
+\f[V]mkosi.key\f[R].
+.TP
+\f[V]SshCertificate=\f[R], \f[V]--ssh-certificate=\f[R]
+Path to the X509 certificate in PEM format to provision as the SSH
+public key in virtual machines started with \f[V]mkosi qemu\f[R].
+If not configured and \f[V]mkosi.crt\f[R] exists in the working
+directory, it will automatically be used for this purpose.
+Run \f[V]mkosi genkey\f[R] to automatically generate a certificate in
+\f[V]mkosi.crt\f[R].
+.SS Specifiers
+.PP
+The current value of various settings can be accessed when parsing
+configuration files by using specifiers.
+To write a literal \f[V]%\f[R] character in a configuration file without
+treating it as a specifier, use \f[V]%%\f[R].
+The following specifiers are understood:
+.PP
+.TS
+tab(@);
+l l.
+T{
+Setting
+T}@T{
+Specifier
+T}
+_
+T{
+\f[V]Distribution=\f[R]
+T}@T{
+\f[V]%d\f[R]
+T}
+T{
+\f[V]Release=\f[R]
+T}@T{
+\f[V]%r\f[R]
+T}
+T{
+\f[V]Architecture=\f[R]
+T}@T{
+\f[V]%a\f[R]
+T}
+T{
+\f[V]Format=\f[R]
+T}@T{
+\f[V]%t\f[R]
+T}
+T{
+\f[V]Output=\f[R]
+T}@T{
+\f[V]%o\f[R]
+T}
+T{
+\f[V]OutputDirectory=\f[R]
+T}@T{
+\f[V]%O\f[R]
+T}
+T{
+\f[V]ImageId=\f[R]
+T}@T{
+\f[V]%i\f[R]
+T}
+T{
+\f[V]ImageVersion=\f[R]
+T}@T{
+\f[V]%v\f[R]
+T}
+.TE
+.SS Supported distributions
+.PP
+Images may be created containing installations of the following
+distributions:
+.IP \[bu] 2
+\f[I]Fedora Linux\f[R]
+.IP \[bu] 2
+\f[I]Debian\f[R]
+.IP \[bu] 2
+\f[I]Ubuntu\f[R]
+.IP \[bu] 2
+\f[I]Arch Linux\f[R]
+.IP \[bu] 2
+\f[I]openSUSE\f[R]
+.IP \[bu] 2
+\f[I]Mageia\f[R]
+.IP \[bu] 2
+\f[I]CentOS\f[R]
+.IP \[bu] 2
+\f[I]RHEL\f[R]
+.IP \[bu] 2
+\f[I]RHEL UBI\f[R]
+.IP \[bu] 2
+\f[I]OpenMandriva\f[R]
+.IP \[bu] 2
+\f[I]Rocky Linux\f[R]
+.IP \[bu] 2
+\f[I]Alma Linux\f[R]
+.IP \[bu] 2
+\f[I]Gentoo\f[R] (\f[B]Gentoo is experimental and unsupported.
+We make no guarantee that it will work at all and the core maintainers
+will generally not fix gentoo specific issues\f[R])
+.IP \[bu] 2
+\f[I]None\f[R] (\f[B]Requires the user to provide a pre-built
+rootfs\f[R])
+.PP
+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[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 images
+for any of the rpm-based distributions.
+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[V]zypper\f[R] may be used to build
+\f[I]openSUSE\f[R] images.
+Other distributions and build automation tools for embedded Linux
+systems such as Buildroot, OpenEmbedded and Yocto Project may be used by
+selecting the \f[V]custom\f[R] distribution, and populating the rootfs
+via a combination of base trees, skeleton trees, and prepare scripts.
+.PP
+Currently, \f[I]Fedora Linux\f[R] packages all relevant tools as of
+Fedora 28.
+.PP
+Note that when not using a custom mirror, \f[V]RHEL\f[R] images can only
+be built from a host system with a \f[V]RHEL\f[R] subscription
+(established using e.g.\ \f[V]subscription-manager\f[R]).
+.SH Execution Flow
+.PP
+Execution flow for \f[V]mkosi build\f[R].
+Default values/calls are shown in parentheses.
+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 "1." 3
+Parse CLI options
+.IP "2." 3
+Parse configuration files
+.IP "3." 3
+If we\[cq]re not running as root, unshare the user namespace and map the
+subuid range configured in \f[V]/etc/subuid\f[R] and
+\f[V]/etc/subgid\f[R] into it.
+.IP "4." 3
+Unshare the mount namespace
+.IP "5." 3
+Remount the following directories read-only if they exist:
+.RS 4
+.IP \[bu] 2
+\f[V]/usr\f[R]
+.IP \[bu] 2
+\f[V]/etc\f[R]
+.IP \[bu] 2
+\f[V]/opt\f[R]
+.IP \[bu] 2
+\f[V]/srv\f[R]
+.IP \[bu] 2
+\f[V]/boot\f[R]
+.IP \[bu] 2
+\f[V]/efi\f[R]
+.IP \[bu] 2
+\f[V]/media\f[R]
+.IP \[bu] 2
+\f[V]/mnt\f[R]
+.RE
+.PP
+Then, for each image, we execute the following steps:
+.IP " 1." 4
+Copy package manager trees into the workspace
+.IP " 2." 4
+Copy base trees (\f[V]--base-tree=\f[R]) into the image
+.IP " 3." 4
+Copy skeleton trees (\f[V]mkosi.skeleton\f[R]) into image
+.IP " 4." 4
+Install distribution and packages into image or use cache tree if
+available
+.IP " 5." 4
+Run prepare scripts on image with the \f[V]final\f[R] argument
+(\f[V]mkosi.prepare\f[R])
+.IP " 6." 4
+Install build packages in overlay if any build scripts are configured
+.IP " 7." 4
+Run prepare scripts on overlay with the \f[V]build\f[R] argument if any
+build scripts are configured (\f[V]mkosi.prepare\f[R])
+.IP " 8." 4
+Cache the image if configured (\f[V]--incremental\f[R])
+.IP " 9." 4
+Run build scripts on image + overlay if any build scripts are configured
+(\f[V]mkosi.build\f[R])
+.IP "10." 4
+Finalize the build if the output format \f[V]none\f[R] is configured
+.IP "11." 4
+Copy the build scripts outputs into the image
+.IP "12." 4
+Copy the extra trees into the image (\f[V]mkosi.extra\f[R])
+.IP "13." 4
+Run post-install scripts (\f[V]mkosi.postinst\f[R])
+.IP "14." 4
+Write config files required for \f[V]Ssh=\f[R], \f[V]Autologin=\f[R] and
+\f[V]MakeInitrd=\f[R]
+.IP "15." 4
+Install systemd-boot and configure secure boot if configured
+(\f[V]--secure-boot\f[R])
+.IP "16." 4
+Run \f[V]systemd-sysusers\f[R]
+.IP "17." 4
+Run \f[V]systemd-tmpfiles\f[R]
+.IP "18." 4
+Run \f[V]systemctl preset-all\f[R]
+.IP "19." 4
+Run \f[V]depmod\f[R]
+.IP "20." 4
+Run \f[V]systemd-firstboot\f[R]
+.IP "21." 4
+Run \f[V]systemd-hwdb\f[R]
+.IP "22." 4
+Remove packages and files (\f[V]RemovePackages=\f[R],
+\f[V]RemoveFiles=\f[R])
+.IP "23." 4
+Run SELinux relabel is a SELinux policy is installed
+.IP "24." 4
+Run finalize scripts (\f[V]mkosi.finalize\f[R])
+.IP "25." 4
+Generate unified kernel image if configured to do so
+.IP "26." 4
+Generate final output format
+.SH Scripts
+.PP
+To allow for image customization that cannot be implemented using
+mkosi\[cq]s builtin features, mkosi supports running scripts at various
+points during the image build process that can customize the image as
+needed.
+Scripts are executed on the host system as root (either real root or
+root within the user namespace that mkosi created when running
+unprivileged) with a customized environment to simplify modifying the
+image.
+For each script, the configured build sources (\f[V]BuildSources=\f[R])
+are mounted into the current working directory before running the script
+in the current working directory.
+\f[V]$SRCDIR\f[R] is set to point to the current working directory.
+The following scripts are supported:
+.IP \[bu] 2
+If \f[B]\f[VB]mkosi.prepare\f[B]\f[R] (\f[V]PrepareScripts=\f[R])
+exists, it is first called with the \f[V]final\f[R] argument, right
+after the software packages are installed.
+It is called a second time with the \f[V]build\f[R] command line
+parameter, right after the build packages are installed and the build
+overlay mounted on top of the image\[cq]s root directory .
+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[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).
+In contrast to a general purpose installation, it is safe to install
+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
+If \f[B]\f[VB]mkosi.build\f[B]\f[R] (\f[V]BuildScripts=\f[R]) exists, it
+is executed with the build overlay mounted on top of the image\[cq]s
+root directory.
+When running the build script, \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 image.
+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 running the build script, the contents of \f[V]$DESTDIR\f[R] are
+copied into the image.
+.IP \[bu] 2
+If \f[B]\f[VB]mkosi.postinst\f[B]\f[R]
+(\f[V]PostInstallationScripts=\f[R]) exists, it is executed after the
+(optional) build tree and extra trees have been installed.
+This script may be used to alter the images without any restrictions,
+after all software packages and built sources have been installed.
+.IP \[bu] 2
+If \f[B]\f[VB]mkosi.finalize\f[B]\f[R] (\f[V]FinalizeScripts=\f[R])
+exists, it is executed as the last step of preparing an image.
+.PP
+If a script uses the \f[V].chroot\f[R] extension, mkosi will chroot into
+the image using \f[V]mkosi-chroot\f[R] (see below) before executing the
+script.
+For example, if \f[V]mkosi.postinst.chroot\f[R] exists, mkosi will
+chroot into the image and execute it as the post-installation script.
+.PP
+Scripts executed by mkosi receive the following environment variables:
+.IP \[bu] 2
+\f[V]$ARCHITECTURE\f[R] contains the architecture from the
+\f[V]Architecture=\f[R] setting.
+If \f[V]Architecture=\f[R] is not set, it will contain the native
+architecture of the host machine.
+See the documentation of \f[V]Architecture=\f[R] for possible values for
+this variable.
+.IP \[bu] 2
+\f[V]$CHROOT_SCRIPT\f[R] contains the path to the running script
+relative to the image root directory.
+The primary usecase for this variable is in combination with the
+\f[V]mkosi-chroot\f[R] script.
+See the description of \f[V]mkosi-chroot\f[R] below for more
+information.
+.IP \[bu] 2
+\f[V]$SRCDIR\f[R] contains the path to the directory mkosi was invoked
+from, with any configured build sources mounted on top.
+\f[V]$CHROOT_SRCDIR\f[R] contains the value that \f[V]$SRCDIR\f[R] will
+have after invoking \f[V]mkosi-chroot\f[R].
+.IP \[bu] 2
+\f[V]$BUILDDIR\f[R] is only defined if \f[V]mkosi.builddir\f[R] exists
+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.
+\f[V]$CHROOT_BUILDDIR\f[R] contains the value that \f[V]$BUILDDIR\f[R]
+will have after invoking \f[V]mkosi-chroot\f[R].
+.IP \[bu] 2
+\f[V]$DESTDIR\f[R] is a directory into which any installed software
+generated by a build script may be placed.
+This variable is only set when executing a build script.
+\f[V]$CHROOT_DESTDIR\f[R] contains the value that \f[V]$DESTDIR\f[R]
+will have after invoking \f[V]mkosi-chroot\f[R].
+.IP \[bu] 2
+\f[V]$OUTPUTDIR\f[R] points to the staging directory used to store build
+artifacts generated during the build.
+\f[V]$CHROOT_OUTPUTDIR\f[R] contains the value that \f[V]$OUTPUTDIR\f[R]
+will have after invoking \f[V]mkosi-chroot\f[R].
+.IP \[bu] 2
+\f[V]$PACKAGEDIR\f[R] points to the directory containing the local
+package repository.
+Build scripts can add more packages to the local repository by writing
+the packages to \f[V]$PACKAGEDIR\f[R].
+.IP \[bu] 2
+\f[V]$BUILDROOT\f[R] is the root directory of the image being built,
+optionally with the build overlay mounted on top depending on the script
+that\[cq]s being executed.
+.IP \[bu] 2
+\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[V]WithDocs=yes\f[R]).
+A build script should suppress installation of any package 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[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[V]WithTests=no\f[R]).
+A build script should avoid running any unit or integration tests in
+case \f[V]$WITH_TESTS\f[R] is \f[V]0\f[R].
+.IP \[bu] 2
+\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[V]WithNetwork=no\f[R]).
+A build script should avoid any network communication in case
+\f[V]$WITH_NETWORK\f[R] is \f[V]0\f[R].
+.IP \[bu] 2
+\f[V]$SOURCE_DATE_EPOCH\f[R] is defined if requested
+(\f[V]SourceDateEpoch=TIMESTAMP\f[R],
+\f[V]Environment=SOURCE_DATE_EPOCH=TIMESTAMP\f[R] or the host
+environment variable \f[V]$SOURCE_DATE_EPOCH\f[R]).
+This is useful to make builds reproducible.
+See
+SOURCE_DATE_EPOCH (https://reproducible-builds.org/specs/source-date-epoch/)
+for more information.
+.IP \[bu] 2
+\f[V]$MKOSI_UID\f[R] and \f[V]$MKOSI_GID\f[R] are the respectively the
+uid, gid of the user that invoked mkosi, potentially translated to a uid
+in the user namespace that mkosi is running in.
+These can be used in combination with \f[V]setpriv\f[R] to run commands
+as the user that invoked mkosi (e.g.
+\f[V]setpriv --reuid=$MKOSI_UID --regid=$MKOSI_GID --clear-groups <command>\f[R])
+.PP
+Consult this table for which script receives which environment
+variables:
+.PP
+.TS
+tab(@);
+lw(16.5n) lw(13.4n) lw(11.8n) lw(14.2n) lw(14.2n).
+T{
+Variable
+T}@T{
+\f[V]mkosi.prepare\f[R]
+T}@T{
+\f[V]mkosi.build\f[R]
+T}@T{
+\f[V]mkosi.postinst\f[R]
+T}@T{
+\f[V]mkosi.finalize\f[R]
+T}
+_
+T{
+\f[V]$CHROOT_SCRIPT\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]$SRCDIR\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]CHROOT_SRCDIR\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]$BUILDDIR\f[R]
+T}@T{
+T}@T{
+X
+T}@T{
+T}@T{
+T}
+T{
+\f[V]CHROOT_BUILDDIR\f[R]
+T}@T{
+T}@T{
+X
+T}@T{
+T}@T{
+T}
+T{
+\f[V]DESTDIR\f[R]
+T}@T{
+T}@T{
+X
+T}@T{
+T}@T{
+T}
+T{
+\f[V]CHROOT_DESTDIR\f[R]
+T}@T{
+T}@T{
+X
+T}@T{
+T}@T{
+T}
+T{
+\f[V]$OUTPUTDIR\f[R]
+T}@T{
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]CHROOT_OUTPUTDIR\f[R]
+T}@T{
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]$BUILDROOT\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]WITH_DOCS\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+T}@T{
+T}
+T{
+\f[V]WITH_TESTS\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+T}@T{
+T}
+T{
+\f[V]WITH_NETWORK\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+T}@T{
+T}
+T{
+\f[V]SOURCE_DATE_EPOCH\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]MKOSI_UID\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]MKOSI_GID\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+.TE
+.PP
+Additionally, when a script is executed, a few scripts are made
+available via \f[V]$PATH\f[R] to simplify common usecases.
+.IP \[bu] 2
+\f[V]mkosi-chroot\f[R]: This script will chroot into the image and
+execute the given command.
+On top of chrooting into the image, it will also mount various files and
+directories (\f[V]$SRCDIR\f[R], \f[V]$DESTDIR\f[R], \f[V]$BUILDDIR\f[R],
+\f[V]$OUTPUTDIR\f[R], \f[V]$CHROOT_SCRIPT\f[R]) into the image and
+modify the corresponding environment variables to point to the locations
+inside the image.
+It will also mount APIVFS filesystems (\f[V]/proc\f[R], \f[V]/dev\f[R],
+\&...)
+to make sure scripts and tools executed inside the chroot work properly.
+It also propagates \f[V]/etc/resolv.conf\f[R] from the host into the
+chroot if requested so that DNS resolution works inside the chroot.
+After the mkosi-chroot command exits, various mount points are cleaned
+up.
+.RS 2
+.PP
+For example, to invoke \f[V]ls\f[R] inside of the image, use the
+following
+.IP
+.nf
+\f[C]
+mkosi-chroot ls ...
+\f[R]
+.fi
+.PP
+To execute the entire script inside the image, add a \[lq].chroot\[rq]
+suffix to the name (\f[V]mkosi.build.chroot\f[R] instead of
+\f[V]mkosi.build\f[R], etc.).
+.RE
+.IP \[bu] 2
+For all of the supported package managers except portage (\f[V]dnf\f[R],
+\f[V]rpm\f[R], \f[V]apt\f[R], \f[V]pacman\f[R], \f[V]zypper\f[R]),
+scripts of the same name are put into \f[V]$PATH\f[R] that make sure
+these commands operate on the image\[cq]s root directory with the
+configuration supplied by the user instead of on the host system.
+This means that from a script, you can do
+e.g.\ \f[V]dnf   install vim\f[R] to install vim into the image.
+.IP \[bu] 2
+\f[V]mkosi-as-caller\f[R]: This script uses \f[V]setpriv\f[R] to switch
+from the user \f[V]root\f[R] in the user namespace used for various
+build steps back to the original user that called mkosi.
+This is useful when we want to invoke build steps which will write to
+\f[V]$BUILDDIR\f[R] and we want to have the files owned by the calling
+user.
+.RS 2
+.PP
+For example, a complete \f[V]mkosi.build\f[R] script might be the
+following:
+.IP
+.nf
+\f[C]
+set -ex
+
+mkosi-as-caller meson setup \[dq]$BUILDDIR/build\[dq] \[dq]$SRCDIR\[dq]
+mkosi-as-caller meson compile -C \[dq]$BUILDDIR/build\[dq]
+meson install -C \[dq]$BUILDDIR/build\[dq] --no-rebuild
+\f[R]
+.fi
+.RE
+.IP \[bu] 2
+\f[V]git\f[R] is automatically invoked with \f[V]safe.directory=*\f[R]
+to avoid permissions errors when running as the root user in a user
+namespace.
+.IP \[bu] 2
+\f[V]useradd\f[R] and \f[V]groupadd\f[R] are automatically invoked with
+\f[V]--root=$BUILDROOT\f[R] when executed outside of the image.
+.PP
+When scripts are executed, any directories that are still writable are
+also made read-only (\f[V]/home\f[R], \f[V]/var\f[R], \f[V]/root\f[R],
+\&...)
+and only the minimal set of directories that need to be writable remain
+writable.
+This is to ensure that scripts can\[cq]t mess with the host system when
+mkosi is running as root.
+.PP
+Note that when executing scripts, all source directories are made
+ephemeral which means all changes made to source directories while
+running scripts are thrown away after the scripts finish executing.
+Use the output, build or cache directories if you need to persist data
+between builds.
+.SH Files
+.PP
+To make it easy to build images for development versions of your
+projects, mkosi can read configuration data from the local directory,
+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[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.
+This allows creation of files that need to be provided early, for
+example to configure the package manager or set systemd presets.
+.RS 2
+.PP
+When using the directory, file ownership is not preserved: all files
+copied will be owned by root.
+To preserve ownership, use a tar archive.
+.RE
+.IP \[bu] 2
+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[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
+When using the directory, file ownership is not preserved: all files
+copied will be owned by root.
+To preserve ownership, use a tar archive.
+.RE
+.IP \[bu] 2
+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[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[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[V]mkosi.build\f[R] scripts support it.
+Specifically, this directory will be mounted into the build container,
+and the \f[V]$BUILDDIR\f[R] environment variable will be set to it when
+the build scripts are invoked.
+A 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[V]mkosi\f[R]
+is used in incremental mode (\f[V]-i\f[R]): not only the image and build
+overlay, but also the build tree is reused between subsequent
+invocations.
+Note that if this directory does not exist the \f[V]$BUILDDIR\f[R]
+environment variable is not set, and it is up to the build scripts 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[VB]mkosi.rootpw\f[B]\f[R] file can be used to provide the
+password for the root user of the image.
+If the password is prefixed with \f[V]hashed:\f[R] it is treated as an
+already hashed root password.
+The password may optionally be followed by a newline character which is
+implicitly removed.
+The file must have an access mode of 0600 or less.
+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[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[V]/etc/crypttab\f[R] expect the passphrase files).
+The file must have an access mode of 0600 or less.
+.IP \[bu] 2
+The \f[B]\f[VB]mkosi.crt\f[B]\f[R] and \f[B]\f[VB]mkosi.key\f[B]\f[R]
+files contain an X.509 certificate and PEM private key to use when
+signing is required (UEFI SecureBoot, verity, \&...).
+.IP \[bu] 2
+The \f[B]\f[VB]mkosi.output/\f[B]\f[R] directory is used to store all
+build artifacts.
+.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].
+.IP \[bu] 2
+The \f[B]\f[VB]mkosi.repart/\f[B]\f[R] directory is used as the source
+for systemd-repart partition definition files which are passed to
+systemd-repart when building a disk image.
+If it does not exist and the \f[V]RepartDirectories=\f[R] setting is not
+configured, mkosi will default to the following partition definition
+files:
+.RS 2
+.PP
+\f[V]00-esp.conf\f[R] (if we\[cq]re building a bootable image):
+.IP
+.nf
+\f[C]
+[Partition]
+Type=esp
+Format=vfat
+CopyFiles=/boot:/
+CopyFiles=/efi:/
+SizeMinBytes=512M
+SizeMaxBytes=512M
+\f[R]
+.fi
+.PP
+\f[V]05-bios.conf\f[R] (if we\[cq]re building a BIOS bootable image):
+.IP
+.nf
+\f[C]
+[Partition]
+# UUID of the grub BIOS boot partition which grubs needs on GPT to
+# embed itself into.
+Type=21686148-6449-6e6f-744e-656564454649
+SizeMinBytes=1M
+SizeMaxBytes=1M
+\f[R]
+.fi
+.PP
+\f[V]10-root.conf\f[R]:
+.IP
+.nf
+\f[C]
+[Partition]
+Type=root
+Format=<distribution-default-filesystem>
+CopyFiles=/
+Minimize=guess
+\f[R]
+.fi
+.PP
+Note that if either \f[V]mkosi.repart/\f[R] is found or
+\f[V]RepartDirectories=\f[R] is used, we will not use any of the default
+partition definitions.
+.RE
+.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[V]mkosi.conf\f[R], in case the default settings are not acceptable
+for a project.
+.SH CACHING
+.PP
+\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[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.
+.IP "2." 3
+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[V]-f\f[R] switch.
+.IP "3." 3
+Finally, between multiple builds the build artifact directory may be
+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 a \f[V]mkosi.build\f[R] build script.
+.PP
+The package cache and incremental mode are unconditionally useful.
+The final cache 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.
+.SH Building multiple images
+.PP
+If the \f[V]mkosi.images/\f[R] directory exists, mkosi will load
+individual image configurations from it and build each of them.
+Image configurations can be either directories containing mkosi
+configuration files or regular files with the \f[V].conf\f[R] extension.
+.PP
+When image configurations are found in \f[V]mkosi.images/\f[R], mkosi
+will build the configured images and all of their dependencies (or all
+of them if no images were explicitly configured using
+\f[V]Images=\f[R]).
+To add dependencies between images, the \f[V]Dependencies=\f[R] setting
+can be used.
+.PP
+When images are defined, mkosi will first read the global configuration
+(configuration outside of the \f[V]mkosi.images/\f[R] directory),
+followed by the image specific configuration.
+This means that global configuration takes precedence over image
+specific configuration.
+.PP
+Images can refer to outputs of images they depend on.
+Specifically, for the following options, mkosi will only check whether
+the inputs exist just before building the image:
+.IP \[bu] 2
+\f[V]BaseTrees=\f[R]
+.IP \[bu] 2
+\f[V]PackageManagerTrees=\f[R]
+.IP \[bu] 2
+\f[V]SkeletonTrees=\f[R]
+.IP \[bu] 2
+\f[V]ExtraTrees=\f[R]
+.IP \[bu] 2
+\f[V]ToolsTree=\f[R]
+.IP \[bu] 2
+\f[V]Initrds=\f[R]
+.PP
+To refer to outputs of a image\[cq]s dependencies, simply configure any
+of these options with a relative path to the output to use in the output
+directory of the dependency.
+Or use the \f[V]%O\f[R] specifier to refer to the output directory.
+.PP
+A good example on how to build multiple images can be found in the
+systemd (https://github.com/systemd/systemd/tree/main/mkosi.images)
+repository.
+.SH ENVIRONMENT VARIABLES
+.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.
+.IP \[bu] 2
+\f[V]$MKOSI_DNF\f[R] can be used to override the executable used as
+\f[V]dnf\f[R].
+This is particularly useful to select between \f[V]dnf\f[R] and
+\f[V]dnf5\f[R].
+.SH EXAMPLES
+.PP
+Create and run a raw \f[I]GPT\f[R] image with \f[I]ext4\f[R], as
+\f[V]image.raw\f[R]:
+.IP
+.nf
+\f[C]
+# mkosi -p systemd --incremental boot
+\f[R]
+.fi
+.PP
+Create and run a bootable \f[I]GPT\f[R] image, as \f[V]foobar.raw\f[R]:
+.IP
+.nf
+\f[C]
+$ mkosi -d fedora -p kernel-core -p systemd -p systemd-boot -p udev -o foobar.raw
+# mkosi --output foobar.raw boot
+$ mkosi --output foobar.raw qemu
+\f[R]
+.fi
+.PP
+Create and run a \f[I]Fedora Linux\f[R] image in a plain directory:
+.IP
+.nf
+\f[C]
+# mkosi --distribution fedora --format directory boot
+\f[R]
+.fi
+.PP
+Create a compressed image \f[V]image.raw.xz\f[R] with \f[I]SSH\f[R]
+installed and add a checksum file:
+.IP
+.nf
+\f[C]
+$ mkosi --distribution fedora --format disk --checksum --compress-output --package=openssh-clients
+\f[R]
+.fi
+.PP
+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
+.nf
+\f[C]
+$ cat >mkosi.conf <<EOF
+[Distribution]
+Distribution=fedora
+
+[Output]
+Format=disk
+
+[Content]
+Packages=kernel,systemd,systemd-udev,openssh-clients,httpd
+BuildPackages=make,gcc,libcurl-devel
+EOF
+$ cat >mkosi.build <<EOF
+#!/bin/sh
+
+if [ \[dq]$container\[dq] != \[dq]mkosi\[dq] ]; then
+    exec mkosi-chroot \[dq]$CHROOT_SCRIPT\[dq] \[dq]$\[at]\[dq]
+fi
+
+cd $SRCDIR
+\&./autogen.sh
+\&./configure --prefix=/usr
+make -j \[ga]nproc\[ga]
+make install
+EOF
+$ chmod +x mkosi.build
+# mkosi --incremental boot
+# systemd-nspawn -bi image.raw
+\f[R]
+.fi
+.SS Different ways to boot with \f[V]qemu\f[R]
+.PP
+The easiest way to boot a virtual machine is to build an image with the
+required components and let \f[V]mkosi\f[R] call \f[V]qemu\f[R] with all
+the right options:
+.IP
+.nf
+\f[C]
+$ mkosi -d fedora \[rs]
+    --autologin \[rs]
+    -p systemd-udev,systemd-boot,kernel-core \[rs]
+    build
+$ mkosi -d fedora qemu
+\&...
+fedora login: root (automatic login)
+[root\[at]fedora \[ti]]#
+\f[R]
+.fi
+.PP
+The default is to boot with a text console only.
+In this mode, messages from the boot loader, the kernel, and systemd,
+and later the getty login prompt and shell all use the same terminal.
+It is possible to switch between the qemu console and monitor by
+pressing \f[V]Ctrl-a c\f[R].
+The qemu monitor may for example be used to inject special keys or shut
+down the machine quickly.
+.PP
+To boot with a graphical window, add \f[V]--qemu-qui\f[R]:
+.IP
+.nf
+\f[C]
+$ mkosi -d fedora --qemu-gui qemu
+\f[R]
+.fi
+.PP
+A kernel may be booted directly with
+\f[V]mkosi qemu -kernel ... -initrd ... -append \[aq]...\[aq]\f[R].
+This is a bit faster because no boot loader is used, and it is also
+easier to experiment with different kernels and kernel commandlines.
+Note that despite the name, qemu\[cq]s \f[V]-append\f[R] option replaces
+the default kernel commandline embedded in the kernel and any previous
+\f[V]-append\f[R] specifications.
+.PP
+The UKI is also copied into the output directory and may be booted
+directly:
+.IP
+.nf
+\f[C]
+$ mkosi qemu -kernel mkosi.output/fedora\[ti]38/image.efi
+\f[R]
+.fi
+.PP
+When booting using an external kernel, we don\[cq]t need the kernel
+\f[I]in\f[R] the image, but we would still want the kernel modules to be
+installed.
+.PP
+It is also possible to do a \f[I]direct kernel boot\f[R] into a boot
+loader, taking advantage of the fact that \f[V]systemd-boot(7)\f[R] is a
+valid UEFI binary:
+.IP
+.nf
+\f[C]
+$ mkosi qemu -kernel /usr/lib/systemd/boot/efi/systemd-bootx64.efi
+\f[R]
+.fi
+.PP
+In this scenario, the kernel is loaded from the ESP in the image by
+\f[V]systemd-boot\f[R].
+.SH REQUIREMENTS
+.PP
+mkosi is packaged for various distributions: Debian, Ubuntu, Arch Linux,
+Fedora Linux, OpenMandriva, Gentoo.
+Note that it has been a while since the last release and the packages
+shipped by distributions are very out of date.
+We currently recommend running mkosi from git until a new release
+happens.
+.PP
+mkosi currently requires systemd 254 to build bootable disk images.
+.PP
+When not using distribution packages make sure to install the necessary
+dependencies.
+For example, on \f[I]Fedora Linux\f[R] you need:
+.IP
+.nf
+\f[C]
+# dnf install bubblewrap btrfs-progs apt dosfstools mtools edk2-ovmf e2fsprogs squashfs-tools gnupg python3 tar xfsprogs xz zypper sbsigntools
+\f[R]
+.fi
+.PP
+On Debian/Ubuntu it might be necessary to install the
+\f[V]ubuntu-keyring\f[R], \f[V]ubuntu-archive-keyring\f[R] and/or
+\f[V]debian-archive-keyring\f[R] packages explicitly, in addition to
+\f[V]apt\f[R], depending on what kind of distribution images you want to
+build.
+.PP
+Note that the minimum required Python version is 3.9.
+.SH Frequently Asked Questions (FAQ)
+.IP \[bu] 2
+Why does \f[V]mkosi qemu\f[R] with KVM not work on Debian/Ubuntu?
+.PP
+While other distributions are OK with allowing access to
+\f[V]/dev/kvm\f[R], on Debian/Ubuntu this is only allowed for users in
+the \f[V]kvm\f[R] group.
+Because mkosi unshares a user namespace when running unprivileged, even
+if the calling user was in the kvm group, when mkosi unshares the user
+namespace to run unprivileged, it loses access to the \f[V]kvm\f[R]
+group and by the time we start \f[V]qemu\f[R] we don\[cq]t have access
+to \f[V]/dev/kvm\f[R] anymore.
+As a workaround, you can change the permissions of the device nodes to
+\f[V]0666\f[R] which is sufficient to make KVM work unprivileged.
+To persist these settings across reboots, copy
+\f[V]/usr/lib/tmpfiles.d/static-nodes-permissions.conf\f[R] to
+\f[V]/etc/tmpfiles.d/static-nodes-permissions.conf\f[R] and change the
+mode of \f[V]/dev/kvm\f[R] from \f[V]0660\f[R] to \f[V]0666\f[R].
+.SH REFERENCES
+.IP \[bu] 2
+Primary mkosi git repository on
+GitHub (https://github.com/systemd/mkosi/)
+.IP \[bu] 2
+mkosi \[em] A Tool for Generating OS
+Images (https://0pointer.net/blog/mkosi-a-tool-for-generating-os-images.html)
+introductory blog post by Lennart Poettering
+.IP \[bu] 2
+The mkosi OS generation tool (https://lwn.net/Articles/726655/) story on
+LWN
+.SH SEE ALSO
+.PP
+\f[V]systemd-nspawn(1)\f[R], \f[V]dnf(8)\f[R]