+++ /dev/null
-.\" Automatically generated by Pandoc 2.19.2
-.\"
-.\" Define V font for inline verbatim, using C font in formats
-.\" that render this, and otherwise B font.
-.ie "\f[CB]x\f[]"x" \{\
-. ftr V B
-. ftr VI BI
-. ftr VB B
-. ftr VBI BI
-.\}
-.el \{\
-. ftr V CR
-. ftr VI CI
-. ftr VB CB
-. ftr VBI CBI
-.\}
-.TH "mkosi" "1" "" "" ""
-.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 [script parameters\&...]\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\&...] clean\f[R]
-.PP
-\f[V]mkosi [options\&...] serve\f[R]
-.PP
-\f[V]mkosi [options\&...] bump\f[R]
-.PP
-\f[V]mkosi [options\&...] genkey\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.\[ga]
-.TP
-\f[V]build\f[R]
-This builds the image based on the settings passed in on the command
-line or read from a \f[V]mkosi.conf\f[R] file.
-This command is the default if no verb is explicitly specified.
-This command must be executed as \f[V]root\f[R].
-Any arguments passed after the \f[V]build\f[R] verb are passed as
-arguments to the build script (if there is one).
-.TP
-\f[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 is then passed as the \[lq]kernel command line\[rq] 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.
-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 (\f[V]boot\f[R], \f[V]qemu\f[R] verbs) container or
-VM via SSH.
-Make sure to run \f[V]mkosi ssh\f[R] with the same config as
-\f[V]mkosi build\f[R] was run with so that it has the necessary
-information available to connect to the running container/VM via SSH.
-Any arguments passed after the \f[V]ssh\f[R] verb are passed as
-arguments to the \f[V]ssh\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]bump\f[R]
-Determines the current image version string (as configured with
-\f[V]ImageVersion=\f[R]/\f[V]--image-version=\f[R]), increases its last
-dot-separated component by one and writes the resulting version string
-to \f[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]help\f[R]
-This verb is equivalent to the \f[V]--help\f[R] switch documented below:
-it shows a brief usage explanation.
-.SS Execution Flow
-.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 \[bu] 2
-Copy skeleton trees (\f[V]mkosi.skeleton\f[R]) into image
-.IP \[bu] 2
-Install distribution and packages into image or use cache tree if
-available
-.IP \[bu] 2
-Install build packages in overlay if a build script is configured
-.IP \[bu] 2
-Run prepare script on image and on image + build overlay if a build
-script is configured (\f[V]mkosi.prepare\f[R])
-.IP \[bu] 2
-Run build script on image + build overlay if a build script is
-configured (\f[V]mkosi.build\f[R])
-.IP \[bu] 2
-Copy the build script outputs into the image
-.IP \[bu] 2
-Copy the extra trees into the image (\f[V]mkosi.extra\f[R])
-.IP \[bu] 2
-Run \f[V]kernel-install\f[R]
-.IP \[bu] 2
-Install systemd-boot
-.IP \[bu] 2
-Run post-install script (\f[V]mkosi.postinst\f[R])
-.IP \[bu] 2
-Run \f[V]systemctl preset-all\f[R]
-.IP \[bu] 2
-Remove packages and files (\f[V]RemovePackages=\f[R],
-\f[V]RemoveFiles=\f[R])
-.IP \[bu] 2
-Run finalize script (\f[V]mkosi.finalize\f[R])
-.IP \[bu] 2
-Run SELinux relabel is a SELinux policy is installed
-.IP \[bu] 2
-Generate unified kernel image
-.IP \[bu] 2
-Generate final output format
-.SS Supported output formats
-.PP
-The following output formats are supported:
-.IP \[bu] 2
-Raw \f[I]GPT\f[R] disk image, created using systemd-repart
-.IP \[bu] 2
-Plain directory, containing the OS tree (\f[I]directory\f[R])
-.IP \[bu] 2
-btrfs subvolume
-.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, repart partition definition
-files may be placed in \f[V]mkosi.repart/\f[R] to configure the
-generated disk image.
-.SS Configuration Settings
-.PP
-The following settings can be set through configuration files (the
-syntax with \f[V]SomeSetting=value\f[R]) and on the command line (the
-syntax with \f[V]--some-setting=value\f[R]).
-For some command line parameters, a single-letter shortcut is also
-allowed.
-In the configuration files, the setting must be in the appropriate
-section, so the settings are grouped by section below.
-.PP
-Configuration is parsed in the following order:
-.IP \[bu] 2
-The command line arguments are parsed
-.IP \[bu] 2
-\f[V]mkosi.conf\f[R] is parsed if it exists in the directory set with
-\f[V]--directory=\f[R] or the current working directory if
-\f[V]--directory=\f[R] is not used.
-.IP \[bu] 2
-\f[V]mkosi.conf.d/\f[R] is parsed in the same directory if it exists.
-Each directory and each file with the \f[V].conf\f[R] extension in
-\f[V]mkosi.conf.d/\f[R] is parsed.
-Any directory in \f[V]mkosi.conf.d\f[R] is parsed as if it were a
-regular top level directory.
-.IP \[bu] 2
-Any default paths (depending on the option) are configured if the
-corresponding path exists.
-.PP
-If a setting is specified multiple times across the different sources of
-configuration, the first assignment that is found is used.
-For example, a setting specified on the command line will always take
-precedence over the same setting configured in a config file.
-To override settings in a dropin file, make sure your dropin file is
-alphanumerically ordered before the config file that you\[cq]re trying
-to override.
-.PP
-Settings that take a list of values are merged by prepending each value
-to the previously configured values.
-If a value of a list setting is prefixed with \f[V]!\f[R], if any later
-assignment of that setting tries to add the same value, that value is
-ignored.
-Values prefixed with \f[V]!\f[R] can be globs to ignore more than one
-value.
-.PP
-To conditionally include configuration files, the \f[V][Match]\f[R]
-section can be used.
-A configuration file is only included if all the conditions in the
-\f[V][Match]\f[R] block are satisfied.
-If a condition in \f[V][Match]\f[R] depends on a setting and the setting
-has not been explicitly configured when the condition is evaluated, the
-setting is assigned its default value.
-.PP
-Command line options that take no argument are shown without \[lq]=\[rq]
-in their long version.
-In the config files, they should be specified with a boolean argument:
-either \[lq]1\[rq], \[lq]yes\[rq], or \[lq]true\[rq] to enable, or
-\[lq]0\[rq], \[lq]no\[rq], \[lq]false\[rq] to disable.
-.SS [Match] Section.
-.TP
-\f[V]Distribution=\f[R]
-Matches against the configured distribution.
-.TP
-\f[V]Release=\f[R]
-Matches against the configured distribution release.
-If this condition is used and no distribution has been explicitly
-configured yet, the host distribution and release are used.
-.TP
-\f[V]PathExists=\f[R]
-This condition is satisfied if the given path exists.
-Relative paths are interpreted relative to the parent directory of the
-config file that the condition is read from.
-.SS [Distribution] Section
-.TP
-\f[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]openmandriva\f[R],
-\f[V]rocky\f[R], and \f[V]alma\f[R].
-If not specified, defaults to the distribution of the host.
-Whenever a distribution is assigned, the release is reset to the default
-release configured for that distribution.
-.TP
-\f[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.
-.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.
-.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]
-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[V]<name>::<url>\f[R] (e.g.\ \f[V]myrepo::https://myrepo.net\f[R]).
-.TP
-\f[V]RepositoryDirectories\f[R], \f[V]--repo-dir=\f[R]
-This option can (for now) only be used with RPM-based distributions and
-Arch Linux.
-It takes a comma separated list of directories containing extra
-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[V]Architecture=\f[R], \f[V]--architecture=\f[R]
-The architecture to build the image for.
-Note that this currently only works for architectures compatible with
-the host\[cq]s architecture.
-.SS [Output] Section
-.TP
-\f[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 OS images inside a local
-directory), \f[V]subvolume\f[R] (similar, but as a btrfs subvolume),
-\f[V]tar\f[R] (similar, but a tarball of the image is generated),
-\f[V]cpio\f[R] (similar, but a cpio archive is generated),
-\f[V]disk\f[R] (a block device image with a GPT partition table).
-.TP
-\f[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).
-Defaults to \f[V]json\f[R].
-.TP
-\f[V]Output=\f[R], \f[V]--output=\f[R], \f[V]-o\f[R]
-Path for the output image file to generate.
-Takes a relative or absolute path where the generated image will be
-placed.
-If neither this option nor \f[V]OutputDirectory=\f[R] is used, the image
-is generated under the name \f[V]image\f[R], but its name suffixed with
-an appropriate file suffix (e.g.\ \f[V]image.raw.xz\f[R] in case
-\f[V]gpt_ext4\f[R] is used in combination with \f[V]xz\f[R]
-compression).
-If the \f[V]ImageId=\f[R] option is configured it is used instead of
-\f[V]image\f[R] in the default output name.
-If an image version is specified via \f[V]ImageVersion=\f[R], it is
-included in the default name, e.g.\ a specified image version of
-\f[V]7.8\f[R] might result in an image file name of
-\f[V]image_7.8.raw.xz\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 (i.e.\ the
-generated image when an output path is not given, \f[V]SHA256SUMS\f[R]
-file, etc.).
-If this is not specified and the directory \f[V]mkosi.output/\f[R]
-exists in the local directory, it is automatically used for this
-purpose.
-If the setting is not used and \f[V]mkosi.output/\f[R] does not exist,
-all output artifacts are placed adjacent to the output image file.
-If an output directory is configured, mkosi will create
-\f[V]distro\[ti]release\f[R] subdirectories in it to store the
-artfifacts per distro, release combination that\[cq]s built.
-.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, and \f[V]mkosi.workspace/\f[R] exists in the local
-directory, it is used for this purpose.
-Otherwise, hidden subdirectories of the current working directory are
-used.
-The data in this directory is removed automatically after each build.
-It\[cq]s safe to manually remove the contents of this directory should
-an \f[V]mkosi\f[R] invocation be aborted abnormally (for example, due to
-reboot/power failure).
-.TP
-\f[V]Force=\f[R], \f[V]--force\f[R], \f[V]-f\f[R]
-Replace the output file if it already exists, when building an image.
-By default when building an image and an output artifact already exists
-\f[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 \[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[V]clean\f[R] operation this option has a slightly different
-effect: by default the verb will only remove build artifacts from a
-previous run, when specified once the incremental cache files are
-deleted too, and when specified twice the package cache is also removed.
-.PP
-.TP
-\f[V]Bootable=\f[R], \f[V]--bootable=\f[R]
-Takes a boolean or \f[V]auto\f[R].
-Enables or disable generating of a bootable image.
-If enabled, mkosi will install systemd-boot, run kernel-install,
-generate unified kernel images for installed kernels and add an ESP
-partition when the disk image output is used.
-If systemd-boot is not installed or no kernel images can be found, the
-build will fail.
-\f[V]auto\f[R] behaves as if the option was enabled, but the build
-won\[cq]t fail if either no kernel images or systemd-boot can\[cq]t be
-found.
-If disabled, systemd-boot won\[cq]t be installed even if found inside
-the image, kernel-install won\[cq]t be executed, no unified kernel
-images will be generated and no ESP partition will be added to the image
-if the disk output format is used.
-.TP
-\f[V]KernelCommandLine=\f[R], \f[V]--kernel-command-line=\f[R]
-Use the specified kernel command line when building images.
-By default command line arguments get appended.
-To remove all arguments from the current list pass \[lq]!*\[rq].
-To remove specific arguments add a space separated list of \[lq]!\[rq]
-prefixed arguments.
-For example adding \[lq]!* console=ttyS0 rw\[rq] to a
-\f[V]mkosi.conf\f[R] file or the command line arguments passes
-\[lq]console=ttyS0 rw\[rq] to the kernel in any case.
-Just adding \[lq]console=ttyS0 rw\[rq] would append these two arguments
-to the kernel command line created by lower priority configuration files
-or previous \f[V]KernelCommandLine=\f[R] command line arguments.
-.TP
-\f[V]SecureBoot=\f[R], \f[V]--secure-boot\f[R]
-Sign the resulting kernel/initrd image for UEFI SecureBoot.
-.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]SecureBootCommonName=\f[R], \f[V]--secure-boot-common-name=\f[R]
-Common name to be used when generating SecureBoot keys via mkosi\[cq]s
-\f[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]SecureBootValidDays=\f[R], \f[V]--secure-boot-valid-days=\f[R]
-Number of days that the keys should remain valid when generating
-SecureBoot keys via mkosi\[cq]s \f[V]genkey\f[R] command.
-Defaults to two years (730 days).
-.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]cryptography\f[R] (https://cryptography.io/) module is importable
-and the \f[V]systemd-measure\f[R] binary is in \f[V]PATH\f[R].
-.TP
-\f[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]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[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] and \f[V]cpio\f[R].
-.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]AutoBump=\f[R], \f[V]--auto-bump=\f[R], \f[V]-B\f[R]
-If specified, after each successful build the the version is bumped in a
-fashion equivalent to the \f[V]bump\f[R] verb, in preparation for the
-next build.
-This is useful for simple, linear version management: each build in a
-series will have a version number one higher then the previous one.
-.TP
-\f[V]ImageId=\f[R], \f[V]--image-id=\f[R]
-Configure the image identifier.
-This accepts a freeform string that shall be used to identify the image
-with.
-If set the default output file will be named after it (possibly suffixed
-with the version).
-If this option is used the root, \f[V]/usr/\f[R] and Verity partitions
-in the image will have their labels set to this (possibly suffixed by
-the image version).
-The identifier is also passed via the \f[V]$IMAGE_ID\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_ID=\f[R] field of it).
-.TP
-\f[V]CacheInitrd=\f[R], \f[V]--cache-initrd\f[R]
-If specified, and incremental mode is used, mkosi will build the initrd
-in the cache image and reuse it in the final image.
-Note that this means that any changes that are only applied to the final
-image and not the cached image won\[cq]t be included in the initrd.
-.TP
-\f[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]RepartDirectory=\f[R], \f[V]--repart-dir=\f[R]
-Path to a directory containing systemd-repart partition definition files
-that are used when mkosi invokes systemd-repart when building a disk
-image.
-If not specified and \f[V]mkosi.repart/\f[R] exists in the local
-directory, it will be used instead.
-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]TarStripSELinuxContext=\f[R], \f[V]--tar-strip-selinux-context\f[R]
-If running on a SELinux-enabled system (Fedora Linux, CentOS, Rocky
-Linux, Alma Linux), files inside the container are tagged with SELinux
-context extended attributes (\f[V]xattrs\f[R]), which may interfere with
-host SELinux rules in building or further container import stages.
-This option strips SELinux context attributes from the resulting tar
-archive.
-.TP
-\f[V]Initrd=\f[R], \f[V]--initrd\f[R]
-Use user-provided initrd(s).
-Takes a comma separated list of paths to initrd files.
-This option may be used multiple times in which case the initrd lists
-are combined.
-.SS [Content] Section
-.TP
-\f[V]Packages=\f[R], \f[V]--package=\f[R], \f[V]-p\f[R]
-Install the specified distribution packages (i.e.\ RPM, DEB, \&...)
-in the image.
-Takes a comma separated list of package specifications.
-This option may be used multiple times in which case the specified
-package lists are combined.
-Packages specified this way will be installed both in the development
-and the final image.
-Use \f[V]BuildPackages=\f[R] to specify packages that shall only be used
-for the image generated in the build image, but that shall not appear in
-the final image.
-The types and syntax of \[lq]package specifications\[rq] that are
-allowed depend on the package installer (e.g.\ \f[V]dnf\f[R] or
-\f[V]yum\f[R] for \f[V]rpm\f[R]-based distros or \f[V]apt\f[R] for
-\f[V]deb\f[R]-based distros), but may include package names, package
-names with version and/or architecture, package name globs, paths to
-packages in the file system, package groups, and virtual provides,
-including file paths.
-To remove a package e.g.\ added by a \f[V]mkosi.conf\f[R] configuration
-file prepend the package name with \f[V]!\f[R].
-For example -p \[lq]!apache2\[rq] would remove the apache2 package.
-To replace the apache2 package by the httpd package just add -p
-\[lq]!apache2,httpd\[rq] to the command line arguments.
-To remove all packages use \[lq]!*\[rq].
-Example: when using an distro that uses \f[V]dnf\f[R],
-\f[V]Packages=meson libfdisk-devel.i686 git-* prebuilt/rpms/systemd-249-rc1.local.rpm /usr/bin/ld \[at]development-tools python3dist(mypy)\f[R]
-would install the \f[V]meson\f[R] package (in the latest version), the
-32-bit version of the \f[V]libfdisk-devel\f[R] package, all available
-packages that start with the \f[V]git-\f[R] prefix, a \f[V]systemd\f[R]
-rpm from the local file system, one of the packages that provides
-\f[V]/usr/bin/ld\f[R], the packages in the \[lq]Development Tools\[rq]
-group, and the package that contains the \f[V]mypy\f[R] python module.
-.TP
-\f[V]WithDocs=\f[R], \f[V]--with-docs\f[R]
-Include documentation in the image built.
-By default if the underlying distribution package manager supports it
-documentation is not included in the image built.
-The \f[V]$WITH_DOCS\f[R] environment variable passed to the
-\f[V]mkosi.build\f[R] script indicates whether this option was used or
-not.
-.TP
-\f[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] 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[V]mkosi.build\f[R]
-build script honors it.
-.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.
-The directory configured this way is mounted into both the development
-and the final image while the package manager is running.
-.TP
-\f[V]SkeletonTree=\f[R], \f[V]--skeleton-tree=\f[R]
-Takes a colon separated pair of paths.
-The first path refers to a directory to copy into the OS tree before
-invoking the package manager.
-The second path refers to the target directory inside the image.
-If the second path is not provided, the directory is copied on top of
-the root directory of the image.
-Use this to insert files and directories into the OS tree before the
-package manager installs any packages.
-If this option is not used, but the \f[V]mkosi.skeleton/\f[R] directory
-is found in the local directory it is automatically used for this
-purpose with the root directory as target (also see the \[lq]Files\[rq]
-section below).
-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[V]git\f[R] which retain full file ownership and access
-mode metadata for committed files.
-If the tar file \f[V]mkosi.skeleton.tar\f[R] is found in the local
-directory it will be automatically used for this purpose.
-.TP
-\f[V]ExtraTree=\f[R], \f[V]--extra-tree=\f[R]
-Takes a colon separated pair of paths.
-The first path refers to a directory to copy from the host into the
-image.
-The second path refers to the target directory inside the image.
-If the second path is not provided, the directory is copied on top of
-the root directory of the image.
-Use this to override any default configuration files shipped with the
-distribution.
-If this option is not used, but the \f[V]mkosi.extra/\f[R] directory is
-found in the local directory it is automatically used for this purpose
-with the root directory as target.
-(also see the \[lq]Files\[rq] section below).
-As with the skeleton tree logic above, instead of a directory, a tar
-file may be provided too.
-\f[V]mkosi.skeleton.tar\f[R] will be automatically used if found in the
-local directory.
-.TP
-\f[V]CleanPackageMetadata=\f[R], \f[V]--clean-package-metadata=\f[R]
-Enable/disable removal of package manager databases, caches, and logs at
-the end of installation.
-Can be specified as true, false, or \[lq]\f[V]auto\f[R]\[rq] (the
-default).
-With \[lq]\f[V]auto\f[R]\[rq], files will be removed if the respective
-package manager executable is \f[I]not\f[R] present at the end of the
-installation.
-.TP
-\f[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]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.
-This option is currently only implemented for distributions using
-\f[V]dnf\f[R].
-.TP
-\f[V]Environment=\f[R], \f[V]--environment=\f[R]
-Adds variables to the environment that the
-build/prepare/postinstall/finalize scripts are executed with.
-Takes a space-separated list of variable assignments or just variable
-names.
-In the latter case, the values of those variables will be passed through
-from the environment in which \f[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]BuildSources=\f[R], \f[V]--build-sources=\f[R]
-Takes a path to a source tree to mount into the development image, if
-the build script is used.
-.TP
-\f[V]BuildDirectory=\f[R], \f[V]--build-dir=\f[R]
-Takes a path of a directory to use as build directory for build systems
-that support out-of-tree builds (such as Meson).
-The directory used this way is shared between repeated builds, and
-allows the build system to reuse artifacts (such as object files,
-executable, \&...)
-generated on previous invocations.
-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[V]$BUILDDIR\f[R] environment variable.
-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 \[lq]Files\[rq]
-section below).
-.TP
-\f[V]InstallDirectory=\f[R], \f[V]--install-dir=\f[R]
-Takes a path of a directory to use as the install directory.
-The directory used this way is shared between builds and allows the
-build system to not have to reinstall files that were already installed
-by a previous build and didn\[cq]t change.
-The build script can find the path to this directory in the
-\f[V]$DESTDIR\f[R] environment variable.
-If this option is not specified, but a directory
-\f[V]mkosi.installdir\f[R] exists in the local directory, it is
-automatically used for this purpose (also see the \[lq]Files\[rq]
-section below).
-.TP
-\f[V]BuildPackages=\f[R], \f[V]--build-package=\f[R]
-Similar to \f[V]Packages=\f[R], but configures packages to install only
-in the first phase of the build, into the development image.
-This option should be used to list packages containing header files,
-compilers, build systems, linkers and other build tools the
-\f[V]mkosi.build\f[R] script requires to operate.
-Note that packages listed here are only included in the image created
-during the first phase of the build, and are absent in the final image.
-Use \f[V]Packages=\f[R] to list packages that shall be included in both.
-Packages are appended to the list.
-Packages prefixed with \[lq]!\[rq] are removed from the list.
-\[lq]!*\[rq] removes all packages from the list.
-.TP
-\f[V]Password=\f[R], \f[V]--password=\f[R]
-Set the password of the \f[V]root\f[R] user.
-By default the \f[V]root\f[R] account is locked.
-If this option is not used, but a file \f[V]mkosi.rootpw\f[R] exists in
-the local directory, the root password is automatically read from it.
-.TP
-\f[V]PasswordIsHashed=\f[R], \f[V]--password-is-hashed\f[R]
-Indicate that the password supplied for the \f[V]root\f[R] user has
-already been hashed, so that the string supplied with
-\f[V]Password=\f[R] or \f[V]mkosi.rootpw\f[R] will be written to
-\f[V]/etc/shadow\f[R] literally.
-.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/hvc0\f[R].
-.TP
-\f[V]BuildScript=\f[R], \f[V]--build-script=\f[R]
-Takes a path to an executable that is used as build script for this
-image.
-The specified script is copied onto the development image and executed
-inside a namespaced chroot environment.
-If this option is not used, but the \f[V]mkosi.build\f[R] file found in
-the local directory it is automatically used for this purpose (also see
-the \[lq]Files\[rq] section below).
-Specify an empty value to disable automatic detection.
-.TP
-\f[V]PrepareScript=\f[R], \f[V]--prepare-script=\f[R]
-Takes a path to an executable that is invoked inside the image right
-after installing the software packages.
-It is the last step before the image is cached (if incremental mode is
-enabled).
-This script is invoked inside a namespaced chroot environment, and thus
-does not have access to host resources.
-If this option is not used, but an executable script
-\f[V]mkosi.prepare\f[R] is found in the local directory, it is
-automatically used for this purpose.
-Specify an empty value to disable automatic detection.
-.TP
-\f[V]PostInstallationScript=\f[R], \f[V]--postinst-script=\f[R]
-Takes a path to an executable that is invoked inside the final image
-right after copying in the build artifacts generated in the first phase
-of the build.
-This script is invoked inside a namespaced chroot environment, and thus
-does not have access to host resources.
-If this option is not used, but an executable \f[V]mkosi.postinst\f[R]
-is found in the local directory, it is automatically used for this
-purpose.
-Specify an empty value to disable automatic detection.
-.TP
-\f[V]FinalizeScript=\f[R], \f[V]--finalize-script=\f[R]
-Takes a path to an executable that is invoked outside the final image
-right after copying in the build artifacts generated in the first phase
-of the build, and after having executed the \f[V]mkosi.postinst\f[R]
-script (see \f[V]PostInstallationScript=\f[R]).
-This script is invoked directly in the host environment, and hence has
-full access to the host\[cq]s resources.
-If this option is not used, but an executable \f[V]mkosi.finalize\f[R]
-is found in the local directory, it is automatically used for this
-purpose.
-Specify an empty value to disable automatic detection.
-.TP
-\f[V]WithNetwork=\f[R], \f[V]--with-network=\f[R]
-When true, enables network connectivity while the build script
-\f[V]mkosi.build\f[R] is invoked.
-By default, the build script runs with networking turned off.
-The \f[V]$WITH_NETWORK\f[R] environment variable is passed to the
-\f[V]mkosi.build\f[R] build script indicating whether the build is done
-with or without network.
-.TP
-\f[V]CacheOnly=\f[R], \f[V]--cache-only=\f[R]
-If specified, the package manager is instructed not to contact the
-network for updating package data.
-This provides a minimal level of reproducibility, as long as the package
-data cache is already fully populated.
-.TP
-\f[V]Settings=\f[R], \f[V]--settings=\f[R]
-Specifies a \f[V].nspawn\f[R] settings file for \f[V]systemd-nspawn\f[R]
-to use in the \f[V]boot\f[R] and \f[V]shell\f[R] verbs, and to place
-next to the generated image file.
-This is useful to configure the \f[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]BaseImage=\f[R], \f[V]--base-image=\f[R]
-Use the specified directory or file system image as the base image, and
-create the output image that consists only of changes from this base.
-The base image is attached as the lower file system in an overlayfs
-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.
-.SS [Validation] Section
-.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]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]1G\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.
-Defaults to yes if the host machine supports KVM acceleration, no
-otherwise.
-.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 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[V]Ssh=\f[R], \f[V]--ssh\f[R]
-If specified, an sshd socket unit and matching service are installed in
-the final image that expose sshd over VSock.
-When building with this option and running the image using
-\f[V]mkosi qemu\f[R], the \f[V]mkosi ssh\f[R] command can be used to
-connect to the container/VM via SSH.
-Note that you still have to make sure openssh is installed in the image
-to make this option behave correctly.
-Also note that mkosi doesn\[cq]t provision a public SSH key into the
-image automatically.
-One way to do this is by setting the \f[V]ssh.authorized_keys.root\f[R]
-credential using the \f[V]Credential=\f[R] option or by copying it in
-using \f[V]ExtraTrees=\f[R].
-To access images booted using \f[V]mkosi boot\f[R], use
-\f[V]machinectl\f[R].
-.TP
-\f[V]Credentials=\f[R], \f[V]--credential=\f[R]
-Set credentials to be passed to systemd-nspawn or qemu respectively when
-\f[V]mkosi shell/boot\f[R] or \f[V]mkosi qemu\f[R] are used.
-This option takes a space separated list of key=value assignments.
-.TP
-\f[V]KernelCommandLineExtra=\f[R], \f[V]--kernel-command-line-extra=\f[R]
-Set extra kernel command line entries that are appended to the kernel
-command line at runtime when booting the image.
-When booting in a container, these are passed as extra arguments to
-systemd.
-When booting in a VM, these are appended to the kernel command line via
-the SMBIOS io.systemd.stub.kernel-cmdline-extra OEM string.
-This will only be picked up by systemd-boot/systemd-stub versions newer
-than or equal to v254.
-.TP
-\f[V]Acl=\f[R], \f[V]--acl=\f[R]
-If specified, ACLs will be set on any generated root filesystem
-directories that allow the user running mkosi to remove them without
-needing privileges.
-.SS Commandline-only Options
-.PP
-Those settings cannot be configured in the configuration files.
-.TP
-\f[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 \f[V]mkosi.*\f[R] files are searched for only
-after changing to this directory, hence using this option is an
-effective way to build a project located in a specific directory.
-.TP
-\f[V]--config=\f[R]
-Loads additional settings from the specified settings file.
-Most command line options may also be configured in a settings file.
-See the table below to see which command line options match which
-settings file option.
-If this option is not used, but a file \f[V]mkosi.conf\f[R] is found in
-the local directory it is automatically used for this purpose.
-If a setting is configured both on the command line and in the settings
-file, the command line generally wins, except for options taking lists
-in which case both lists are combined.
-.TP
-\f[V]--incremental\f[R], \f[V]-i\f[R]
-Enable incremental build mode.
-This only applies if the two-phase \f[V]mkosi.build\f[R] build script
-logic is used.
-In this mode, a copy of the OS image is created immediately after all OS
-packages are unpacked but before the \f[V]mkosi.build\f[R] script is
-invoked in the development container.
-Similarly, a copy of the final image is created immediately before the
-build artifacts from the \f[V]mkosi.build\f[R] script are copied in.
-On subsequent invocations of \f[V]mkosi\f[R] with the \f[V]-i\f[R]
-switch these cached images may be used to skip the OS package unpacking,
-thus drastically speeding up repetitive build times.
-Note that when this is used and a pair of cached incremental images
-exists they are not automatically regenerated, even if options such as
-\f[V]Packages=\f[R] are modified.
-In order to force rebuilding of these cached images, combine
-\f[V]-i\f[R] with \f[V]-ff\f[R] to ensure cached images are first
-removed and then re-created.
-.TP
-\f[V]--debug=\f[R]
-Enable additional debugging output.
-Takes a comma-separated list of arguments specifying the area of
-interest.
-Pass any invalid value (e.g.\ empty) to list currently accepted values.
-.TP
-\f[V]--version\f[R]
-Show package version.
-.TP
-\f[V]--help\f[R], \f[V]-h\f[R]
-Show brief usage information.
-.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]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[V]apt\f[R] may be used
-to build \f[I]Debian\f[R] or \f[I]Ubuntu\f[R] images.
-Any distribution that packages \f[V]dnf\f[R] may be used to build
-\f[I]CentOS\f[R], \f[I]Alma Linux\f[R], \f[I]Rocky Linux\f[R],
-\f[I]Fedora Linux\f[R], \f[I]Mageia\f[R] or \f[I]OpenMandriva\f[R]
-images.
-Any distro that packages \f[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.
-Any distribution that packages \f[V]emerge\f[R] may be used to build
-\f[I]Gentoo\f[R] images.
-.PP
-Currently, \f[I]Fedora Linux\f[R] packages all relevant tools as of
-Fedora 28.
-.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.conf\f[B]\f[R] file provides the default
-configuration for the image building process.
-For example, it may specify the distribution to use (\f[V]fedora\f[R],
-\f[V]ubuntu\f[R], \f[V]debian\f[R], \f[V]arch\f[R], \f[V]opensuse\f[R],
-\f[V]mageia\f[R], \f[V]openmandriva\f[R], \f[V]gentoo\f[R]) for the
-image, or additional distribution packages to install.
-Note that all options encoded in this configuration file may also be set
-on the command line, and this file is hence little more than a way to
-make sure invoking \f[V]mkosi\f[R] without further parameters in your
-\f[I]source\f[R] tree is enough to get the right image of your choice
-set up.
-.RS 2
-.PP
-Additionally, if a \f[I]\f[VI]mkosi.conf.d/\f[I]\f[R] directory exists,
-each file in it is loaded in the same manner adding/overriding the
-values specified in \f[V]mkosi.conf\f[R].
-If \f[V]mkosi.conf.d/\f[R] contains a directory named after the
-distribution being built, each file in that directory is also processed.
-.PP
-The file format is inspired by Windows \f[V].ini\f[R] files and supports
-multi-line assignments: any line with initial whitespace is considered a
-continuation line of the line before.
-Command-line arguments, as shown in the help description, have to be
-included in a configuration block (e.g.\ \[lq]\f[V][Content]\f[R]\[rq])
-corresponding to the argument group (e.g.\ \[lq]\f[V]Content\f[R]\[rq]),
-and the argument gets converted as follows:
-\[lq]\f[V]--with-network\f[R]\[rq] becomes
-\[lq]\f[V]WithNetwork=yes\f[R]\[rq].
-For further details see the table above.
-.RE
-.IP \[bu] 2
-The \f[B]\f[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
-\f[B]\f[VB]mkosi.build\f[B]\f[R] may be an executable script.
-If it exists, the image will be built twice: the first iteration will be
-the \f[I]development\f[R] image, the second iteration will be the
-\f[I]final\f[R] image.
-The \f[I]development\f[R] image is used to build the project in the
-current working directory (the \f[I]source\f[R] tree).
-For that the whole directory is copied into the image, along with the
-\f[V]mkosi.build\f[R] script.
-The script is then invoked inside the image, with \f[V]$SRCDIR\f[R]
-pointing to the \f[I]source\f[R] tree.
-\f[V]$DESTDIR\f[R] points to a directory where the script should place
-any files generated it would like to end up in the \f[I]final\f[R]
-image.
-Note that \f[V]make\f[R]/\f[V]automake\f[R]/\f[V]meson\f[R] based build
-systems generally honor \f[V]$DESTDIR\f[R], thus making it very natural
-to build \f[I]source\f[R] trees from the build script.
-After the \f[I]development\f[R] image was built and the build script ran
-inside of it, it is removed again.
-After that the \f[I]final\f[R] image is built, without any
-\f[I]source\f[R] tree or build script copied in.
-However, this time the contents of \f[V]$DESTDIR\f[R] are added into the
-image.
-.RS 2
-.PP
-When the source tree is copied into the \f[I]build\f[R] image, all files
-are copied, except for \f[V]mkosi.builddir/\f[R], \f[V]mkosi.cache/\f[R]
-and \f[V]mkosi.output/\f[R].
-That said, \f[V].gitignore\f[R] is respected if the source tree is a
-\f[V]git\f[R] checkout.
-If multiple different images shall be built from the same source tree it
-is essential to exclude their output files from this copy operation, as
-otherwise a version of an image built earlier might be included in a
-later build, which is usually not intended.
-An alternative to excluding these built images via \f[V].gitignore\f[R]
-entries is to use the \f[V]mkosi.output/\f[R] directory, which is an
-easy way to exclude all build artifacts.
-.PP
-The \f[V]$MKOSI_CONFIG\f[R] environment variable will be set inside of
-this script so that you know which \f[V]mkosi.conf\f[R] (if any) was
-passed in.
-.RE
-.IP \[bu] 2
-The \f[B]\f[VB]mkosi.prepare\f[B]\f[R] script is invoked directly after
-the software packages are installed, from within the image context, if
-it exists.
-It is once called for the \f[I]development\f[R] image (if this is
-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[V]pip\f[R], \f[V]npm\f[R], \&...), after all software packages
-are installed but before the image is cached (if incremental mode is
-enabled).
-This script is executed within \f[V]$SRCDIR\f[R].
-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
-The \f[B]\f[VB]mkosi.postinst\f[B]\f[R] script is invoked as the
-penultimate step of preparing an image, from within the image context,
-if it exists.
-It is called first for the \f[I]development\f[R] image (if this is
-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[V]$SRCDIR\f[R]/\f[V]$DESTDIR\f[R] setup.
-.IP \[bu] 2
-The \f[B]\f[VB]mkosi.finalize\f[B]\f[R] script, if it exists, is invoked
-as last step of preparing an image, from the host system.
-It is once called for the \f[I]development\f[R] image (if this is
-enabled, see above) with the \[lq]build\[rq] command line parameter, as
-the last step before invoking the build script, after the
-\f[V]mkosi.postinst\f[R] script is invoked.
-It is called the second time with the \[lq]final\[rq] command line
-parameter as the last step before the image is considered complete.
-The environment variable \f[V]$BUILDROOT\f[R] points to the root
-directory of the installation image.
-Additional verbs may be added in the future, the script should be
-prepared for that.
-This script may be used to alter the images without any restrictions,
-after all software packages and built sources have been installed.
-This script is more flexible than \f[V]mkosi.postinst\f[R] in two
-regards: it has access to the host file system so it\[cq]s easier to
-copy in additional files or to modify the image based on external
-configuration, and the script is run in the host, so it can be used even
-without emulation even if the image has a foreign architecture.
-.IP \[bu] 2
-The \f[B]\f[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] script 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 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[V]mkosi\f[R]
-is used in incremental mode (\f[V]-i\f[R]): not only the disk images,
-but also the build tree is reused between subsequent invocations.
-Note that if this directory does not exist the \f[V]$BUILDDIR\f[R]
-environment variable is not set, and it is up to build script to decide
-whether to do in in-tree or an out-of-tree build, and which build
-directory to use.
-.IP \[bu] 2
-The \f[B]\f[VB]mkosi.includedir/\f[B]\f[R] directory, if it exists, is
-automatically used as an out-of-tree include directory for header files.
-Specifically, it will be mounted in the build container at
-\f[V]/usr/include/\f[R] when building the build image and when running
-the build script.
-After building the (cached) build image, this directory will contain all
-the files installed to \f[V]/usr/include\f[R].
-Language servers or other tools can use these files to provide a better
-editing experience for developers working on a project.
-.IP \[bu] 2
-The \f[B]\f[VB]mkosi.installdir/\f[B]\f[R] directory, if it exists, is
-automatically used as the install directory.
-Specifically, this directory will be mounted into the container at
-\f[V]/root/dest\f[R] when running the build script.
-After running the build script, the contents of this directory are
-installed into the final image.
-This is useful to cache the install step of the build.
-If used, subsequent builds will only have to reinstall files that have
-changed since the previous build.
-.IP \[bu] 2
-The \f[B]\f[VB]mkosi.rootpw\f[B]\f[R] file can be used to provide the
-password or hashed password (if \f[V]--password-is-hashed\f[R] is set)
-for the root user of the image.
-The password may optionally be followed by a newline character which is
-implicitly removed.
-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.
-If this file does not exist and encryption is requested, the user is
-queried instead.
-.IP \[bu] 2
-The \f[B]\f[VB]mkosi.secure-boot.crt\f[B]\f[R] and
-\f[B]\f[VB]mkosi.secure-boot.key\f[B]\f[R] files contain an X.509
-certificate and PEM private key to use when UEFI SecureBoot support is
-enabled.
-All EFI binaries included in the image\[cq]s ESP are signed with this
-key, as a late step in the build process.
-.IP \[bu] 2
-The \f[B]\f[VB]mkosi.output/\f[B]\f[R] directory will be used for all
-build artifacts, if the image output path is not configured (i.e.\ no
-\f[V]--output=\f[R] setting specified), or configured to a filename
-(i.e.\ a path containing no \f[V]/\f[R] character).
-This includes the image itself, the root hash file in case Verity is
-used, the checksum and its signature if that\[cq]s enabled, and the
-nspawn settings file if there is any.
-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[VB]mkosi.reposdir/\f[B]\f[R] directory, if it exists, is
-automatically used as the repository directory for extra repository
-files.
-See the \f[V]RepositoryDirectories\f[R] option for more information.
-.IP \[bu] 2
-The \f[B]\f[VB]mkosi.credentials/\f[B]\f[R] directory is used as a
-source of extra credentials similar to the \f[V]Credentials=\f[R]
-option.
-For each file in the directory, the filename will be used as the
-credential name and the file contents become the credential value, or,
-if the file is executable, mkosi will execute the file and the
-command\[cq]s output to stdout will be used as the credential value.
-Output to stderr will be ignored.
-Credentials configured with \f[V]Credentials=\f[R] take precedence over
-files in \f[V]mkosi.credentials\f[R].
-.PP
-All these files are optional.
-.PP
-Note that the location of all these files may also be configured during
-invocation via command line switches, and as settings in
-\f[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 the \f[V]mkosi.build\f[R] build script.
-.PP
-The package cache (i.e.\ the first item above) is unconditionally
-useful.
-The latter two caches only apply to uses of \f[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:
-an OS image rebuilt will be almost as quick to build the source tree
-only.
-.SH ENVIRONMENT VARIABLES
-.PP
-The build script \f[V]mkosi.build\f[R] receives the following
-environment variables:
-.IP \[bu] 2
-\f[V]$SRCDIR\f[R] contains the path to the sources to build.
-.IP \[bu] 2
-\f[V]$DESTDIR\f[R] is a directory into which any artifacts generated by
-the build script shall be placed.
-.IP \[bu] 2
-\f[V]$BUILDDIR\f[R] is only defined if \f[V]mkosi.builddir\f[R] and
-points to the build directory to use.
-This is useful for all build systems that support out-of-tree builds to
-reuse already built artifacts from previous runs.
-.IP \[bu] 2
-\f[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]).
-The 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]).
-The 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]).
-The 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]$MKOSI_LESS\f[R] overrides options for \f[V]less\f[R] when it is
-invoked by \f[V]mkosi\f[R] to page output.
-.SH EXAMPLES
-.PP
-Create and run a raw \f[I]GPT\f[R] image with \f[I]ext4\f[R], as
-\f[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 -p systemd -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
-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,dracut,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
-\f[V]mkosi\f[R] builds a Unified Kernel Image (UKI).
-It 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 \[lq]direct kernel boot\[rq] 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.
-It is usually easiest to use the distribution package.
-.PP
-The latest code from git requires systemd 253.
-.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 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[V]systemd-nspawn(1)\f[R], \f[V]dnf(8)\f[R]
projects / thirdparty / mkosi.git / commitdiff
