Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 1852 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man1/mkosi.1 b/upstream/mageia-cauldron/man1/mkosi.1
new file mode 100644
index 00000000..e32d7ccb
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/mkosi.1
@@ -0,0 +1,1852 @@
+.\" Automatically generated by Pandoc 2.14.0.3
+.\"
+.TH "mkosi" "1" "2016-" "" ""
+.hy
+.SH NAME
+.PP
+mkosi \[em] Build Bespoke OS Images
+.SH SYNOPSIS
+.PP
+\f[C]mkosi [options\&...] build\f[R]
+.PP
+\f[C]mkosi [options\&...] clean\f[R]
+.PP
+\f[C]mkosi [options\&...] summary\f[R]
+.PP
+\f[C]mkosi [options\&...] shell [command line\&...]\f[R]
+.PP
+\f[C]mkosi [options\&...] boot [nspawn settings\&...]\f[R]
+.PP
+\f[C]mkosi [options\&...] qemu\f[R]
+.PP
+\f[C]mkosi [options\&...] ssh\f[R]
+.PP
+\f[C]mkosi [options\&...] serve\f[R]
+.PP
+\f[C]mkosi [options\&...] bump\f[R]
+.PP
+\f[C]mkosi [options\&...] genkey\f[R]
+.PP
+\f[C]mkosi [options\&...] help\f[R]
+.SH DESCRIPTION
+.PP
+\f[C]mkosi\f[R] is a tool for easily building customized OS images.
+It\[cq]s a fancy wrapper around \f[C]dnf --installroot\f[R],
+\f[C]debootstrap\f[R], \f[C]pacstrap\f[R] and \f[C]zypper\f[R] that may
+generate disk images with a number of bells and whistles.
+.SS Command Line Verbs
+.PP
+The following command line verbs are known:
+.TP
+\f[B]\f[CB]build\f[B]\f[R]
+This builds the image, based on the settings passed in on the command
+line or read from a \f[C]mkosi.default\f[R] file.
+This verb is the default if no verb is explicitly specified.
+This command must be executed as \f[C]root\f[R].
+Any arguments passed after \f[C]build\f[R] are passed as arguments to
+the build script (if there is one).
+.TP
+\f[B]\f[CB]clean\f[B]\f[R]
+Remove build artifacts generated on a previous build.
+If combined with \f[C]-f\f[R], also removes incremental build cache
+images.
+If \f[C]-f\f[R] is specified twice, also removes any package cache.
+.TP
+\f[B]\f[CB]summary\f[B]\f[R]
+Outputs a human-readable summary of all options used for building an
+image.
+This will parse the command line and \f[C]mkosi.default\f[R] file as it
+would do on \f[C]build\f[R], but only output what it is configured for
+and not actually build anything.\[ga]
+.TP
+\f[B]\f[CB]shell\f[B]\f[R]
+This builds the image if it is not built yet, and then invokes
+\f[C]systemd-nspawn\f[R] to acquire an interactive shell prompt in it.
+If this verb is used an optional command line may be specified which is
+then invoked in place of the shell in the container.
+Combine this with \f[C]-f\f[R] in order to rebuild the image
+unconditionally before acquiring the shell, see below.
+This command must be executed as \f[C]root\f[R].
+.TP
+\f[B]\f[CB]boot\f[B]\f[R]
+Similar to \f[C]shell\f[R] but boots the image up using
+\f[C]systemd-nspawn\f[R].
+If this verb is used an optional command line may be specified which is
+passed as \[lq]kernel command line\[rq] to the init system in the image.
+.TP
+\f[B]\f[CB]qemu\f[B]\f[R]
+Similar to \f[C]boot\f[R] but uses \f[C]qemu\f[R] to boot up the image,
+i.e.\ instead of container virtualization VM virtualization is used.
+This verb is only supported on images that contain a boot loader,
+i.e.\ those built with \f[C]Bootable=yes\f[R] (see below).
+This command must be executed as \f[C]root\f[R] unless the image already
+exists and \f[C]-f\f[R] is not specified.
+.TP
+\f[B]\f[CB]ssh\f[B]\f[R]
+When the image is built with the \f[C]Ssh=yes\f[R] option, this command
+connects to a booted (\f[C]boot\f[R], \f[C]qemu\f[R] verbs) container/VM
+via SSH.
+Make sure to run \f[C]mkosi ssh\f[R] with the same config as
+\f[C]mkosi build\f[R] was run with so that it has the necessary
+information available to connect to the running container/VM via SSH.
+.TP
+\f[B]\f[CB]serve\f[B]\f[R]
+This builds the image if it is not built yet, and then serves the output
+directory (i.e.\ usually \f[C]mkosi.output/\f[R], see below) via a small
+embedded HTTP server, listening on port 8081.
+Combine with \f[C]-f\f[R] in order to rebuild the image unconditionally
+before serving it.
+This command is useful for testing network based acquisition of OS
+images, for example via \f[C]machinectl pull-raw \&...\f[R] and
+\f[C]machinectl   pull-tar \&...\f[R].
+.TP
+\f[B]\f[CB]bump\f[B]\f[R]
+Determines the current image version string (as configured with
+\f[C]ImageVersion=\f[R]/\f[C]--image-version=\f[R]), increases its last
+dot-separated component by one and writes the resulting version string
+to \f[C]mkosi.version\f[R].
+This is useful for implementing a simple versioning scheme: each time
+this verb is called the version is bumped in preparation for the
+subsequent build.
+Note that \f[C]--auto-bump\f[R]/\f[C]-B\f[R] may be used to
+automatically bump the version after each successful build.
+.TP
+\f[B]\f[CB]genkey\f[B]\f[R]
+Generate a pair of SecureBoot keys for usage with the
+\f[C]SecureBootKey=\f[R]/\f[C]--secure-boot-key=\f[R] and
+\f[C]SecureBootCertificate=\f[R]/\f[C]--secure-boot-certificate=\f[R]
+options.
+.TP
+\f[B]\f[CB]help\f[B]\f[R]
+This verb is equivalent to the \f[C]--help\f[R] switch documented below:
+it shows a brief usage explanation.
+.SS Execution flow
+.PP
+Execution flow for \f[C]mkosi build\f[R].
+Columns represent the execution context.
+Default values/calls are shown in parentheses.
+When building with \f[C]--incremental\f[R] mkosi creates a cache of the
+distribution installation for both images if not already existing and
+replaces the distribution installation in consecutive runs with data
+from the cached one.
+.IP
+.nf
+\f[C]
+            HOST            .          BUILD          .          FINAL
+                            .          IMAGE          .          IMAGE
+                            .                         .
+   start                    .                         .
+     |                      .                         .
+     v                      .                         .
+build script?  -------exists----->     copy           .
+     |                      .      skeleton trees     .
+     |                      .     (mkosi.skeleton/)   .
+    none                    .            |            .
+     |                      .            v            .
+     v                      .         install         .
+    skip                    .       distribution,     .
+ build image                .       packages and      .
+     |                      .      build packages,    .
+     |                      .           run           .
+     |                      .      prepare script     .
+     |                      .   (mkosi.prepare build) .
+     |                      .     or if incremental   .
+     |                      .  use cached build image .
+     |                      .            |            .
+     |                      .            v            .
+     |                      .          copy           .
+     |                      .      build sources      .
+     |                      .          (./)           .
+     |                      .            |            .
+     |                      .            v            .
+     |                      .          copy           .
+     |                      .       extra trees       .
+     |                      .      (mkosi.extra/)     .
+     |                      .            |            .
+     |                      .            v            .
+     |                      .           run           .
+     |                      .    postinstall script   .
+     |                      .  (mkosi.postinst build) .
+     |                      .            |            .
+     |         .-------------------------\[aq]            .
+     |         |            .                         .
+     |         v            .                         .
+     |        run           .                         .
+     |   finalize script    .                         .
+     |(mkosi.finalize build).                         .
+     |         |            .                         .
+     |         \[aq]-------------------------.            .
+     |                      .            |            .
+     |                      .            v            .
+     |                      .           run           .
+     |                      .       build script      .
+     |                      .      (mkosi.build)      .
+     |                      .            |            .
+     \[aq]-----------------------------------+------------------------.
+                            .                         .           |
+                            .                         .           v
+                            .                         .          copy
+                            .                         .     skeleton trees
+                            .                         .    (mkosi.skeleton/)
+                            .                         .           |
+                            .                         .           v
+                            .                         .        install
+                            .                         .      distribution
+                            .                         .      and packages,
+                            .                         .          run
+                            .                         .     prepare script
+                            .                         .  (mkosi.prepare final)
+                            .                         .    or if incremental
+                            .                         . use cached final image
+                            .                         .           |
+                            .                         .           v
+                            .                         .         copy
+                            .                         .     build results
+                            .                         .           |
+                            .                         .           v
+                            .                         .         copy
+                            .                         .      extra trees
+                            .                         .     (mkosi.extra/)
+                            .                         .           |
+                            .                         .           v
+                            .                         .          run
+                            .                         .    postinstall script
+                            .                         .  (mkosi.postinst final)
+                            .                         .           |
+                            .                         .           v
+                            .                         .           |
+                            .                         .     perform cleanup
+                            .                         . (remove files, packages,
+                            .                         .     package metadata)
+                            .                         .           |
+               .--------------------------------------------------\[aq]
+               |            .                         .
+               v            .                         .
+              run           .                         .
+        finalize script     .                         .
+    (mkosi.finalize final)  .                         .
+               |            .                         .
+     .---------\[aq]            .                         .
+     |                      .                         .
+     v                      .                         .
+    end                     .                         .
+                            .                         .
+            HOST            .          BUILD          .          FINAL
+                            .          IMAGE          .          IMAGE
+                            .                         .
+\f[R]
+.fi
+.SS Supported output formats
+.PP
+The following output formats are supported:
+.IP \[bu] 2
+Raw \f[I]GPT\f[R] disk image, with ext4 as root (\f[I]gpt_ext4\f[R])
+.IP \[bu] 2
+Raw \f[I]GPT\f[R] disk image, with xfs as root (\f[I]gpt_xfs\f[R])
+.IP \[bu] 2
+Raw \f[I]GPT\f[R] disk image, with btrfs as root (\f[I]gpt_btrfs\f[R])
+.IP \[bu] 2
+Raw \f[I]GPT\f[R] disk image, with squashfs as read-only root
+(\f[I]gpt_squashfs\f[R])
+.IP \[bu] 2
+Plain squashfs image, without partition table, as read-only root
+(\f[I]plain_squashfs\f[R])
+.IP \[bu] 2
+Plain directory, containing the OS tree (\f[I]directory\f[R])
+.IP \[bu] 2
+btrfs subvolume, with separate subvolumes for \f[C]/var\f[R],
+\f[C]/home\f[R], \f[C]/srv\f[R], \f[C]/var/tmp\f[R]
+(\f[I]subvolume\f[R])
+.IP \[bu] 2
+Tar archive (\f[I]tar\f[R])
+.IP \[bu] 2
+CPIO archive (\f[I]cpio\f[R]) in the format appropriate for a kernel
+initrd
+.PP
+When a \f[I]GPT\f[R] disk image is created, the following additional
+options are available:
+.IP \[bu] 2
+A swap partition may be added in
+.IP \[bu] 2
+The image may be made bootable on \f[I]EFI\f[R] and \f[I]BIOS\f[R]
+systems
+.IP \[bu] 2
+Separate partitions for \f[C]/srv\f[R] and \f[C]/home\f[R] may be added
+in
+.IP \[bu] 2
+The root, \f[C]/srv\f[R] and \f[C]/home\f[R] partitions may optionally
+be encrypted with LUKS.
+.IP \[bu] 2
+A dm-verity partition may be added in that adds runtime integrity data
+for the root partition
+.SS Configuration Settings
+.PP
+The following settings can be set through configuration files (the
+syntax with \f[C]SomeSetting=value\f[R]) and on the command line (the
+syntax with \f[C]--some-setting=value\f[R]).
+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
+Command line options that take no argument are shown without \[lq]=\[rq]
+in their long version.
+In the config files, they should be specified with a boolean argument:
+either \[lq]1\[rq], \[lq]yes\[rq], or \[lq]true\[rq] to enable, or
+\[lq]0\[rq], \[lq]no\[rq], \[lq]false\[rq] to disable.
+.SS [Distribution] Section
+.TP
+\f[B]\f[CB]Distribution=\f[B]\f[R], \f[B]\f[CB]--distribution=\f[B]\f[R], \f[B]\f[CB]-d\f[B]\f[R]
+The distribution to install in the image.
+Takes one of the following arguments: \f[C]fedora\f[R],
+\f[C]debian\f[R], \f[C]ubuntu\f[R], \f[C]arch\f[R], \f[C]opensuse\f[R],
+\f[C]mageia\f[R], \f[C]centos\f[R], \f[C]centos_epel\f[R],
+\f[C]clear\f[R], \f[C]photon\f[R], \f[C]openmandriva\f[R],
+\f[C]rocky\f[R], \f[C]rocky_epel\f[R], \f[C]alma\f[R],
+\f[C]alma_epel\f[R].
+If not specified, defaults to the distribution of the host.
+.TP
+\f[B]\f[CB]Release=\f[B]\f[R], \f[B]\f[CB]--release=\f[B]\f[R], \f[B]\f[CB]-r\f[B]\f[R]
+The release of the distribution to install in the image.
+The precise syntax of the argument this takes depends on the
+distribution used, and is either a numeric string (in case of Fedora
+Linux, CentOS, \&..., e.g.\ \f[C]29\f[R]), or a distribution version
+name (in case of Debian, Ubuntu, \&..., e.g.\ \f[C]artful\f[R]).
+If neither this option, nor \f[C]Distribution=\f[R] is specified,
+defaults to the distribution version of the host.
+If the distribution is specified, defaults to a recent version of it.
+.TP
+\f[B]\f[CB]Mirror=\f[B]\f[R], \f[B]\f[CB]--mirror=\f[B]\f[R], \f[B]\f[CB]-m\f[B]\f[R]
+The mirror to use for downloading the distribution packages.
+Expects a mirror URL as argument.
+.TP
+\f[B]\f[CB]Repositories=\f[B]\f[R], \f[B]\f[CB]--repositories=\f[B]\f[R]
+Additional package repositories to use during installation.
+Expects one or more URLs as argument, separated by commas.
+This option may be used multiple times, in which case the list of
+repositories to use is combined.
+Use \[lq]!*\[rq] to remove all repositories from to the list or use
+e.g.\ \[lq]!repo-url\[rq] to remove just one specific repository.
+For Arch Linux, additional repositories must be passed in the form
+\f[C]<name>::<url>\f[R] (e.g.\ \f[C]myrepo::https://myrepo.net\f[R]).
+.TP
+\f[B]\f[CB]UseHostRepositories=\f[B]\f[R], \f[B]\f[CB]--use-host-repositories\f[B]\f[R]
+This option is only applicable for RPM-based distributions:
+\f[I]CentOS\f[R], \f[I]Fedora Linux\f[R], \f[I]Mageia\f[R],
+\f[I]Photon\f[R], \f[I]Rocky Linux\f[R], \f[I]Alma Linux\f[R] and
+\f[I]OpenMandriva\f[R].
+Allows use of the host\[cq]s existing RPM repositories.
+By default, a hardcoded set of default RPM repositories is generated and
+used.
+Use \f[C]--repositories=\f[R] to identify a custom set of repositories
+to be enabled and used for the build.
+.TP
+\f[B]\f[CB]RepositoryDirectory\f[B]\f[R], \f[B]\f[CB]--repository-directory\f[B]\f[R]
+This option can (for now) only be used with RPM-based istributions and
+Arch Linux.
+It identifies a directory containing extra repository definitions that
+will be used when installing packages.
+The files are passed directly to the corresponding package manager and
+should be written in the format expected by the package manager of the
+image\[cq]s distro.
+.TP
+\f[B]\f[CB]Architecture=\f[B]\f[R], \f[B]\f[CB]--architecture=\f[B]\f[R]
+The architecture to build the image for.
+Note that this currently only works for architectures compatible with
+the host\[cq]s architecture.
+.SS [Output] Section
+.TP
+\f[B]\f[CB]Format=\f[B]\f[R], \f[B]\f[CB]--format=\f[B]\f[R], \f[B]\f[CB]-t\f[B]\f[R]
+The image format type to generate.
+One of \f[C]directory\f[R] (for generating OS images inside a local
+directory), \f[C]subvolume\f[R] (similar, but as a btrfs subvolume),
+\f[C]tar\f[R] (similar, but a tarball of the image is generated),
+\f[C]cpio\f[R] (similar, but a cpio archive is generated),
+\f[C]gpt_ext4\f[R] (a block device image with an ext4 file system inside
+a GPT partition table), \f[C]gpt_xfs\f[R] (similar, but with an xfs file
+system), \f[C]gpt_btrfs\f[R] (similar, but with an btrfs file system),
+\f[C]gpt_squashfs\f[R] (similar, but with a squashfs file system),
+\f[C]plain_squashfs\f[R] (a plain squashfs file system without a
+partition table).
+.TP
+\f[B]\f[CB]ManifestFormat=\f[B]\f[R], \f[B]\f[CB]--manifest-format=\f[B]\f[R]
+The manifest format type or types to generate.
+A comma-delimited list consisting of \f[C]json\f[R] (the standard JSON
+output format that describes the packages installed),
+\f[C]changelog\f[R] (a human-readable text format designed for diffing).
+Defaults to \f[C]json\f[R].
+.TP
+\f[B]\f[CB]Output=\f[B]\f[R], \f[B]\f[CB]--output=\f[B]\f[R], \f[B]\f[CB]-o\f[B]\f[R]
+Path for the output image file to generate.
+Takes a relative or absolute path where the generated image will be
+placed.
+If neither this option nor \f[C]OutputDirectory=\f[R] is used, the image
+is generated under the name \f[C]image\f[R], but its name suffixed with
+an appropriate file suffix (e.g.\ \f[C]image.raw.xz\f[R] in case
+\f[C]gpt_ext4\f[R] is used in combination with \f[C]xz\f[R]
+compression).
+If the \f[C]ImageId=\f[R] option is configured it is used instead of
+\f[C]image\f[R] in the default output name.
+If an image version is specified via \f[C]ImageVersion=\f[R], it is
+included in the default name, e.g.\ a specified image version of
+\f[C]7.8\f[R] might result in an image file name of
+\f[C]image_7.8.raw.xz\f[R].
+.TP
+\f[B]\f[CB]OutputSplitRoot=\f[B]\f[R], \f[B]\f[CB]--output-split-root=\f[B]\f[R], \f[B]\f[CB]OutputSplitVerify=\f[B]\f[R], \f[B]\f[CB]--output-split-verity=\f[B]\f[R], \f[B]\f[CB]OutputSplitKernel=\f[B]\f[R], \f[B]\f[CB]--output-split-kernel=\f[B]\f[R]
+Paths for the split-out output image files, when
+\f[C]SplitArtifacts=yes\f[R] is used.
+If unspecified, the relevant split artifact files will be named like the
+main image, but with \f[C].root\f[R], \f[C].verity\f[R], and
+\f[C].efi\f[R] suffixes inserted (and in turn possibly suffixed by
+compression suffix, if compression is enabled).
+.TP
+\f[B]\f[CB]OutputDirectory=\f[B]\f[R], \f[B]\f[CB]--output-dir=\f[B]\f[R], \f[B]\f[CB]-O\f[B]\f[R]
+Path to a directory where to place all generated artifacts (i.e.\ the
+generated image when an output path is not given, \f[C]SHA256SUMS\f[R]
+file, etc.).
+If this is not specified and the directory \f[C]mkosi.output/\f[R]
+exists in the local directory, it is automatically used for this
+purpose.
+If the setting is not used and \f[C]mkosi.output/\f[R] does not exist,
+all output artifacts are placed adjacent to the output image file.
+.TP
+\f[B]\f[CB]WorkspaceDirectory=\f[B]\f[R], \f[B]\f[CB]--workspace-dir=\f[B]\f[R]
+Path to a directory where to store data required temporarily while
+building the image.
+This directory should have enough space to store the full OS image,
+though in most modes the actually used disk space is smaller.
+If not specified, and \f[C]mkosi.workspace/\f[R] exists in the local
+directory, it is used for this purpose.
+Otherwise, a subdirectory in the temporary storage area is used
+(\f[C]$TMPDIR\f[R] if set, \f[C]/var/tmp/\f[R] otherwise).
+The data in this directory is removed automatically after each build.
+It\[cq]s safe to manually remove the contents of this directory should
+an \f[C]mkosi\f[R] invocation be aborted abnormally (for example, due to
+reboot/power failure).
+If the \f[C]btrfs\f[R] output modes are selected this directory must be
+backed by \f[C]btrfs\f[R] too.
+.TP
+\f[B]\f[CB]Force=\f[B]\f[R], \f[B]\f[CB]--force\f[B]\f[R], \f[B]\f[CB]-f\f[B]\f[R]
+Replace the output file if it already exists, when building an image.
+By default when building an image and an output artifact already exists
+\f[C]mkosi\f[R] will refuse operation.
+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 \[lq]Files\[rq] section below),
+specifying this option thrice will ensure the package cache is removed
+too, before the re-build is initiated.
+For the \f[C]clean\f[R] operation this option has a slightly different
+effect: by default the verb will only remove build artifacts from a
+previous run, when specified once the incremental cache files are
+deleted too, and when specified twice the package cache is also removed.
+.PP
+.TP
+\f[B]\f[CB]GPTFirstLBA=\f[B]\f[R], \f[B]\f[CB]--gpt-first-lba=\f[B]\f[R]
+Override the first usable LBA (Logical Block Address) within the GPT
+header.
+This defaults to \f[C]2048\f[R], which is actually the desired value.
+However, some tools, e.g.\ the \f[C]prl_disk_tool\f[R] utility from the
+Parallels virtualization suite require this to be set to \f[C]34\f[R],
+otherwise they might fail to resize the disk image and/or partitions
+inside it.
+.TP
+\f[B]\f[CB]Bootable=\f[B]\f[R], \f[B]\f[CB]--bootable\f[B]\f[R], \f[B]\f[CB]-b\f[B]\f[R]
+Generate a bootable image.
+By default this will generate an image bootable on UEFI systems.
+Use \f[C]BootProtocols=\f[R] to select support for a different boot
+protocol.
+.TP
+\f[B]\f[CB]BootProtocols=\f[B]\f[R], \f[B]\f[CB]--boot-protocols=\f[B]\f[R]
+Pick one or more boot protocols to support when generating a bootable
+image, as enabled with \f[C]Bootable=\f[R].
+Takes a comma-separated list of \f[C]uefi\f[R] or \f[C]bios\f[R].
+May be specified more than once in which case the specified lists are
+merged.
+If \f[C]uefi\f[R] is specified the \f[C]sd-boot\f[R] UEFI boot loader is
+used, if \f[C]bios\f[R] is specified the GNU Grub boot loader is used.
+Use \[lq]!*\[rq] to remove all previously added protocols or
+\[lq]!protocol\[rq] to remove one protocol.
+.TP
+\f[B]\f[CB]KernelCommandLine=\f[B]\f[R], \f[B]\f[CB]--kernel-command-line=\f[B]\f[R]
+Use the specified kernel command line when building bootable images.
+By default command line arguments get appended.
+To remove all arguments from the current list pass \[lq]!*\[rq].
+To remove specific arguments add a space separated list of \[lq]!\[rq]
+prefixed arguments.
+For example adding \[lq]!* console=ttyS0 rw\[rq] to a
+\f[C]mkosi.default\f[R] file or the command line arguments passes
+\[lq]console=ttyS0 rw\[rq] to the kernel in any case.
+Just adding \[lq]console=ttyS0 rw\[rq] would append these two arguments
+to the kernel command line created by lower priority configuration files
+or previous \f[C]KernelCommandLine=\f[R] command line arguments.
+.TP
+\f[B]\f[CB]SecureBoot=\f[B]\f[R], \f[B]\f[CB]--secure-boot\f[B]\f[R]
+Sign the resulting kernel/initrd image for UEFI SecureBoot.
+.TP
+\f[B]\f[CB]SecureBootKey=\f[B]\f[R], \f[B]\f[CB]--secure-boot-key=\f[B]\f[R]
+Path to the PEM file containing the secret key for signing the UEFI
+kernel image, if \f[C]SecureBoot=\f[R] is used.
+.TP
+\f[B]\f[CB]SecureBootCertificate=\f[B]\f[R], \f[B]\f[CB]--secure-boot-certificate=\f[B]\f[R]
+Path to the X.509 file containing the certificate for the signed UEFI
+kernel image, if \f[C]SecureBoot=\f[R] is used.
+.TP
+\f[B]\f[CB]SecureBootCommonName=\f[B]\f[R], \f[B]\f[CB]--secure-boot-common-name=\f[B]\f[R]
+Common name to be used when generating SecureBoot keys via mkosi\[cq]s
+\f[C]genkey\f[R] command.
+Defaults to \f[C]mkosi of %u\f[R], where \f[C]%u\f[R] expands to the
+username of the user invoking mkosi.
+.TP
+\f[B]\f[CB]SecureBootValidDays=\f[B]\f[R], \f[B]\f[CB]--secure-boot-valid-days=\f[B]\f[R]
+Number of days that the keys should remain valid when generating
+SecureBoot keys via mkosi\[cq]s \f[C]genkey\f[R] command.
+Defaults to two years (730 days).
+.TP
+\f[B]\f[CB]ReadOnly=\f[B]\f[R], \f[B]\f[CB]--read-only\f[B]\f[R]
+Set the read-only flag on the root partition in the partition table.
+Only applies to \f[C]gpt_ext4\f[R], \f[C]gpt_xfs\f[R],
+\f[C]gpt_btrfs\f[R], \f[C]subvolume\f[R] output formats, and is implied
+on \f[C]gpt_squashfs\f[R] and \f[C]plain_squashfs\f[R].
+The read-only flag is essentially a hint to tools using the image (see
+https://systemd.io/DISCOVERABLE_PARTITIONS/).
+In particular, all systemd tools like \f[C]systemd-nspawn\f[R] and
+\f[C]systemd-gpt-auto-generator\f[R] will mount such partitions
+read-only, but tools from other project may ignore the flag.
+.TP
+\f[B]\f[CB]Minimize=\f[B]\f[R], \f[B]\f[CB]--minimize\f[B]\f[R]
+Attempt to make the resulting root file system as small as possible by
+removing free space from the file system.
+Only supported for \f[C]gpt_ext4\f[R] and \f[C]gpt_btrfs\f[R].
+For ext4 this relies on \f[C]resize2fs -M\f[R], which reduces the free
+disk space but is not perfect and generally leaves some free space.
+For btrfs the results are optimal and no free space is left.
+.TP
+\f[B]\f[CB]Encrypt=\f[B]\f[R], \f[B]\f[CB]--encrypt\f[B]\f[R]
+Encrypt all partitions in the file system or just the root file system.
+Takes either \f[C]all\f[R] or \f[C]data\f[R] as argument.
+If \f[C]all\f[R], the root, \f[C]/home\f[R] and \f[C]/srv\f[R] file
+systems will be encrypted using dm-crypt/LUKS (with its default
+settings).
+If \f[C]data\f[R], the root file system will be left unencrypted, but
+\f[C]/home\f[R] and \f[C]/srv\f[R] will be encrypted.
+The passphrase to use is read from the \f[C]mkosi.passphrase\f[R] file
+in the current working directory.
+Note that the UEFI System Partition (ESP) containing the boot loader and
+kernel to boot is never encrypted since it needs to be accessible by the
+firmware.
+.TP
+\f[B]\f[CB]Verity=\f[B]\f[R], \f[B]\f[CB]--verity\f[B]\f[R]
+Add a \[lq]Verity\[rq] integrity partition to the image.
+Takes a boolean or the special value \f[C]signed\f[R], and defaults to
+disabled.
+If enabled, the root partition (or \f[C]/usr/\f[R] partition, in case
+\f[C]UsrOnly=\f[R] is enabled) is protected with \f[C]dm-verity\f[R]
+against offline modification, the verification data is placed in an
+additional GPT partition.
+Implies \f[C]ReadOnly=yes\f[R].
+If this is enabled, the Verity root hash is written to an output file
+with \f[C].roothash\f[R] or \f[C].usrhash\f[R] suffix.
+If set to \f[C]signed\f[R], Verity is also enabled, but the resulting
+root hash is then also signed (in PKCS#7 format) with the signature key
+configured with \f[C]SecureBootKey=\f[R].
+Or in other words: the SecureBoot key pair is then used to both sign the
+kernel, if that is enabled, and the root/\f[C]/usr/\f[R] file system.
+This signature is then stored in an additional output file with the
+\f[C].roothash.p7s\f[R] or \f[C].usrhash.p7s\f[R] suffix in DER format.
+It is also written to an additional partition in the image.
+The latter allows generating self-contained signed disk images,
+implementing the Verity provisions described in the Discoverable
+Partitions Specification (https://systemd.io/DISCOVERABLE_PARTITIONS).
+.TP
+\f[B]\f[CB]CompressFs=\f[B]\f[R], \f[B]\f[CB]--compress-fs=\f[B]\f[R]
+Enable or disable internal compression in the file system.
+Only applies to output formats with squashfs or btrfs.
+Takes one of \f[C]zlib\f[R], \f[C]lzo\f[R], \f[C]zstd\f[R],
+\f[C]lz4\f[R], \f[C]xz\f[R] or a boolean value as argument.
+If the latter is used compression is enabled/disabled and the default
+algorithm is used.
+In case of the \f[C]squashfs\f[R] output formats compression is implied,
+but this option may be used to select the algorithm.
+.TP
+\f[B]\f[CB]CompressOutput=\f[B]\f[R], \f[B]\f[CB]--compress-output=\f[B]\f[R]
+Configure compression for the resulting image or archive.
+The argument can be either a boolean or a compression algorithm
+(\f[C]xz\f[R], \f[C]zstd\f[R]).
+\f[C]xz\f[R] compression is used by default.
+Note that when applied to block device image types this means the image
+cannot be started directly but needs to be decompressed first.
+This also means that the \f[C]shell\f[R], \f[C]boot\f[R], \f[C]qemu\f[R]
+verbs are not available when this option is used.
+Implied for \f[C]tar\f[R] and \f[C]cpio\f[R].
+.TP
+\f[B]\f[CB]Compress=\f[B]\f[R], \f[B]\f[CB]--compress=\f[B]\f[R]
+Enable compression.
+Using this option is equivalent to either \f[C]CompressFs=\f[R] or
+\f[C]CompressOutput=\f[R]; the appropriate type of compression is
+selected automatically.
+.TP
+\f[B]\f[CB]Mksquashfs=\f[B]\f[R], \f[B]\f[CB]--mksquashfs=\f[B]\f[R]
+Set the path to the \f[C]mksquashfs\f[R] executable to use.
+This is useful in case the parameters for the tool shall be augmented,
+as the tool may be replaced by a script invoking it with the right
+parameters, this way.
+.TP
+\f[B]\f[CB]QCow2=\f[B]\f[R], \f[B]\f[CB]--qcow2\f[B]\f[R]
+Encode the resulting image as QEMU QCOW2 image.
+This only applies to \f[C]gpt_ext4\f[R], \f[C]gpt_xfs\f[R],
+\f[C]gpt_btrfs\f[R], \f[C]gpt_squashfs\f[R].
+QCOW2 images can be read natively by \f[C]qemu\f[R], but not by the
+Linux kernel.
+This means the \f[C]shell\f[R] and \f[C]boot\f[R] verbs are not
+available when this option is used, however \f[C]qemu\f[R] will work.
+.TP
+\f[B]\f[CB]Hostname=\f[B]\f[R], \f[B]\f[CB]--hostname=\f[B]\f[R]
+Set the image\[cq]s hostname to the specified name.
+.TP
+\f[B]\f[CB]ImageVersion=\f[B]\f[R], \f[B]\f[CB]--image-version=\f[B]\f[R]
+Configure the image version.
+This accepts any string, but it is recommended to specify a series of
+dot separated components.
+The version may also be configured in a file \f[C]mkosi.version\f[R] in
+which case it may be conveniently managed via the \f[C]bump\f[R] verb or
+the \f[C]--auto-bump\f[R] switch.
+When specified the image version is included in the default output file
+name, i.e.\ instead of \f[C]image.raw\f[R] the default will be
+\f[C]image_0.1.raw\f[R] for version \f[C]0.1\f[R] of the image, and
+similar.
+The version is also passed via the \f[C]$IMAGE_VERSION\f[R] to any build
+scripts invoked (which may be useful to patch it into
+\f[C]/etc/os-release\f[R] or similar, in particular the
+\f[C]IMAGE_VERSION=\f[R] field of it).
+.TP
+\f[B]\f[CB]ImageId=\f[B]\f[R], \f[B]\f[CB]--image-id=\f[B]\f[R]
+Configure the image identifier.
+This accepts a freeform string that shall be used to identify the image
+with.
+If set the default output file will be named after it (possibly suffixed
+with the version).
+If this option is used the root, \f[C]/usr/\f[R] and Verity partitions
+in the image will have their labels set to this (possibly suffixed by
+the image version).
+The identifier is also passed via the \f[C]$IMAGE_ID\f[R] to any build
+scripts invoked (which may be useful to patch it into
+\f[C]/etc/os-release\f[R] or similar, in particular the
+\f[C]IMAGE_ID=\f[R] field of it).
+.TP
+\f[B]\f[CB]WithUnifiedKernelImages=\f[B]\f[R], \f[B]\f[CB]--without-unified-kernel-images\f[B]\f[R]
+If specified, mkosi does not build unified kernel images and instead
+installs kernels with a separate initrd and boot loader config to the
+efi or bootloader partition.
+.TP
+\f[B]\f[CB]HostonlyInitrd=\f[B]\f[R], \f[B]\f[CB]--hostonly-initrd\f[B]\f[R]
+If specified, mkosi will run the tool to create the initrd such that a
+non-generic initrd is created that will only be able to run on the
+system mkosi is run on.
+Currently mkosi uses dracut for all supported distributions except Clear
+Linux and this option translates to enabling dracut\[cq]s hostonly
+option.
+.TP
+\f[B]\f[CB]UsrOnly=\f[B]\f[R], \f[B]\f[CB]--usr-only\f[B]\f[R]
+If specified, \f[C]mkosi\f[R] will only add the \f[C]/usr/\f[R]
+directory tree (instead of the whole root file system) to the image.
+This is useful for fully stateless systems that come up pristine on
+every single boot, where \f[C]/etc/\f[R] and \f[C]/var/\f[R] are
+populated by \f[C]systemd-tmpfiles\f[R]/\f[C]systemd-sysusers\f[R] and
+related calls, or systems that are originally shipped without a root
+file system, but where \f[C]systemd-repart\f[R] adds one on the first
+boot.
+.TP
+\f[B]\f[CB]SplitArtifacts=\f[B]\f[R], \f[B]\f[CB]--split-artifacts\f[B]\f[R]
+If specified and building an image with a partition table, also write
+out the root file system partition, its Verity partition (if configured)
+and the generated unified kernel (if configured) into separate output
+files.
+This is useful in A/B update scenarios where an existing disk image
+shall be augmented with a new version of a root or \f[C]/usr\f[R]
+partition along with its Verity partition and unified kernel.
+.TP
+\f[B]\f[CB]NoChown=\f[B]\f[R], \f[B]\f[CB]--no-chown\f[B]\f[R]
+By default, if \f[C]mkosi\f[R] is run inside a \f[C]sudo\f[R]
+environment all generated artifacts have their UNIX user/group ownership
+changed to the user which invoked \f[C]sudo\f[R].
+With this option this may be turned off and all generated files are
+owned by \f[C]root\f[R].
+.TP
+\f[B]\f[CB]TarStripSELinuxContext=\f[B]\f[R], \f[B]\f[CB]--tar-strip-selinux-context\f[B]\f[R]
+If running on a SELinux-enabled system (Fedora Linux, CentOS, Rocky
+Linux, Alma Linux), files inside the container are tagged with SELinux
+context extended attributes (\f[C]xattrs\f[R]), which may interfere with
+host SELinux rules in building or further container import stages.
+This option strips SELinux context attributes from the resulting tar
+archive.
+.TP
+\f[B]\f[CB]MachineID=\f[B]\f[R], \f[B]\f[CB]--machine-id\f[B]\f[R]
+Set the machine\[cq]s ID to the specified value.
+If unused, a random ID will be used while building the image and the
+final image will be shipped without a machine ID.
+.SS [Content] Section
+.TP
+\f[B]\f[CB]BasePackages=\f[B]\f[R], \f[B]\f[CB]--base-packages\f[B]\f[R]
+Takes a boolean or the special value \f[C]conditional\f[R].
+If true, automatically install packages to ensure basic functionality,
+as appropriate for the given image type.
+For example, \f[C]systemd\f[R] is always included,
+\f[C]systemd-udev\f[R] and \f[C]dracut\f[R] if the image is bootable,
+and so on.
+If false, only packages specified with \f[C]Packages=\f[R] will be
+installed.
+If \f[C]conditional\f[R], the list of packages to install will be
+extended with boolean dependencies (c.f.
+https://rpm.org/user_doc/boolean_dependencies.html), to install specific
+packages when \f[I]other\f[R] packages are in the list.
+For example, \f[C]systemd-udev\f[R] may be automatically included if the
+image is bootable and \f[C]systemd\f[R] is installed.
+With this, various \[lq]base\[rq] packages still need to be specified if
+they should be included, but the corresponding \[lq]extension\[rq]
+packages will be added automatically when appropriate.
+This feature depends on support in the package manager, so it is not
+implemented for all distributions.
+.TP
+\f[B]\f[CB]Packages=\f[B]\f[R], \f[B]\f[CB]--package=\f[B]\f[R], \f[B]\f[CB]-p\f[B]\f[R]
+Install the specified distribution packages (i.e.\ RPM, DEB, \&...) in
+the image.
+Takes a comma separated list of package specifications.
+This option may be used multiple times in which case the specified
+package lists are combined.
+Packages specified this way will be installed both in the development
+and the final image.
+Use \f[C]BuildPackages=\f[R] to specify packages that shall only be used
+for the image generated in the build image, but that shall not appear in
+the final image.
+The types and syntax of \[lq]package specifications\[rq] that are
+allowed depend on the package installer (e.g.\ \f[C]dnf\f[R] or
+\f[C]yum\f[R] for \f[C]rpm\f[R]-based distros or \f[C]apt\f[R] for
+\f[C]deb\f[R]-based distros), but may include package names, package
+names with version and/or architecture, package name globs, paths to
+packages in the file system, package groups, and virtual provides,
+including file paths.
+To remove a package e.g.\ added by a \f[C]mkosi.default\f[R]
+configuration file prepend the package name with \f[C]!\f[R].
+For example -p \[lq]!apache2\[rq] would remove the apache2 package.
+To replace the apache2 package by the httpd package just add -p
+\[lq]!apache2,httpd\[rq] to the command line arguments.
+To remove all packages use \[lq]!*\[rq].
+Example: when using an distro that uses \f[C]dnf\f[R],
+\f[C]Packages=meson libfdisk-devel.i686 git-* prebuilt/rpms/systemd-249-rc1.local.rpm /usr/bin/ld \[at]development-tools python3dist(mypy)\f[R]
+would install the \f[C]meson\f[R] package (in the latest version), the
+32-bit version of the \f[C]libfdisk-devel\f[R] package, all available
+packages that start with the \f[C]git-\f[R] prefix, a \f[C]systemd\f[R]
+rpm from the local file system, one of the packages that provides
+\f[C]/usr/bin/ld\f[R], the packages in the \[lq]Development Tools\[rq]
+group, and the package that contains the \f[C]mypy\f[R] python module.
+.TP
+\f[B]\f[CB]WithDocs=\f[B]\f[R], \f[B]\f[CB]--with-docs\f[B]\f[R]
+Include documentation in the image built.
+By default if the underlying distribution package manager supports it
+documentation is not included in the image built.
+The \f[C]$WITH_DOCS\f[R] environment variable passed to the
+\f[C]mkosi.build\f[R] script indicates whether this option was used or
+not.
+.TP
+\f[B]\f[CB]WithTests=\f[B]\f[R], \f[B]\f[CB]--without-tests\f[B]\f[R], \f[B]\f[CB]-T\f[B]\f[R]
+If set to false (or when the command-line option is used), the
+\f[C]$WITH_TESTS\f[R] environment variable is set to \f[C]0\f[R] when
+the \f[C]mkosi.build\f[R] script is invoked.
+This is supposed to be used by the build script to bypass any unit or
+integration tests that are normally run during the source build process.
+Note that this option has no effect unless the \f[C]mkosi.build\f[R]
+build script honors it.
+.TP
+\f[B]\f[CB]Cache=\f[B]\f[R], \f[B]\f[CB]--cache=\f[B]\f[R]
+Takes a path to a directory to use as package cache for the distribution
+package manager used.
+If this option is not used, but a \f[C]mkosi.cache/\f[R] directory is
+found in the local directory it is automatically used for this purpose.
+The directory configured this way is mounted into both the development
+and the final image while the package manager is running.
+.TP
+\f[B]\f[CB]SkeletonTree=\f[B]\f[R], \f[B]\f[CB]--skeleton-tree=\f[B]\f[R]
+Takes a path to a directory to copy into the OS tree before invoking the
+package manager.
+Use this to insert files and directories into the OS tree before the
+package manager installs any packages.
+If this option is not used, but the \f[C]mkosi.skeleton/\f[R] directory
+is found in the local directory it is automatically used for this
+purpose (also see the \[lq]Files\[rq] section below).
+Instead of a directory, a tar file may be provided.
+In this case it is unpacked into the OS tree before the package manager
+is invoked.
+This mode of operation allows setting permissions and file ownership
+explicitly, in particular for projects stored in a version control
+system such as \f[C]git\f[R] which retain full file ownership and access
+mode metadata for committed files.
+If the tar file \f[C]mkosi.skeleton.tar\f[R] is found in the local
+directory it will be automatically used for this purpose.
+.TP
+\f[B]\f[CB]ExtraTree=\f[B]\f[R], \f[B]\f[CB]--extra-tree=\f[B]\f[R]
+Takes a path to a directory to copy on top of the OS tree the package
+manager generated.
+Use this to override any default configuration files shipped with the
+distribution.
+If this option is not used, but the \f[C]mkosi.extra/\f[R] directory is
+found in the local directory it is automatically used for this purpose
+(also see the \[lq]Files\[rq] section below).
+As with the skeleton tree logic above, instead of a directory, a tar
+file may be provided too.
+\f[C]mkosi.skeleton.tar\f[R] will be automatically used if found in the
+local directory.
+.TP
+\f[B]\f[CB]CleanPackageMetadata=\f[B]\f[R], \f[B]\f[CB]--clean-package-metadata=\f[B]\f[R]
+Enable/disable removal of package manager databases, caches, and logs at
+the end of installation.
+Can be specified as true, false, or \[lq]\f[C]auto\f[R]\[rq] (the
+default).
+With \[lq]\f[C]auto\f[R]\[rq], files will be removed if the respective
+package manager executable is \f[I]not\f[R] present at the end of the
+installation.
+.TP
+\f[B]\f[CB]RemoveFiles=\f[B]\f[R], \f[B]\f[CB]--remove-files=\f[B]\f[R]
+Takes a comma-separated list of globs.
+Files in the image matching the globs will be purged at the end.
+.TP
+\f[B]\f[CB]RemovePackages=\f[B]\f[R], \f[B]\f[CB]--remove-package=\f[B]\f[R]
+Takes a comma-separated list of package specifications for removal, in
+the same format as \f[C]Packages=\f[R].
+The removal will be performed as one of the last steps.
+This step is skipped if \f[C]CleanPackageMetadata=no\f[R] is used.
+This option is currently only implemented for distributions using
+\f[C]dnf\f[R].
+.TP
+\f[B]\f[CB]Environment=\f[B]\f[R], \f[B]\f[CB]--environment=\f[B]\f[R]
+Adds variables to the environment that the
+build/prepare/postinstall/finalize scripts are executed with.
+Takes a space-separated list of variable assignments or just variable
+names.
+In the latter case, the values of those variables will be passed through
+from the environment in which \f[C]mkosi\f[R] was invoked.
+This option may be specified more than once, in which case all listed
+variables will be set.
+If the same variable is set twice, the later setting overrides the
+earlier one.
+.TP
+\f[B]\f[CB]BuildSources=\f[B]\f[R], \f[B]\f[CB]--build-sources=\f[B]\f[R]
+Takes a path to a source tree to copy into the development image, if the
+build script is used.
+This only applies if a build script is used, and defaults to the local
+directory.
+Use \f[C]SourceFileTransfer=\f[R] to configure how the files are
+transferred from the host to the container image.
+.TP
+\f[B]\f[CB]BuildDirectory=\f[B]\f[R], \f[B]\f[CB]--build-dir=\f[B]\f[R]
+Takes a path of a directory to use as build directory for build systems
+that support out-of-tree builds (such as Meson).
+The directory used this way is shared between repeated builds, and
+allows the build system to reuse artifacts (such as object files,
+executable, \&...) generated on previous invocations.
+This directory is mounted into the development image when the build
+script is invoked.
+The build script can find the path to this directory in the
+\f[C]$BUILDDIR\f[R] environment variable.
+If this option is not specified, but a directory
+\f[C]mkosi.builddir/\f[R] exists in the local directory it is
+automatically used for this purpose (also see the \[lq]Files\[rq]
+section below).
+.TP
+\f[B]\f[CB]IncludeDirectory=\f[B]\f[R], \f[B]\f[CB]--include-directory=\f[B]\f[R]
+Takes a path of a directory to use as the include directory.
+This directory is mounted at \f[C]/usr/include\f[R] when building the
+build image and running the build script.
+This means all include files installed to \f[C]/usr/include\f[R] will be
+stored in this directory.
+This is useful to make include files available on the host system for
+use by language servers to provide code completion.
+If this option is not specified, but a directory
+\f[C]mkosi.includedir/\f[R] exists in the local directory, it is
+automatically used for this purpose (also see the \[lq]Files\[rq]
+section below).
+.TP
+\f[B]\f[CB]InstallDirectory=\f[B]\f[R], \f[B]\f[CB]--install-directory=\f[B]\f[R]
+Takes a path of a directory to use as the install directory.
+The directory used this way is shared between builds and allows the
+build system to not have to reinstall files that were already installed
+by a previous build and didn\[cq]t change.
+The build script can find the path to this directory in the
+\f[C]$DESTDIR\f[R] environment variable.
+If this option is not specified, but a directory
+\f[C]mkosi.installdir\f[R] exists in the local directory, it is
+automatically used for this purpose (also see the \[lq]Files\[rq]
+section below).
+.TP
+\f[B]\f[CB]BuildPackages=\f[B]\f[R], \f[B]\f[CB]--build-package=\f[B]\f[R]
+Similar to \f[C]Packages=\f[R], but configures packages to install only
+in the first phase of the build, into the development image.
+This option should be used to list packages containing header files,
+compilers, build systems, linkers and other build tools the
+\f[C]mkosi.build\f[R] script requires to operate.
+Note that packages listed here are only included in the image created
+during the first phase of the build, and are absent in the final image.
+Use \f[C]Packages=\f[R] to list packages that shall be included in both.
+Packages are appended to the list.
+Packages prefixed with \[lq]!\[rq] are removed from the list.
+\[lq]!*\[rq] removes all packages from the list.
+.TP
+\f[B]\f[CB]Password=\f[B]\f[R], \f[B]\f[CB]--password=\f[B]\f[R]
+Set the password of the \f[C]root\f[R] user.
+By default the \f[C]root\f[R] account is locked.
+If this option is not used, but a file \f[C]mkosi.rootpw\f[R] exists in
+the local directory, the root password is automatically read from it.
+.TP
+\f[B]\f[CB]PasswordIsHashed=\f[B]\f[R], \f[B]\f[CB]--password-is-hashed\f[B]\f[R]
+Indicate that the password supplied for the \f[C]root\f[R] user has
+already been hashed, so that the string supplied with
+\f[C]Password=\f[R] or \f[C]mkosi.rootpw\f[R] will be written to
+\f[C]/etc/shadow\f[R] literally.
+.TP
+\f[B]\f[CB]Autologin=\f[B]\f[R], \f[B]\f[CB]--autologin\f[B]\f[R]
+Enable autologin for the \f[C]root\f[R] user on \f[C]/dev/pts/0\f[R]
+(nspawn), \f[C]/dev/tty1\f[R] (QEMU) and \f[C]/dev/ttyS0\f[R] (QEMU with
+\f[C]QemuHeadless=yes\f[R]) by patching \f[C]/etc/pam.d/login\f[R].
+.TP
+\f[B]\f[CB]SkipFinalPhase=\f[B]\f[R], \f[B]\f[CB]--skip-final-phase=\f[B]\f[R]
+Causes the (second) final image build stage to be skipped.
+This is useful in combination with a build script, for when you care
+about the artifacts that were created locally in \f[C]$BUILDDIR\f[R],
+but ultimately plan to discard the final image.
+.TP
+\f[B]\f[CB]BuildScript=\f[B]\f[R], \f[B]\f[CB]--build-script=\f[B]\f[R]
+Takes a path to an executable that is used as build script for this
+image.
+If this option is used the build process will be two-phased instead of
+single-phased.
+The specified script is copied onto the development image and executed
+inside an \f[C]systemd-nspawn\f[R] container environment.
+If this option is not used, but the \f[C]mkosi.build\f[R] file found in
+the local directory it is automatically used for this purpose (also see
+the \[lq]Files\[rq] section below).
+Specify an empty value to disable automatic detection.
+.TP
+\f[B]\f[CB]PrepareScript=\f[B]\f[R], \f[B]\f[CB]--prepare-script=\f[B]\f[R]
+Takes a path to an executable that is invoked inside the image right
+after installing the software packages.
+It is the last step before the image is cached (if incremental mode is
+enabled).
+This script is invoked inside a \f[C]systemd-nspawn\f[R] container
+environment, and thus does not have access to host resources.
+If this option is not used, but an executable script
+\f[C]mkosi.prepare\f[R] is found in the local directory, it is
+automatically used for this purpose.
+Specify an empty value to disable automatic detection.
+.TP
+\f[B]\f[CB]PostInstallationScript=\f[B]\f[R], \f[B]\f[CB]--postinst-script=\f[B]\f[R]
+Takes a path to an executable that is invoked inside the final image
+right after copying in the build artifacts generated in the first phase
+of the build.
+This script is invoked inside a \f[C]systemd-nspawn\f[R] container
+environment, and thus does not have access to host resources.
+If this option is not used, but an executable \f[C]mkosi.postinst\f[R]
+is found in the local directory, it is automatically used for this
+purpose.
+Specify an empty value to disable automatic detection.
+.TP
+\f[B]\f[CB]FinalizeScript=\f[B]\f[R], \f[B]\f[CB]--finalize-script=\f[B]\f[R]
+Takes a path to an executable that is invoked outside the final image
+right after copying in the build artifacts generated in the first phase
+of the build, and after having executed the \f[C]mkosi.postinst\f[R]
+script (see \f[C]PostInstallationScript=\f[R]).
+This script is invoked directly in the host environment, and hence has
+full access to the host\[cq]s resources.
+If this option is not used, but an executable \f[C]mkosi.finalize\f[R]
+is found in the local directory, it is automatically used for this
+purpose.
+Specify an empty value to disable automatic detection.
+.TP
+\f[B]\f[CB]SourceFileTransfer=\f[B]\f[R], \f[B]\f[CB]--source-file-transfer=\f[B]\f[R]
+Configures how the source file tree (as configured with
+\f[C]BuildSources=\f[R]) is transferred into the container image during
+the first phase of the build.
+Takes one of \f[C]copy-all\f[R] (to copy all files from the source
+tree), \f[C]copy-git-cached\f[R] (to copy only those files
+\f[C]git ls-files --cached\f[R] lists), \f[C]copy-git-others\f[R] (to
+copy only those files \f[C]git ls-files --others\f[R] lists),
+\f[C]mount\f[R] to bind mount the source tree directly.
+Defaults to \f[C]copy-git-cached\f[R] if a \f[C]git\f[R] source tree is
+detected, otherwise \f[C]copy-all\f[R].
+When you specify \f[C]copy-git-more\f[R], it is the same as
+\f[C]copy-git-cached\f[R], except it also includes the \f[C].git/\f[R]
+directory.
+.TP
+\f[B]\f[CB]SourceFileTransferFinal=\f[B]\f[R], \f[B]\f[CB]--source-file-transfer-final=\f[B]\f[R]
+Same as \f[C]SourceFileTransfer=\f[R], but for the final image instead
+of the build image.
+Takes the same values as \f[C]SourceFileFransfer=\f[R] except
+\f[C]mount\f[R].
+By default, sources are not copied into the final image.
+.TP
+\f[B]\f[CB]SourceResolveSymlinks=\f[B]\f[R], \f[B]\f[CB]--source-resolve-symlinks\f[B]\f[R]
+If given, any symbolic links in the source file tree are resolved and
+the file contents are copied to the build image.
+If not given, they are left as symbolic links.
+This only applies if \f[C]SourceFileTransfer=\f[R] is
+\f[C]copy-all\f[R].
+Defaults to leaving them as symbolic links.
+.TP
+\f[B]\f[CB]SourceResolveSymlinksFinal=\f[B]\f[R], \f[B]\f[CB]--source-resolve-symlinks-final\f[B]\f[R]
+Same as \f[C]SourceResolveSymlinks=\f[R], but for the final image
+instead of the build image.
+.TP
+\f[B]\f[CB]WithNetwork=\f[B]\f[R], \f[B]\f[CB]--with-network\f[B]\f[R]
+When true, enables network connectivity while the build script
+\f[C]mkosi.build\f[R] is invoked.
+By default, the build script runs with networking turned off.
+The \f[C]$WITH_NETWORK\f[R] environment variable is passed to the
+\f[C]mkosi.build\f[R] build script indicating whether the build is done
+with or without network.
+If specified as \f[C]never\f[R], the package manager is instructed not
+to contact the network for updating package data.
+This provides a minimal level of reproducibility, as long as the package
+data cache is already fully populated.
+.TP
+\f[B]\f[CB]Settings=\f[B]\f[R], \f[B]\f[CB]--settings=\f[B]\f[R]
+Specifies a \f[C].nspawn\f[R] settings file for \f[C]systemd-nspawn\f[R]
+to use in the \f[C]boot\f[R] and \f[C]shell\f[R] verbs, and to place
+next to the generated image file.
+This is useful to configure the \f[C]systemd-nspawn\f[R] environment
+when the image is run.
+If this setting is not used but an \f[C]mkosi.nspawn\f[R] file found in
+the local directory it is automatically used for this purpose.
+.SS [Partitions] Section
+.TP
+\f[B]\f[CB]BaseImage=\f[B]\f[R], \f[B]\f[CB]--base-image=\f[B]\f[R]
+Use the specified directory or file system image as the base image, and
+create the output image that consists only of changes from this base.
+The base image is attached as the lower file system in an overlayfs
+structure, and the output filesystem becomes the upper layer, initially
+empty.
+Thus files that are not modified compared to the base image are not
+present in the output image.
+This option may be used to create systemd \[lq]system extensions\[rq] or
+portable services.
+See https://systemd.io/PORTABLE_SERVICES/#extension-images for more
+information.
+.TP
+\f[B]\f[CB]RootSize=\f[B]\f[R], \f[B]\f[CB]--root-size=\f[B]\f[R]
+Takes a size in bytes for the root file system.
+The specified numeric value may be suffixed with \f[C]K\f[R],
+\f[C]M\f[R], \f[C]G\f[R] to indicate kilo-, mega- and gigabytes (all to
+the base of 1024).
+This applies to output formats \f[C]gpt_ext4\f[R], \f[C]gpt_xfs\f[R],
+\f[C]gpt_btrfs\f[R].
+Defaults to 3G.
+.TP
+\f[B]\f[CB]ESPSize=\f[B]\f[R], \f[B]\f[CB]--esp-size=\f[B]\f[R]
+Similar to \f[C]RootSize=\f[R], configures the size of the UEFI System
+Partition (ESP).
+This is only relevant if the \f[C]Bootable=\f[R] option is used to
+generate a bootable image.
+Defaults to 256 MB.
+.TP
+\f[B]\f[CB]SwapSize=\f[B]\f[R], \f[B]\f[CB]--swap-size=\f[B]\f[R]
+Similar to \f[C]RootSize=\f[R], configures the size of a swap partition
+on the image.
+If omitted, no swap partition is created.
+.TP
+\f[B]\f[CB]HomeSize=\f[B]\f[R], \f[B]\f[CB]--home-size=\f[B]\f[R]
+Similar to \f[C]RootSize=\f[R], configures the size of the
+\f[C]/home\f[R] partition.
+If omitted, no separate \f[C]/home\f[R] partition is created.
+.TP
+\f[B]\f[CB]SrvSize=\f[B]\f[R], \f[B]\f[CB]--srv-size=\f[B]\f[R]
+Similar to \f[C]RootSize=\f[R], configures the size of the
+\f[C]/srv\f[R] partition.
+If omitted, no separate \f[C]/srv\f[R] partition is created.
+.SS [Validation] Section
+.TP
+\f[B]\f[CB]Checksum=\f[B]\f[R], \f[B]\f[CB]--checksum\f[B]\f[R]
+Generate a \f[C]SHA256SUMS\f[R] file of all generated artifacts after
+the build is complete.
+.TP
+\f[B]\f[CB]Sign=\f[B]\f[R], \f[B]\f[CB]--sign\f[B]\f[R]
+Sign the generated \f[C]SHA256SUMS\f[R] using \f[C]gpg\f[R] after
+completion.
+.TP
+\f[B]\f[CB]Key=\f[B]\f[R], \f[B]\f[CB]--key=\f[B]\f[R]
+Select the \f[C]gpg\f[R] key to use for signing \f[C]SHA256SUMS\f[R].
+This key must be already present in the \f[C]gpg\f[R] keyring.
+.TP
+\f[B]\f[CB]BMap=\f[B]\f[R], \f[B]\f[CB]--bmap\f[B]\f[R]
+Generate a \f[C]bmap\f[R] file for usage with \f[C]bmaptool\f[R] from
+the generated image file.
+.SS [Host] Section
+.TP
+\f[B]\f[CB]ExtraSearchPaths=\f[B]\f[R], \f[B]\f[CB]--extra-search-paths=\f[B]\f[R]
+List of colon-separated paths to look for tools in, before using the
+regular \f[C]$PATH\f[R] search path.
+.TP
+\f[B]\f[CB]QemuHeadless=\f[B]\f[R], \f[B]\f[CB]--qemu-headless=\f[B]\f[R]
+When used with the \f[C]build\f[R] verb, this option adds
+\f[C]console=ttyS0\f[R] to the image\[cq]s kernel command line and sets
+the terminal type of the serial console in the image to the terminal
+type of the host (more specifically, the value of the \f[C]$TERM\f[R]
+environment variable passed to mkosi).
+This makes sure that all terminal features such as colors and shortcuts
+still work as expected when connecting to the qemu VM over the serial
+console (for example via \f[C]-nographic\f[R]).
+When used with the \f[C]qemu\f[R] verb, this option adds the
+\f[C]-nographic\f[R] option to \f[C]qemu\f[R]\[cq]s command line so qemu
+starts a headless vm and connects to its serial console from the current
+terminal instead of launching the VM in a separate window.
+.TP
+\f[B]\f[CB]QemuSmp=\f[B]\f[R], \f[B]\f[CB]--qemu-smp=\f[B]\f[R]
+When used with the \f[C]qemu\f[R] verb, this options sets
+\f[C]qemu\f[R]\[cq]s \f[C]-smp\f[R] argument which controls the number
+of guest\[cq]s CPUs.
+Defaults to \f[C]2\f[R].
+.TP
+\f[B]\f[CB]QemuMem=\f[B]\f[R], \f[B]\f[CB]--qemu-mem=\f[B]\f[R]
+When used with the \f[C]qemu\f[R] verb, this options sets
+\f[C]qemu\f[R]\[cq]s \f[C]-m\f[R] argument which controls the amount of
+guest\[cq]s RAM.
+Defaults to \f[C]1G\f[R].
+.TP
+\f[B]\f[CB]QemuKvm=\f[B]\f[R], \f[B]\f[CB]--qemu-kvm=\f[B]\f[R]
+When used with the \f[C]qemu\f[R] verb, this option specifies whether
+QEMU should use KVM acceleration.
+Defaults to yes if the host machine supports KVM acceleration, no
+otherwise.
+.TP
+\f[B]\f[CB]NspawnKeepUnit=\f[B]\f[R], \f[B]\f[CB]--nspawn-keep-unit\f[B]\f[R]
+When used, this option instructs underlying calls of systemd-nspawn to
+use the current unit scope, instead of creating a dedicated transcient
+scope unit for the containers.
+This option should be used when mkosi is run by a service unit.
+.TP
+\f[B]\f[CB]Netdev=\f[B]\f[R], \f[B]\f[CB]--netdev\f[B]\f[R]
+When used with the boot or qemu verbs, this option creates a virtual
+ethernet link between the host and the container/VM.
+The host interface is automatically picked up by systemd-networkd as
+documented in systemd-nspawn\[cq]s man page:
+https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-n
+.TP
+\f[B]\f[CB]Ephemeral=\f[B]\f[R], \f[B]\f[CB]--ephemeral\f[B]\f[R]
+When used with the \f[C]shell\f[R], \f[C]boot\f[R], or \f[C]qemu\f[R]
+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 subvolume snapshots or `reflinks' natively (\[lq]btrfs\[rq] or
+new \[lq]xfs\[rq]) than on more traditional file systems that do not
+(\[lq]ext4\[rq]).
+.TP
+\f[B]\f[CB]Ssh=\f[B]\f[R], \f[B]\f[CB]--ssh\f[B]\f[R]
+If specified, installs and enables \f[C]sshd\f[R] in the final image and
+generates a SSH keypair and adds the public key to root\[cq]s
+\f[C]authorized_keys\f[R] in the final image.
+The private key is stored in mkosi\[cq]s output directory.
+When building with this option and running the image using
+\f[C]mkosi boot\f[R] or \f[C]mkosi qemu\f[R], the \f[C]mkosi ssh\f[R]
+command can be used to connect to the container/VM via SSH.
+.TP
+\f[B]\f[CB]SshKey=\f[B]\f[R], \f[B]\f[CB]--ssh-key=\f[B]\f[R]
+If specified, use the given private key when connecting to the guest
+machine via \f[C]mkosi ssh\f[R].
+This requires the public key counterpart to be present in the same
+location, suffixed with \f[C].pub\f[R] (as done by
+\f[C]ssh-keygen\f[R]).
+If this option is not present, \f[C]mkosi\f[R] generates a new key pair
+automatically.
+.TP
+\f[B]\f[CB]SshAgent=\f[B]\f[R], \f[B]\f[CB]--ssh-agent=\f[B]\f[R]
+If specified as a path, use the given socket to connect to the ssh agent
+when building an image and when connecting via \f[C]mkosi ssh\f[R]
+instead of hard-coding a key.
+If specified as \f[C]true\f[R], \f[C]$SSH_AUTH_SOCK\f[R] will be parsed
+instead (hint: use \f[C]sudo\f[R] with \f[C]-E\f[R]).
+The keys listed by \f[C]ssh-add -L\f[R] will be installed as authorized
+keys in the built image.
+The \f[C]ssh\f[R] invocation done by \f[C]mkosi ssh\f[R] will inherit
+\f[C]$SSH_AUTH_SOCK\f[R] for authentication purposes.
+.TP
+\f[B]\f[CB]SshPort=\f[B]\f[R], \f[B]\f[CB]--ssh-port=\f[B]\f[R]
+In the image, sshd will be configured to listen on this port.
+\f[C]mkosi ssh\f[R] will connect to this port.
+.TP
+\f[B]\f[CB]SshTimeout=\f[B]\f[R], \f[B]\f[CB]--ssh-timeout=\f[B]\f[R]
+When used with the \f[C]ssh\f[R] verb, \f[C]mkosi\f[R] will attempt to
+retry the SSH connection up to given timeout (in seconds) in case it
+fails.
+This option is useful mainly in scripted environments where the
+\f[C]qemu\f[R] and \f[C]ssh\f[R] verbs are used in a quick succession
+and the virtual device might not get enough time to configure itself.
+.SS Commandline-only Options
+.PP
+Those settings cannot be configured in the configuration files.
+.TP
+\f[B]\f[CB]--directory=\f[B]\f[R], \f[B]\f[CB]-C\f[B]\f[R]
+Takes a path to a directory.
+\f[C]mkosi\f[R] switches to this directory before doing anything.
+Note that the various \f[C]mkosi.*\f[R] files are searched for only
+after changing to this directory, hence using this option is an
+effective way to build a project located in a specific directory.
+.TP
+\f[B]\f[CB]--default=\f[B]\f[R]
+Loads additional settings from the specified settings file.
+Most command line options may also be configured in a settings file.
+See the table below to see which command line options match which
+settings file option.
+If this option is not used, but a file \f[C]mkosi.default\f[R] is found
+in the local directory it is automatically used for this purpose.
+If a setting is configured both on the command line and in the settings
+file, the command line generally wins, except for options taking lists
+in which case both lists are combined.
+.TP
+\f[B]\f[CB]--all\f[B]\f[R], \f[B]\f[CB]-a\f[B]\f[R]
+Iterate through all files \f[C]mkosi.*\f[R] in the
+\f[C]mkosi.files/\f[R] subdirectory, and build each as if
+\f[C]--default=mkosi.files/mkosi.\&...\f[R] was invoked.
+This is a quick way to build a large number of images in one go.
+Any additional specified command line arguments override the relevant
+options in all files processed this way.
+.TP
+\f[B]\f[CB]--all-directory=\f[B]\f[R]
+If specified, overrides the directory the \f[C]--all\f[R] logic
+described above looks for settings files in.
+If unspecified, defaults to \f[C]mkosi.files/\f[R] in the current
+working directory.
+.TP
+\f[B]\f[CB]--incremental\f[B]\f[R], \f[B]\f[CB]-i\f[B]\f[R]
+Enable incremental build mode.
+This only applies if the two-phase \f[C]mkosi.build\f[R] build script
+logic is used.
+In this mode, a copy of the OS image is created immediately after all OS
+packages are unpacked but before the \f[C]mkosi.build\f[R] script is
+invoked in the development container.
+Similarly, a copy of the final image is created immediately before the
+build artifacts from the \f[C]mkosi.build\f[R] script are copied in.
+On subsequent invocations of \f[C]mkosi\f[R] with the \f[C]-i\f[R]
+switch these cached images may be used to skip the OS package unpacking,
+thus drastically speeding up repetitive build times.
+Note that when this is used and a pair of cached incremental images
+exists they are not automatically regenerated, even if options such as
+\f[C]Packages=\f[R] are modified.
+In order to force rebuilding of these cached images, combine
+\f[C]-i\f[R] with \f[C]-ff\f[R] to ensure cached images are first
+removed and then re-created.
+.TP
+\f[B]\f[CB]--debug=\f[B]\f[R]
+Enable additional debugging output.
+Takes a comma-separated list of arguments specifying the area of
+interest.
+Pass any invalid value (e.g.\ empty) to list currently accepted values.
+.TP
+\f[B]\f[CB]--version\f[B]\f[R]
+Show package version.
+.TP
+\f[B]\f[CB]--help\f[B]\f[R], \f[B]\f[CB]-h\f[B]\f[R]
+Show brief usage information.
+.TP
+\f[B]\f[CB]--auto-bump\f[B]\f[R], \f[B]\f[CB]-B\f[B]\f[R]
+If specified, after each successful build the the version is bumped in a
+fashion equivalent to the \f[C]bump\f[R] verb, in preparation for the
+next build.
+This is useful for simple, linear version management: each build in a
+series will have a version number one higher then the previous one.
+.SS Supported distributions
+.PP
+Images may be created containing installations of the following
+operating systems:
+.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]Clear Linux\f[R]
+.IP \[bu] 2
+\f[I]Photon\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]
+.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[C]debootstrap\f[R] may
+be used to build \f[I]Debian\f[R] or \f[I]Ubuntu\f[R] images.
+Any distribution that packages \f[C]dnf\f[R] may be used to build
+\f[I]Fedora Linux\f[R], \f[I]Mageia\f[R] or \f[I]OpenMandriva\f[R]
+images.
+Any distro that packages \f[C]pacstrap\f[R] may be used to build
+\f[I]Arch Linux\f[R] images.
+Any distribution that packages \f[C]zypper\f[R] may be used to build
+\f[I]openSUSE\f[R] images.
+Any distribution that packages \f[C]yum\f[R] (or the newer replacement
+\f[C]dnf\f[R]) may be used to build \f[I]CentOS\f[R], \f[I]Rocky
+Linux\f[R], or \f[I]Alma Linux\f[R] images.
+Any distribution that packages \f[C]emerge\f[R] may be used to build
+\f[I]Gentoo\f[R] images.
+.PP
+Currently, \f[I]Fedora Linux\f[R] packages all relevant tools as of
+Fedora 28.
+.SS Compatibility
+.PP
+Legacy concepts are avoided: generated images use \f[I]GPT\f[R] disk
+labels (and no \f[I]MBR\f[R] labels), and only systemd-based images may
+be generated.
+.PP
+All generated \f[I]GPT\f[R] disk images may be booted in a local
+container directly with:
+.IP
+.nf
+\f[C]
+systemd-nspawn -bi image.raw
+\f[R]
+.fi
+.PP
+Additionally, bootable \f[I]GPT\f[R] disk images (as created with the
+\f[C]--bootable\f[R] flag) work when booted directly by \f[I]EFI\f[R]
+and \f[I]BIOS\f[R] systems, for example in \f[I]KVM\f[R] via:
+.IP
+.nf
+\f[C]
+qemu-kvm -m 512 -smp 2 -bios /usr/share/edk2/ovmf/OVMF_CODE.fd -drive format=raw,file=image.raw
+\f[R]
+.fi
+.PP
+\f[I]EFI\f[R] bootable \f[I]GPT\f[R] images are larger than plain
+\f[I]GPT\f[R] images, as they additionally carry an \f[I]EFI\f[R] system
+partition containing a boot loader, as well as a kernel, kernel modules,
+udev and more.
+.PP
+All directory or btrfs subvolume images may be booted directly with:
+.IP
+.nf
+\f[C]
+systemd-nspawn -bD image
+\f[R]
+.fi
+.SH Files
+.PP
+To make it easy to build images for development versions of your
+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[CB]mkosi.default\f[B]\f[R] file provides the default
+configuration for the image building process.
+For example, it may specify the distribution to use (\f[C]fedora\f[R],
+\f[C]ubuntu\f[R], \f[C]debian\f[R], \f[C]arch\f[R], \f[C]opensuse\f[R],
+\f[C]mageia\f[R], \f[C]openmandriva\f[R], \f[C]gentoo\f[R]) for the
+image, or additional distribution packages to install.
+Note that all options encoded in this configuration file may also be set
+on the command line, and this file is hence little more than a way to
+make sure invoking \f[C]mkosi\f[R] without further parameters in your
+\f[I]source\f[R] tree is enough to get the right image of your choice
+set up.
+.RS 2
+.PP
+Additionally, if a \f[I]\f[CI]mkosi.default.d/\f[I]\f[R] directory
+exists, each file in it is loaded in the same manner adding/overriding
+the values specified in \f[C]mkosi.default\f[R].
+If \f[C]mkosi.default.d/\f[R] contains a directory named after the
+distribution being built, each file in that directory is also processed.
+.PP
+The file format is inspired by Windows \f[C].ini\f[R] files and supports
+multi-line assignments: any line with initial whitespace is considered a
+continuation line of the line before.
+Command-line arguments, as shown in the help description, have to be
+included in a configuration block (e.g.\ \[lq]\f[C][Content]\f[R]\[rq])
+corresponding to the argument group (e.g.\ \[lq]\f[C]Content\f[R]\[rq]),
+and the argument gets converted as follows:
+\[lq]\f[C]--with-network\f[R]\[rq] becomes
+\[lq]\f[C]WithNetwork=yes\f[R]\[rq].
+For further details see the table above.
+.RE
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.skeleton/\f[B]\f[R] directory or
+\f[B]\f[CB]mkosi.skeleton.tar\f[B]\f[R] archive may be used to insert
+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[CB]mkosi.extra/\f[B]\f[R] directory or
+\f[B]\f[CB]mkosi.extra.tar\f[B]\f[R] archive may be used to insert
+additional files into the image, on top of what the distribution
+includes in its packages.
+They are similar to \f[C]mkosi.skeleton/\f[R] and
+\f[C]mkosi.skeleton.tar\f[R], but the files are copied into the
+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
+\f[B]\f[CB]mkosi.build\f[B]\f[R] may be an executable script.
+If it exists, the image will be built twice: the first iteration will be
+the \f[I]development\f[R] image, the second iteration will be the
+\f[I]final\f[R] image.
+The \f[I]development\f[R] image is used to build the project in the
+current working directory (the \f[I]source\f[R] tree).
+For that the whole directory is copied into the image, along with the
+\f[C]mkosi.build\f[R] script.
+The script is then invoked inside the image (via
+\f[C]systemd-nspawn\f[R]), with \f[C]$SRCDIR\f[R] pointing to the
+\f[I]source\f[R] tree.
+\f[C]$DESTDIR\f[R] points to a directory where the script should place
+any files generated it would like to end up in the \f[I]final\f[R]
+image.
+Note that \f[C]make\f[R]/\f[C]automake\f[R]/\f[C]meson\f[R] based build
+systems generally honor \f[C]$DESTDIR\f[R], thus making it very natural
+to build \f[I]source\f[R] trees from the build script.
+After the \f[I]development\f[R] image was built and the build script ran
+inside of it, it is removed again.
+After that the \f[I]final\f[R] image is built, without any
+\f[I]source\f[R] tree or build script copied in.
+However, this time the contents of \f[C]$DESTDIR\f[R] are added into the
+image.
+.RS 2
+.PP
+When the source tree is copied into the \f[I]build\f[R] image, all files
+are copied, except for \f[C]mkosi.builddir/\f[R], \f[C]mkosi.cache/\f[R]
+and \f[C]mkosi.output/\f[R].
+That said, \f[C].gitignore\f[R] is respected if the source tree is a
+\f[C]git\f[R] checkout.
+If multiple different images shall be built from the same source tree it
+is essential to exclude their output files from this copy operation, as
+otherwise a version of an image built earlier might be included in a
+later build, which is usually not intended.
+An alternative to excluding these built images via \f[C].gitignore\f[R]
+entries is to use the \f[C]mkosi.output/\f[R] directory, which is an
+easy way to exclude all build artifacts.
+.PP
+The \f[C]$MKOSI_DEFAULT\f[R] environment variable will be set inside of
+this script so that you know which \f[C]mkosi.default\f[R] (if any) was
+passed in.
+.RE
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.prepare\f[B]\f[R] script is invoked directly after
+the software packages are installed, from within the image context, if
+it exists.
+It is once called for the \f[I]development\f[R] image (if this is
+enabled, see above) with the \[lq]build\[rq] command line parameter,
+right before copying the extra tree.
+It is called a second time for the \f[I]final\f[R] image with the
+\[lq]final\[rq] command line parameter.
+This script has network access and may be used to install packages from
+other sources than the distro\[cq]s package manager
+(e.g.\ \f[C]pip\f[R], \f[C]npm\f[R], \&...), after all software packages
+are installed but before the image is cached (if incremental mode is
+enabled).
+This script is executed within \f[C]$SRCDIR\f[R].
+In contrast to a general purpose installation, it is safe to install
+packages to the system (\f[C]pip install\f[R],
+\f[C]npm   install -g\f[R]) instead of in \f[C]$SRCDIR\f[R] itself
+because the build image is only used for a single project and can easily
+be thrown away and rebuilt so there\[cq]s no risk of conflicting
+dependencies and no risk of polluting the host system.
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.postinst\f[B]\f[R] script is invoked as the
+penultimate step of preparing an image, from within the image context,
+if it exists.
+It is called first for the \f[I]development\f[R] image (if this is
+enabled, see above) with the \[lq]build\[rq] command line parameter,
+right before invoking the build script.
+It is called a second time for the \f[I]final\f[R] image with the
+\[lq]final\[rq] command line parameter, right before the image is
+considered complete.
+This script may be used to alter the images without any restrictions,
+after all software packages and built sources have been installed.
+Note that this script is executed directly in the image context with the
+final root directory in place, without any
+\f[C]$SRCDIR\f[R]/\f[C]$DESTDIR\f[R] setup.
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.finalize\f[B]\f[R] script, if it exists, is invoked
+as last step of preparing an image, from the host system.
+It is once called for the \f[I]development\f[R] image (if this is
+enabled, see above) with the \[lq]build\[rq] command line parameter, as
+the last step before invoking the build script, after the
+\f[C]mkosi.postinst\f[R] script is invoked.
+It is called the second time with the \[lq]final\[rq] command line
+parameter as the last step before the image is considered complete.
+The environment variable \f[C]$BUILDROOT\f[R] points to the root
+directory of the installation image.
+Additional verbs may be added in the future, the script should be
+prepared for that.
+This script may be used to alter the images without any restrictions,
+after all software packages and built sources have been installed.
+This script is more flexible than \f[C]mkosi.postinst\f[R] in two
+regards: it has access to the host file system so it\[cq]s easier to
+copy in additional files or to modify the image based on external
+configuration, and the script is run in the host, so it can be used even
+without emulation even if the image has a foreign architecture.
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.mksquashfs-tool\f[B]\f[R] script, if it exists,
+will be called wherever \f[C]mksquashfs\f[R] would be called.
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.nspawn\f[B]\f[R] nspawn settings file will be
+copied into the same place as the output image file, if it exists.
+This is useful since nspawn looks for settings files next to image files
+it boots, for additional container runtime settings.
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.cache/\f[B]\f[R] directory, if it exists, is
+automatically used as package download cache, in order to speed repeated
+runs of the tool.
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.builddir/\f[B]\f[R] directory, if it exists, is
+automatically used as out-of-tree build directory, if the build commands
+in the \f[C]mkosi.build\f[R] script support it.
+Specifically, this directory will be mounted into the build container,
+and the \f[C]$BUILDDIR\f[R] environment variable will be set to it when
+the build script is invoked.
+The build script may then use this directory as build directory, for
+automake-style or ninja-style out-of-tree builds.
+This speeds up builds considerably, in particular when \f[C]mkosi\f[R]
+is used in incremental mode (\f[C]-i\f[R]): not only the disk images,
+but also the build tree is reused between subsequent invocations.
+Note that if this directory does not exist the \f[C]$BUILDDIR\f[R]
+environment variable is not set, and it is up to build script to decide
+whether to do in in-tree or an out-of-tree build, and which build
+directory to use.
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.includedir/\f[B]\f[R] directory, if it exists, is
+automatically used as an out-of-tree include directory for header files.
+Specifically, it will be mounted in the build container at
+\f[C]/usr/include/\f[R] when building the build image and when running
+the build script.
+After building the (cached) build image, this directory will contain all
+the files installed to \f[C]/usr/include\f[R].
+Language servers or other tools can use these files to provide a better
+editing experience for developers working on a project.
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.installdir/\f[B]\f[R] directory, if it exists, is
+automatically used as the install directory.
+Specifically, this directory will be mounted into the container at
+\f[C]/root/dest\f[R] when running the build script.
+After running the build script, the contents of this directory are
+installed into the final image.
+This is useful to cache the install step of the build.
+If used, subsequent builds will only have to reinstall files that have
+changed since the previous build.
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.rootpw\f[B]\f[R] file can be used to provide the
+password or hashed password (if \f[C]--password-is-hashed\f[R] is set)
+for the root user of the image.
+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[CB]mkosi.passphrase\f[B]\f[R] file provides the passphrase
+to use when LUKS encryption is selected.
+It should contain the passphrase literally, and not end in a newline
+character (i.e.\ in the same format as cryptsetup and
+\f[C]/etc/crypttab\f[R] expect the passphrase files).
+The file must have an access mode of 0600 or less.
+If this file does not exist and encryption is requested, the user is
+queried instead.
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.secure-boot.crt\f[B]\f[R] and
+\f[B]\f[CB]mkosi.secure-boot.key\f[B]\f[R] files contain an X.509
+certificate and PEM private key to use when UEFI SecureBoot support is
+enabled.
+All EFI binaries included in the image\[cq]s ESP are signed with this
+key, as a late step in the build process.
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.output/\f[B]\f[R] directory will be used for all
+build artifacts, if the image output path is not configured (i.e.\ no
+\f[C]--output=\f[R] setting specified), or configured to a filename
+(i.e.\ a path containing no \f[C]/\f[R] character).
+This includes the image itself, the root hash file in case Verity is
+used, the checksum and its signature if that\[cq]s enabled, and the
+nspawn settings file if there is any.
+Note that this directory is not used if the image output path contains
+at least one slash, and has no effect in that case.
+This setting is particularly useful if multiple different images shall
+be built from the same working directory, as otherwise the build result
+of a preceding run might be copied into a build image as part of the
+source tree (see above).
+.IP \[bu] 2
+The \f[B]\f[CB]mkosi.reposdir/\f[B]\f[R] directory, if it exists, is
+automatically used as the repository directory for extra repository
+files.
+See the \f[C]RepositoryDirectory\f[R] option for more information.
+.PP
+All these files are optional.
+.PP
+Note that the location of all these files may also be configured during
+invocation via command line switches, and as settings in
+\f[C]mkosi.default\f[R], in case the default settings are not acceptable
+for a project.
+.SH BUILD PHASES
+.PP
+If no build script \f[C]mkosi.build\f[R] (see above) is used the build
+consists of a single phase only: the final image is generated as the
+combination of \f[C]mkosi.skeleton/\f[R] (see above), the unpacked
+distribution packages and \f[C]mkosi.extra/\f[R].
+.PP
+If a build script \f[C]mkosi.build\f[R] is used the build consists of
+two phases: in the the first \f[C]development\f[R] phase an image that
+includes necessary build tools (i.e.\ the combination of
+\f[C]Packages=\f[R] and \f[C]BuildPackages=\f[R] is installed) is
+generated (i.e.\ the combination of \f[C]mkosi.skeleton/\f[R] and
+unpacked distribution packages).
+Into this image the source tree is copied and \f[C]mkosi.build\f[R]
+executed.
+The artifacts the \f[C]mkosi.build\f[R] generates are saved.
+Then, the second \f[C]final\f[R] phase starts: an image that excludes
+the build tools (i.e.\ only \f[C]Packages=\f[R] is installed,
+\f[C]BuildPackages=\f[R] is not) is generated.
+This time the build artifacts saved from the first phase are copied in,
+and \f[C]mkosi.extra\f[R] copied on top, thus generating the final
+image.
+.PP
+The two-phased approach ensures that source tree is executed in a clean
+and comprehensive environment, while at the same the final image remains
+minimal and contains only those packages necessary at runtime, but
+avoiding those necessary at build-time.
+.PP
+Note that only the package cache \f[C]mkosi.cache/\f[R] is shared
+between the two phases.
+The distribution package manager is executed exactly once in each phase,
+always starting from a directory tree that is populated with
+\f[C]mkosi.skeleton\f[R] but nothing else.
+.SH CACHING
+.PP
+\f[C]mkosi\f[R] supports three different caches for speeding up
+repetitive re-building of images.
+Specifically:
+.IP "1." 3
+The package cache of the distribution package manager may be cached
+between builds.
+This is configured with the \f[C]--cache=\f[R] option or the
+\f[C]mkosi.cache/\f[R] directory.
+This 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 an \f[C]mkosi.build\f[R] script is used, by enabling incremental
+build mode with \f[C]--incremental\f[R], a cached copy of the
+development and final images can be made immediately before the build
+sources are copied in (for the development image) or the artifacts
+generated by \f[C]mkosi.build\f[R] are copied in (in case of the final
+image).
+This form of caching allows bypassing the time-consuming package
+unpacking step of the distribution package managers, but is only
+effective if the list of packages to use remains stable, but the build
+sources and its scripts change regularly.
+Note that this cache requires manual flushing: whenever the package list
+is modified the cached images need to be explicitly removed before the
+next re-build, using the \f[C]-f\f[R] switch.
+.IP "3." 3
+Finally, between multiple builds the build artifact directory may be
+shared, using the \f[C]mkosi.builddir/\f[R] directory.
+This directory allows build systems such as Meson to reuse already
+compiled sources from a previous built, thus speeding up the build
+process of the \f[C]mkosi.build\f[R] build script.
+.PP
+The package cache (i.e.\ the first item above) is unconditionally
+useful.
+The latter two caches only apply to uses of \f[C]mkosi\f[R] with a
+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:
+an OS image rebuilt will be almost as quick to build the source tree
+only.
+.SH ENVIRONMENT VARIABLES
+.PP
+The build script \f[C]mkosi.build\f[R] receives the following
+environment variables:
+.IP \[bu] 2
+\f[C]$SRCDIR\f[R] contains the path to the sources to build.
+.IP \[bu] 2
+\f[C]$DESTDIR\f[R] is a directory into which any artifacts generated by
+the build script shall be placed.
+.IP \[bu] 2
+\f[C]$BUILDDIR\f[R] is only defined if \f[C]mkosi.builddir\f[R] and
+points to the build directory to use.
+This is useful for all build systems that support out-of-tree builds to
+reuse already built artifacts from previous runs.
+.IP \[bu] 2
+\f[C]$WITH_DOCS\f[R] is either \f[C]0\f[R] or \f[C]1\f[R] depending on
+whether a build without or with installed documentation was requested
+(\f[C]WithDocs=yes\f[R]).
+The build script should suppress installation of any package
+documentation to \f[C]$DESTDIR\f[R] in case \f[C]$WITH_DOCS\f[R] is set
+to \f[C]0\f[R].
+.IP \[bu] 2
+\f[C]$WITH_TESTS\f[R] is either \f[C]0\f[R]or \f[C]1\f[R] depending on
+whether a build without or with running the test suite was requested
+(\f[C]WithTests=no\f[R]).
+The build script should avoid running any unit or integration tests in
+case \f[C]$WITH_TESTS\f[R] is \f[C]0\f[R].
+.IP \[bu] 2
+\f[C]$WITH_NETWORK\f[R] is either \f[C]0\f[R]or \f[C]1\f[R] depending on
+whether a build without or with networking is being executed
+(\f[C]WithNetwork=no\f[R]).
+The build script should avoid any network communication in case
+\f[C]$WITH_NETWORK\f[R] is \f[C]0\f[R].
+.SH EXAMPLES
+.PP
+Create and run a raw \f[I]GPT\f[R] image with \f[I]ext4\f[R], as
+\f[C]image.raw\f[R]:
+.IP
+.nf
+\f[C]
+# mkosi --bootable --incremental boot
+\f[R]
+.fi
+.PP
+Create and run a bootable btrfs \f[I]GPT\f[R] image, as
+\f[C]foobar.raw\f[R]:
+.IP
+.nf
+\f[C]
+# mkosi --format gpt_btrfs --bootable -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 into a plain directory:
+.IP
+.nf
+\f[C]
+# mkosi --distribution fedora --format directory boot
+\f[R]
+.fi
+.PP
+Create a compressed image \f[C]image.raw.xz\f[R] and add a checksum
+file, and install \f[I]SSH\f[R] into it:
+.IP
+.nf
+\f[C]
+# mkosi --distribution fedora --format gpt_squashfs --checksum --compress --package=openssh-clients
+\f[R]
+.fi
+.PP
+Inside the source directory of an \f[C]automake\f[R]-based project,
+configure \f[I]mkosi\f[R] so that simply invoking \f[C]mkosi\f[R]
+without any parameters builds an OS image containing a built version of
+the project in its current state:
+.IP
+.nf
+\f[C]
+# cat >mkosi.default <<EOF
+[Distribution]
+Distribution=fedora
+Release=24
+
+[Output]
+Format=gpt_btrfs
+Bootable=yes
+
+[Content]
+Packages=openssh-clients,httpd
+BuildPackages=make,gcc,libcurl-devel
+EOF
+# cat >mkosi.build <<EOF
+#!/bin/sh
+cd $SRCDIR
+\&./autogen.sh
+\&./configure --prefix=/usr
+make -j \[ga]nproc\[ga]
+make install
+EOF
+# chmod +x mkosi.build
+# mkosi --bootable --incremental boot
+# systemd-nspawn -bi image.raw
+\f[R]
+.fi
+.PP
+To create a \f[I]Fedora Linux\f[R] image with hostname:
+.IP
+.nf
+\f[C]
+# mkosi --distribution fedora --hostname image
+\f[R]
+.fi
+.PP
+Also you could set hostname in configuration file:
+.IP
+.nf
+\f[C]
+# cat mkosi.default
+\&...
+[Output]
+Hostname=image
+\&...
+\f[R]
+.fi
+.SH REQUIREMENTS
+.PP
+mkosi is packaged for various distributions: Debian, Ubuntu, Arch Linux,
+Fedora Linux, OpenMandriva, Gentoo.
+It is usually easiest to use the distribution package.
+.PP
+The current version requires systemd 233 (or actually, systemd-nspawn of
+it).
+.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 arch-install-scripts btrfs-progs debootstrap dosfstools edk2-ovmf e2fsprogs squashfs-tools gnupg python3 tar veritysetup xfsprogs xz zypper sbsigntools
+\f[R]
+.fi
+.PP
+On Debian/Ubuntu it might be necessary to install the
+\f[C]ubuntu-keyring\f[R], \f[C]ubuntu-archive-keyring\f[R] and/or
+\f[C]debian-archive-keyring\f[R] packages explicitly, in addition to
+\f[C]debootstrap\f[R], depending on what kind of distribution images you
+want to build.
+\f[C]debootstrap\f[R] on Debian only pulls in the Debian keyring on its
+own, and the version on Ubuntu only the one from Ubuntu.
+.PP
+Note that the minimum required Python version is 3.7.
+.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 (http://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[C]systemd-nspawn(1)\f[R], \f[C]dnf(8)\f[R], \f[C]debootstrap(8)\f[R]
+.SH AUTHORS
+The mkosi Authors.