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