Command Line Verbs¶

The following command line verbs are known:

summary

Outputs a human-readable summary of all options used for building an image. This will parse the command line and mkosi.conf file as it would do on build, but only output what it is configured for and not actually build anything.

build

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.

shell

This builds the image if it is not built yet, and then invokes systemd-nspawn to acquire an interactive shell prompt in it. An optional command line may be specified after the shell verb, to be invoked in place of the shell in the container. Use -f in order to rebuild the image unconditionally before acquiring the shell, see below. This command must be executed as root.

boot

Similar to shell, but boots the image using systemd-nspawn. An optional command line may be specified after the boot verb, which can contain extra nspawn options as well as arguments which are passed as the kernel command line to the init system in the image.

qemu

Similar to boot, but uses the configured virtual machine monitor (by default qemu) to boot up the image, i.e. instead of container virtualization virtual machine virtualization is used. How extra command line arguments are interpreted depends on the configured virtual machine monitor. See VirtualMachineMonitor= for more information.

ssh

When the image is built with the Ssh=yes option, this command connects to a booted virtual machine (qemu) via SSH. Make sure to run mkosi ssh with the same config as mkosi build so that it has the necessary information available to connect to the running virtual machine via SSH. Specifically, the SSH private key from the SshKey= setting is used to connect to the virtual machine. Use mkosi genkey to automatically generate a key and certificate that will be picked up by mkosi. Any arguments passed after the ssh verb are passed as arguments to the ssh invocation. To connect to a container, use machinectl login or machinectl shell.

journalctl

Uses journalctl to inspect the journal inside the image. Any arguments specified after the journalctl verb are appended to the journalctl invocation.

coredumpctl

Uses coredumpctl to look for coredumps inside the image. Any arguments specified after the coredumpctl verb are appended to the coredumpctl invocation.

clean

Remove build artifacts generated on a previous build. If combined with -f, also removes incremental build cache images. If -f is specified twice, also removes any package cache.

serve

This builds the image if it is not built yet, and then serves the output directory (i.e. usually mkosi.output/, see below) via a small embedded HTTP server, listening on port 8081. Combine with -f 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 machinectl pull-raw ... and machinectl pull-tar ....

burn <device>

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.

bump

Bumps the image version from mkosi.version and writes the resulting version string to mkosi.version. 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 --auto-bump/-B may be used to automatically bump the version after each successful build.

genkey

Generate a pair of SecureBoot keys for usage with the SecureBootKey=/--secure-boot-key= and SecureBootCertificate=/--secure-boot-certificate= options.

documentation

Show mkosi’s documentation. By default this verb will try several ways to output the documentation, but a specific option can be chosen with the --doc-format option. Distro packagers are encouraged to add a file mkosi.1 into the mkosi/resources 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 mkosi/resources/mkosi.md e.g via pandoc -t man -s -o mkosi.1 mkosi.md.

dependencies

Output the list of packages required by mkosi to build and boot images.

help

This verb is equivalent to the --help switch documented below: it shows a brief usage explanation.

Commandline-only Options¶

Those settings cannot be configured in the configuration files.

--force, -f

Replace the output file if it already exists, when building an image. By default when building an image and an output artifact already exists mkosi 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 Files section below), specifying this option thrice will ensure the package cache is removed too, before the re-build is initiated. For the clean 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.

--directory=, -C

Takes a path to a directory. mkosi 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.

--debug=

Enable additional debugging output.

--debug-shell

When executing a command in the image fails, mkosi will start an interactive shell in the image allowing further debugging.

--debug-workspace=

When an error occurs, the workspace directory will not be deleted.

--version

Show package version.

--help, -h

Show brief usage information.

--genkey-common-name=

Common name to be used when generating keys via mkosi’s genkey command. Defaults to mkosi of %u, where %u expands to the username of the user invoking mkosi.

--genkey-valid-days=

Number of days that the keys should remain valid when generating keys via mkosi’s genkey command. Defaults to two years (730 days).

--auto-bump=, -B

If specified, after each successful build the version is bumped in a fashion equivalent to the bump 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.

--doc-format

The format to show the documentation in. Supports the values markdown, man, pandoc, system and auto. In the case of markdown the documentation is shown in the original Markdown format. man shows the documentation in man page format, if it is available. pandoc will generate the man page format on the fly, if pandoc is available. system 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. auto, which is the default, will try all methods in the order man, pandoc, markdown, system.

--json

Show the summary output as JSON-SEQ.

Supported output formats¶

The following output formats are supported:

•

Raw GPT disk image, created using systemd-repart (disk)

•

Plain directory, containing the OS tree (directory)

•

Tar archive (tar)

•

CPIO archive (cpio)

The output format may also be set to none 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).

When a GPT disk image is created, repart partition definition files may be placed in mkosi.repart/ to configure the generated disk image.

It is highly recommended to run mkosi 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.

Configuration Settings¶

The following settings can be set through configuration files (the syntax with SomeSetting=value) and on the command line (the syntax with --some-setting=value). 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.

Configuration is parsed in the following order:

•

The command line arguments are parsed

•

mkosi.local.conf is parsed if it exists. This file should be in the gitignore (or equivalent) and is intended for local configuration.

•

Any default paths (depending on the option) are configured if the corresponding path exists.

•

mkosi.conf is parsed if it exists in the directory configured with --directory= or the current working directory if --directory= is not used.

•

If a profile is defined, its configuration is parsed from the mkosi.profiles/ directory.

•

mkosi.conf.d/ is parsed in the same directory if it exists. Each directory and each file with the .conf extension in mkosi.conf.d/ is parsed. Any directory in mkosi.conf.d is parsed as if it were a regular top level directory.

•

Subimages are parsed from the mkosi.images directory if it exists.

Note that settings configured via the command line always override settings configured via configuration files. If the same setting is configured more than once via configuration files, later assignments override earlier assignments except for settings that take a collection of values. Also, settings read from mkosi.local.conf will override settings from configuration files that are parsed later but not settings specified on the CLI.

Settings that take a collection 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. The values specified on the CLI are appended after all the values from configuration files.

To conditionally include configuration files, the [Match] section can be used. A [Match] section consists of individual conditions. Conditions can use a pipe symbol (|) after the equals sign (...=|...), which causes the condition to become a triggering condition. The config file will be included if the logical AND of all non-triggering conditions and the logical OR of all triggering conditions is satisfied. To negate the result of a condition, 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.

Note that [Match] conditions compare 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 (settings specified on the CLI are taken into account). Also note that matching against a setting and then changing its value afterwards in a different config file may lead to unexpected results.

The [Match] section of a mkosi.conf file in a directory applies to the entire directory. If the conditions are not satisfied, the entire directory is skipped. The [Match] sections of files in mkosi.conf.d/ and mkosi.local.conf only apply to the file itself.

If there are multiple [Match] sections in the same configuration file, each of them has to be satisfied in order for the configuration file to be included. Specifically, triggering conditions only apply to the current [Match] section and are reset between multiple [Match] sections. As an example, the following will only match if the output format is one of disk or directory and the architecture is one of x86-64 or arm64:

[Match]
Format=|disk
Format=|directory
[Match]
Architecture=|x86-64
Architecture=|arm64
    

The [TriggerMatch] section can be used to indicate triggering match sections. These are identical to triggering conditions except they apply to the entire match section instead of just a single condition. As an example, the following will match if the distribution is debian and the release is bookworm or if the distribution is ubuntu and the release is focal.

[TriggerMatch]
Distribution=debian
Release=bookworm
[TriggerMatch]
Distribution=ubuntu
Release=focal
    

The semantics of conditions in [TriggerMatch] sections is the same as in [Match], i.e. all normal conditions are joined by a logical AND and all triggering conditions are joined by a logical OR. When mixing [Match] and [TriggerMatch] sections, a match is achieved when all [Match] sections match and at least one [TriggerMatch] section matches. No match sections are valued as true. Logically this means:

(⋀ᵢ Matchᵢ) ∧ (⋁ᵢ TriggerMatchᵢ)
    

Command line options that take no argument are shown without = in their long version. In the config files, they should be specified with a boolean argument: either 1, yes, or true to enable, or 0, no, false to disable.

[Distribution] Section¶

Distribution=, --distribution=, -d

The distribution to install in the image. Takes one of the following arguments: fedora, debian, ubuntu, arch, opensuse, mageia, centos, rhel, rhel-ubi, openmandriva, rocky, alma, custom. If not specified, defaults to the distribution of the host or custom if the distribution of the host is not a supported distribution.

Release=, --release=, -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. 29), or a distribution version name (in case of Debian, Ubuntu, ..., e.g. artful). 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.

Architecture=, --architecture=

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’ll also need to install and register a user mode emulator for that architecture.

Mirror=, --mirror=, -m

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.

LocalMirror=, --local-mirror=

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 --mirror= but only for the local mkosi build, it will not be configured inside the final image, --mirror= (or the default repository) will be configured inside the final image instead.

RepositoryKeyCheck=, --repository-key-check=

Controls signature/key checks when using repositories, enabled by default. Useful to disable checks when combined with --local-mirror= and using only a repository from a local filesystem. Not used for DNF-based distros yet.

Repositories=, --repositories=

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.

CacheOnly=, --cache-only=

Takes one of auto, metadata, always or never. Defaults to auto. If always, the package manager is instructed not to contact the network. This provides a minimal level of reproducibility, as long as the package cache is already fully populated. If set to metadata, the package manager can still download packages, but we won’t sync the repository metadata. If set to auto, the repository metadata is synced unless we have a cached image (see Incremental=) and packages can be downloaded during the build. If set to never, repository metadata is always synced and and packages can be downloaded during the build.

PackageManagerTrees=, --package-manager-tree=

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. This option is similar to the SkeletonTrees= option, 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. If the mkosi.pkgmngr/ directory is found in the local directory it is used for this purpose with the root directory as target (also see the Files section below). If not configured in any way this value will default to the same value of SkeletonTrees=.

[Output] Section¶

Format=, --format=, -t

The image format type to generate. One of directory (for generating an OS image directly in a local directory), tar (similar, but a tarball of the OS image is generated), cpio (similar, but a cpio archive is generated), disk (a block device OS image with a GPT partition table), uki (a unified kernel image with the OS image in the .initrd PE section), esp (uki but wrapped in a disk image with only an ESP partition), oci (a directory compatible with the OCI image specification), sysext, confext, portable or none (the OS image is solely intended as a build image to produce another artifact).

ManifestFormat=, --manifest-format=

The manifest format type or types to generate. A comma-delimited list consisting of json (the standard JSON output format that describes the packages installed), changelog (a human-readable text format designed for diffing). By default no manifest is generated.

Output=, --output=, -o

Name to use for the generated output image file or directory. Defaults to image or, if ImageId= is specified, it is used as the default output name, optionally suffixed with the version set with ImageVersion= or if a specific image is built from mkosi.images, the name of the image is preferred over ImageId. Note that this option does not allow configuring the output directory, use OutputDirectory= for that.

CompressOutput=, --compress-output=

Configure compression for the resulting image or archive. The argument can be either a boolean or a compression algorithm (xz, zstd). zstd compression is used by default, except CentOS and derivatives up to version 8, which default to xz, and OCI images, which default to gzip. 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 shell, boot, qemu verbs are not available when this option is used. Implied for tar, cpio, uki, esp, and oci.

CompressLevel=, --compress-level=

Configure the compression level to use. Takes an integer. The possible values depend on the compression being used.

OutputDirectory=, --output-dir=, -O

Path to a directory where to place all generated artifacts. If this is not specified and the directory mkosi.output/ exists in the local directory, it is automatically used for this purpose.

WorkspaceDirectory=, --workspace-dir=

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 $XDG_CACHE_HOME (if set), $HOME/.cache (if set) or /var/tmp is used.

CacheDirectory=, --cache-dir=

Takes a path to a directory to use as the incremental cache directory for the incremental images produced when the Incremental= option is enabled. If this option is not used, but a mkosi.cache/ directory is found in the local directory it is automatically used for this purpose.

PackageCacheDirectory=, --package-cache-dir

Takes a path to a directory to use as the package cache directory for the distribution package manager used. If unset, a suitable directory in the user’s home directory or system is used.

BuildDirectory=, --build-dir=

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 $BUILDDIR environment variable. This directory is mounted into the image’s root directory when mkosi-chroot is invoked during execution of the build scripts. If this option is not specified, but a directory mkosi.builddir/ exists in the local directory it is automatically used for this purpose (also see the Files section below).

ImageVersion=, --image-version=

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 mkosi.version in which case it may be conveniently managed via the bump verb or the --auto-bump option. When specified the image version is included in the default output file name, i.e. instead of image.raw the default will be image_0.1.raw for version 0.1 of the image, and similar. The version is also passed via the $IMAGE_VERSION to any build scripts invoked (which may be useful to patch it into /usr/lib/os-release or similar, in particular the IMAGE_VERSION= field of it).

ImageId=, --image-id=

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 $IMAGE_ID to any build scripts invoked. The image ID is automatically added to /usr/lib/os-release.

SplitArtifacts=, --split-artifacts

If specified and building a disk image, pass --split=yes 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 /usr partition along with its Verity partition and unified kernel.

RepartDirectories=, --repart-dir=

Paths to directories containing systemd-repart partition definition files that are used when mkosi invokes systemd-repart when building a disk image. If mkosi.repart/ exists in the local directory, it will be used for this purpose as well. Note that mkosi invokes repart with --root= set to the root of the image root, so any CopyFiles= source paths in partition definition files will be relative to the image root directory.

SectorSize=, --sector-size=

Override the default sector size that systemd-repart uses when building a disk image.

RepartOffline=, --repart-offline=

Specifies whether to build disk images using loopback devices. Enabled by default. When enabled, systemd-repart will not use loopback devices to build disk images. When disabled, systemd-repart will always use loopback devices to build disk images.

Overlay=, --overlay

When used together with BaseTrees=, 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.

UseSubvolumes=, --use-subvolumes=

Takes a boolean or auto. 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 btrfs is not installed or subvolumes cannot be created, an error is raised. If auto, missing btrfs or failures to create subvolumes are ignored.

Seed=, --seed=

Takes a UUID as argument or the special value random. Overrides the seed that systemd-repart(8) (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.

SourceDateEpoch=, --source-date-epoch=

Takes a timestamp in seconds since the UNIX epoch as argument. File modification times of all files will be clamped to this value. The variable is also propagated to systemd-repart and scripts executed by mkosi. If not set explicitly, SOURCE_DATE_EPOCH from --environment 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.

CleanScripts=, --clean-script=

Takes a comma-separated list of paths to executables that are used as the clean scripts for this image. See the Scripts section for more information.

[Content] Section¶

Packages=, --package=, -p

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 BuildPackages= to specify packages that shall only be installed in an overlay that is mounted when the prepare scripts are executed with the build argument and when the build scripts are executed.

BuildPackages=, --build-package=

Similar to Packages=, 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 build 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 mkosi.build scripts require to operate. Note that packages listed here will be absent in the final image.

VolatilePackages=, --volatile-package=

Similar to Packages=, but packages configured with this setting are not cached when Incremental= is enabled and are installed after executing any build scripts.

PackageDirectories=, --package-directory=

Specify directories containing extra packages to be made available during the build. mkosi will create a local repository containing all packages in these directories and make it available when installing packages or running scripts. If the mkosi.packages/ directory is found in the local directory it is also used for this purpose.

VolatilePackageDirectories=, --volatile-package-directory=

Like PackageDirectories=, but any changes to the packages in these directories will not invalidate the cached images if Incremental= is enabled.

WithRecommends=, --with-recommends=

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.

WithDocs=, --with-docs

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 $WITH_DOCS environment variable passed to the mkosi.build scripts is set to 0 or 1 depending on whether this option is enabled or disabled.

BaseTrees=, --base-tree=

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 by setting CleanPackageMetadata=no (see CleanPackageMetadata=).

SkeletonTrees=, --skeleton-tree=

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 mkosi.skeleton/ directory is found in the local directory it is also used for this purpose with the root directory as target (also see the Files section below).

ExtraTrees=, --extra-tree=

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 mkosi.extra/ directory is found in the local directory it is also used for this purpose with the root directory as target. (also see the Files section below).

RemovePackages=, --remove-package=

Takes a comma-separated list of package specifications for removal, in the same format as Packages=. The removal will be performed as one of the last steps. This step is skipped if CleanPackageMetadata=no is used.

RemoveFiles=, --remove-files=

Takes a comma-separated list of globs. Files in the image matching the globs will be purged at the end.

CleanPackageMetadata=, --clean-package-metadata=

Enable/disable removal of package manager databases and repository metadata at the end of installation. Can be specified as true, false, or auto (the default). With auto, package manager databases and repository metadata will be removed if the respective package manager executable is not present at the end of the installation.

SyncScripts=, --sync-script=

Takes a comma-separated list of paths to executables that are used as the sync scripts for this image. See the Scripts section for more information.

PrepareScripts=, --prepare-script=

Takes a comma-separated list of paths to executables that are used as the prepare scripts for this image. See the Scripts section for more information.

BuildScripts=, --build-script=

Takes a comma-separated list of paths to executables that are used as the build scripts for this image. See the Scripts section for more information.

PostInstallationScripts=, --postinst-script=

Takes a comma-separated list of paths to executables that are used as the post-installation scripts for this image. See the Scripts section for more information.

FinalizeScripts=, --finalize-script=

Takes a comma-separated list of paths to executables that are used as the finalize scripts for this image. See the Scripts section for more information.

PostOutputScripts=, --postoutput-script

Takes a comma-separated list of paths to executables that are used as the post output scripts for this image. See the Scripts section for more information.

BuildSources=, --build-sources=

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 /work/src 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 /work/src.

BuildSourcesEphemeral=, --build-sources-ephemeral=

Takes a boolean. Disabled by default. Configures whether changes to source directories (The working directory and configured using BuildSources=) are persisted. If enabled, all source directories will be reset to their original state every time after running all scripts of a specific type (except sync scripts).

Environment=, --environment=

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 mkosi 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.

EnvironmentFiles=, --env-file=

Takes a comma-separated list of paths to files that contain environment variable definitions to be added to the scripting environment. Uses mkosi.env if it is found in the local directory. The variables are first read from mkosi.env if it exists, then from the given list of files and then from the Environment= settings.

WithTests=, --without-tests, -T

If set to false (or when the command-line option is used), the $WITH_TESTS environment variable is set to 0 when the mkosi.build 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 mkosi.build build scripts honor it.

WithNetwork=, --with-network=

When true, enables network connectivity while the build scripts mkosi.build are invoked. By default, the build scripts run with networking turned off. The $WITH_NETWORK environment variable is passed to the mkosi.build build scripts indicating whether the build is done with or without network.

Bootable=, --bootable=

Takes a boolean or auto. 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 Bootloader=) is not installed or no kernel images can be found, the build will fail. auto behaves as if the option was enabled, but the build won’t fail if either no kernel images or the selected EFI bootloader can’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.

Bootloader=, --bootloader=

Takes one of none, systemd-boot, uki or grub. Defaults to systemd-boot. If set to none, no EFI bootloader will be installed into the image. If set to systemd-boot, systemd-boot will be installed and for each installed kernel, a UKI will be generated and stored in EFI/Linux in the ESP. If set to uki, a single UKI will be generated for the latest installed kernel (the one with the highest version) which is installed to EFI/BOOT/BOOTX64.EFI in the ESP. If set to grub, for each installed kernel, a UKI will be generated and stored in EFI/Linux in the ESP. For each generated UKI, a menu entry is appended to the grub configuration in grub/grub.cfg in the ESP which chainloads into the UKI. A shim grub.cfg is also written to EFI/<distribution>/grub.cfg in the ESP which loads grub/grub.cfg in the ESP for compatibility with signed versions of grub which load the grub configuration from this location.

BiosBootloader=, --bios-bootloader=

Takes one of none or grub. Defaults to none. If set to none, no BIOS bootloader will be installed. If set to grub, grub is installed as the BIOS boot loader if a bootable image is requested with the Bootable= 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.

ShimBootloader=, --shim-bootloader=

Takes one of none, unsigned, or signed. Defaults to none. If set to none, shim and MokManager will not be installed to the ESP. If set to unsigned, mkosi will search for unsigned shim and MokManager EFI binaries and install them. If SecureBoot= is enabled, mkosi will sign the unsigned EFI binaries before installing them. If set to signed, mkosi will search for signed EFI binaries and install those. Even if SecureBoot= is enabled, mkosi won’t sign these binaries again.

UnifiedKernelImages=, --unified-kernel-images=

Specifies whether to use unified kernel images or not when Bootloader= is set to systemd-boot or grub. Takes a boolean value or auto. Defaults to auto. If enabled, unified kernel images are always used and the build will fail if any components required to build unified kernel images are missing. If set to auto, unified kernel images will be used if all necessary components are available. Otherwise Type 1 entries as defined by the Boot Loader Specification will be used instead. If disabled, Type 1 entries will always be used.

UnifiedKernelImageFormat=, --unified-kernel-image-format=

Takes a filename without any path components to specify the format that unified kernel images should be installed as. This may include both the regular specifiers (see Specifiers) and special delayed specifiers, that are expanded during the installation of the files, which are described below. The default format for this parameter is &e-&k with -&h being appended if roothash= or usrhash= is found on the kernel command line and +&c if /etc/kernel/tries is found in the image.

Initrds=, --initrd

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 look for initrds in a subdirectory io.mkosi.initrd of the artifact directory (see $ARTIFACTDIR in the section ENVIRONMENT VARIABLES), if none are found there mkosi will automatically build a default initrd.

InitrdPackages=, --initrd-package=

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.

InitrdVolatilePackages=, --initrd-volatile-package=

Similar to VolatilePackages=, except it applies to the default initrd.

MicrocodeHost=, --microcode-host=

When set to true only include microcode for the host’s CPU in the image.

KernelCommandLine=, --kernel-command-line=

Use the specified kernel command line when building images.

KernelModulesInclude=, --kernel-modules-include=

Takes a list of regex patterns that specify kernel modules to include in the image. Patterns should be relative to the /usr/lib/modules/<kver>/kernel directory. mkosi checks for a match anywhere in the module path (e.g. i915 will match against drivers/gpu/drm/i915.ko). 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.

KernelModulesExclude=, --kernel-modules-exclude=

Takes a list of regex patterns that specify modules to exclude from the image. Behaves the same as KernelModulesInclude= except that all modules that match any of the specified patterns are excluded from the image.

KernelModulesInitrd=, --kernel-modules-initrd=

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.

KernelModulesInitrdInclude=, --kernel-modules-initrd-include=

Like KernelModulesInclude=, but applies to the kernel modules included in the kernel modules initrd.

KernelModulesInitrdExclude=, --kernel-modules-initrd-exclude=

Like KernelModulesExclude=, but applies to the kernel modules included in the kernel modules initrd.

Locale=, --locale=, LocaleMessages=, --locale-messages=, Keymap=, --keymap=, Timezone=, --timezone=, Hostname=, --hostname=, RootShell=, --root-shell=

The settings Locale=, --locale=, LocaleMessages=, --locale-messages=, Keymap=, --keymap=, Timezone=, --timezone=, Hostname=, --hostname=, RootShell=, --root-shell= 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 /usr/lib/credstore, so that they apply even if only /usr is shipped in the image.

RootPassword=, --root-password=,

Set the system root password. If this option is not used, but a mkosi.rootpw file is found in the local directory, the password is automatically read from it. If the password starts with hashed:, it is treated as an already hashed root password. The root password is also stored in /usr/lib/credstore under the appropriate systemd credential so that it applies even if only /usr is shipped in the image. To create an unlocked account without any password use hashed: without a hash.

Autologin=, --autologin

Enable autologin for the root user on /dev/pts/0 (nspawn), /dev/tty1 and /dev/hvc0.

MakeInitrd=, --make-initrd

Add /etc/initrd-release and /init to the image so that it can be used as an initramfs.

Ssh=, --ssh

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 mkosi qemu, the mkosi ssh 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 mkosi genkey to automatically generate an X509 certificate and private key to be used by mkosi to enable SSH access to any virtual machines via mkosi ssh. To access images booted using mkosi boot, use machinectl.

SELinuxRelabel=, --selinux-relabel=

Specifies whether to relabel files to match the image’s SELinux policy. Takes a boolean value or auto. Defaults to auto. If disabled, files will not relabeled. If enabled, an SELinux policy has to be installed in the image and setfiles has to be available to relabel files. If any errors occur during setfiles, the build will fail. If set to auto, files will be relabeled if an SELinux policy is installed in the image and if setfiles is available. Any errors occurred during setfiles will be ignored.

[Validation] Section¶

SecureBoot=, --secure-boot

Sign systemd-boot (if it is not signed yet) and any generated unified kernel images for UEFI SecureBoot.

SecureBootAutoEnroll=, --secure-boot-auto-enroll=

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 SecureBoot= 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 /efi/loader/loader.conf using an extra tree with secure-boot-enroll force or secure-boot-enroll manual in it. Auto enrollment is not supported on systemd versions older than v252. Defaults to yes.

SecureBootKey=, --secure-boot-key=

Path to the PEM file containing the secret key for signing the UEFI kernel image if SecureBoot= is used and PCR signatures when SignExpectedPcr= is also used. When SecureBootKeySource= is specified, the input type depends on the source.

SecureBootKeySource=, --secure-boot-key-source=

Source of SecureBootKey=, to support OpenSSL engines. E.g.: --secure-boot-key-source=engine:pkcs11

SecureBootCertificate=, --secure-boot-certificate=

Path to the X.509 file containing the certificate for the signed UEFI kernel image, if SecureBoot= is used.

SecureBootSignTool=, --secure-boot-sign-tool

Tool to use to sign secure boot PE binaries. Takes one of sbsign, pesign or auto. Defaults to auto. If set to auto, either sbsign or pesign are used if available, with sbsign being preferred if both are installed.

VerityKey=, --verity-key=

Path to the PEM file containing the secret key for signing the verity signature, if a verity signature partition is added with systemd-repart. When VerityKeySource= is specified, the input type depends on the source.

VerityKeySource=, --verity-key-source=

Source of VerityKey=, to support OpenSSL engines. E.g.: --verity-key-source=engine:pkcs11

VerityCertificate=, --verity-certificate=

Path to the X.509 file containing the certificate for signing the verity signature, if a verity signature partition is added with systemd-repart.

SignExpectedPcr=, --sign-expected-pcr

Measure the components of the unified kernel image (UKI) using systemd-measure and embed the PCR signature into the unified kernel image. This option takes a boolean value or the special value auto, which is the default, which is equal to a true value if the systemd-measure binary is in PATH. Depends on SecureBoot= being enabled and key from SecureBootKey=.

Passphrase=, --passphrase

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 /etc/crypttab expect the passphrase files). The file must have an access mode of 0600 or less.

Checksum=, --checksum

Generate a SHA256SUMS file of all generated artifacts after the build is complete.

Sign=, --sign

Sign the generated SHA256SUMS using gpg after completion.

Key=, --key=

Select the gpg key to use for signing SHA256SUMS. This key must be already present in the gpg keyring.

[Host] Section¶

ProxyUrl=, --proxy-url=

Configure a proxy to be used for all outgoing network connections. Various tools that mkosi invokes and for which the proxy can be configured are configured to use this proxy. mkosi also sets various well-known environment variables to specify the proxy to use for any programs it invokes that may need internet access.

ProxyExclude=, --proxy-exclude=

Configure hostnames for which requests should not go through the proxy. Takes a comma separated list of hostnames.

ProxyPeerCertificate=, --proxy-peer-certificate=

Configure a file containing certificates used to verify the proxy. Defaults to the system-wide certificate store.

ProxyClientCertificate=, --proxy-client-certificate=

Configure a file containing the certificate used to authenticate the client with the proxy.

ProxyClientKey=, --proxy-client-key=

Configure a file containing the private key used to authenticate the client with the proxy. Defaults to the proxy client certificate if one is provided.

Incremental=, --incremental=, -i

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 mkosi.build scripts are invoked (or anything that happens after it). On subsequent invocations of mkosi with the -i 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 -i with -ff to ensure the cached image is first removed and then re-created.

NSpawnSettings=, --settings=

Specifies a .nspawn settings file for systemd-nspawn to use in the boot and shell verbs, and to place next to the generated image file. This is useful to configure the systemd-nspawn environment when the image is run. If this setting is not used but an mkosi.nspawn file found in the local directory it is automatically used for this purpose.

ExtraSearchPaths=, --extra-search-path=

List of colon-separated paths to look for tools in, before using the regular $PATH search path.

VirtualMachineMonitor=, --vmm=

Configures the virtual machine monitor to use. Takes one of qemu or vmspawn. Defaults to qemu.

QemuGui=, --qemu-gui=

If enabled, qemu is executed with its graphical interface instead of with a serial console.

QemuSmp=, --qemu-smp=

When used with the qemu verb, this options sets qemu’s -smp argument which controls the number of guest’s CPUs. Defaults to 2.

QemuMem=, --qemu-mem=

When used with the qemu verb, this options sets qemu’s -m argument which controls the amount of guest’s RAM. Defaults to 2G.

QemuKvm=, --qemu-kvm=

When used with the qemu verb, this option specifies whether QEMU should use KVM acceleration. Takes a boolean value or auto. Defaults to auto.

QemuVsock=, --qemu-vsock=

When used with the qemu verb, this option specifies whether QEMU should be configured with a vsock. Takes a boolean value or auto. Defaults to auto.

QemuVsockConnectionId=, --qemu-vsock-cid=

When used with the qemu verb, this option specifies the vsock connection ID to use. Takes a number in the interval [3, 0xFFFFFFFF) or hash or auto. Defaults to auto. When set to hash, the connection ID will be derived from the full path to the image. When set to auto, mkosi will try to find a free connection ID automatically. Otherwise, the provided number will be used as is.

QemuSwtpm=, --qemu-swtpm=

When used with the qemu 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 auto. Defaults to auto.

QemuCdrom=, --qemu-cdrom=

When used with the qemu verb, this option specifies whether to attach the image to the virtual machine as a CD-ROM device. Takes a boolean. Defaults to no.

QemuFirmware=, --qemu-firmware=

When used with the qemu verb, this option specifies which firmware to use. Takes one of uefi, uefi-secure-boot, bios, linux, or auto. Defaults to auto. When set to uefi, the OVMF firmware without secure boot support is used. When set to uefi-secure-boot, the OVMF firmware with secure boot support is used. When set to bios, the default SeaBIOS firmware is used. When set to linux, direct kernel boot is used. See the QemuKernel= option for more details on which kernel image is used with direct kernel boot. When set to auto, uefi-secure-boot is used if possible and linux otherwise.

QemuFirmwareVariables=, --qemu-firmware-variables=

When used with the qemu verb, this option specifies the path to the the firmware variables file to use. Currently, this option is only taken into account when the uefi or uefi-secure-boot firmware is used. If not specified, mkosi will search for the default variables file and use that instead.

QemuKernel=, --qemu-kernel=

Set the kernel image to use for qemu direct kernel boot. If not specified, mkosi will use the kernel provided via the command line (-kernel option) or latest the kernel that was installed into the image (or fail if no kernel was installed into the image).

QemuDrives=, --qemu-drive=

Add a qemu drive. Takes a colon-delimited string of format <id>:<size>[:<directory>[:<options>[:<file-id>]]]. id specifies the qemu ID assigned to the drive. This can be used as the drive= property in various qemu devices. size specifies the size of the drive. This takes a size in bytes. Additionally, the suffixes K, M and G can be used to specify a size in kilobytes, megabytes and gigabytes respectively. directory optionally specifies the directory in which to create the file backing the drive. options optionally specifies extra comma-delimited properties which are passed verbatim to qemu’s -drive option. file-id specifies the ID of the file backing the drive. Drives with the same file ID will share the backing file. The directory and size of the file will be determined from the first drive with a given file ID.

QemuArgs=

Space-delimited list of additional arguments to pass when invoking qemu.

Ephemeral=, --ephemeral

When used with the shell, boot, or qemu 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).

Credentials=, --credential=

Set credentials to be passed to systemd-nspawn or qemu respectively when mkosi shell/boot or mkosi qemu are used. This option takes a space separated list of values which can be either key=value pairs or paths. If a path is provided, if it is a file, the credential name will be the name of the file. If the file is executable, the credential value will be the output of executing the file. Otherwise, the credential value will be the contents of the file. If the path is a directory, the same logic applies to each file in the directory.

KernelCommandLineExtra=, --kernel-command-line-extra=

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.

Acl=, --acl=

If specified, ACLs will be set on any generated root filesystem directories that allow the user running mkosi to remove them without needing privileges.

ToolsTree=, --tools-tree=

If specified, programs executed by mkosi to build and boot an image 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 mkosi.tools/ directory is found in the local directory it is automatically used for this purpose with the root directory as target.

ToolsTreeDistribution=, --tools-tree-distribution=

Set the distribution to use for the default tools tree. By default, the same distribution as the image that’s being built is used, except for CentOS and Ubuntu images, in which case Fedora and Debian are used respectively.

ToolsTreeRelease=, --tools-tree-release=

Set the distribution release to use for the default tools tree. By default, the hardcoded default release in mkosi for the distribution is used.

ToolsTreeMirror=, --tools-tree-mirror=

Set the mirror to use for the default tools tree. By default, the default mirror for the tools tree distribution is used.

ToolsTreeRepositories=, --tools-tree-repository

Same as Repositories= but for the default tools tree.

ToolsTreePackageManagerTrees=, --tools-tree-package-manager-tree=

Same as PackageManagerTrees= but for the default tools tree.

ToolsTreePackages=, --tools-tree-packages=

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.

ToolsTreeCertificates=, --tools-tree-certificates=

Specify whether to use certificates and keys from the tools tree. If enabled, /usr/share/keyrings, /usr/share/distribution-gpg-keys, /etc/pki, /etc/ssl, /etc/ca-certificates, /etc/pacman.d/gnupg and /var/lib/ca-certificates from the tools tree are used. Otherwise, these directories are picked up from the host.

RuntimeTrees=, --runtime-tree=

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 at /root/src in the machine. If the second path is relative, it is interpreted relative to /root/src in the machine.

RuntimeSize=, --runtime-size=

If specified, disk images are grown to the specified size when they’re booted with mkosi boot or mkosi qemu. Takes a size in bytes. Additionally, the suffixes K, M and G can be used to specify a size in kilobytes, megabytes and gigabytes respectively.

RuntimeScratch=, --runtime-scratch=

Takes a boolean value or auto. Specifies whether to mount extra scratch space to /var/tmp. If enabled, practically unlimited scratch space is made available under /var/tmp when booting the image with mkosi qemu, mkosi boot or mkosi shell.

RuntimeNetwork=, --runtime-network=

Takes one of user, interface or none. Defaults to user. Specifies the networking to set up when booting the image. user sets up usermode networking. interface sets up a virtual network connection between the host and the image. This translates to a veth interface for mkosi shell and mkosi boot and a tap interface for mkosi qemu and mkosi vmspawn.

RuntimeBuildSources=, --runtime-build-sources=

Mount the build sources configured with BuildSources= and the build directory (if one is configured) to the same locations in /work that they were mounted to when running the build script when using mkosi boot or mkosi qemu.

UnitProperties=, --unit-property=

Configure systemd unit properties to add to the systemd scopes allocated when using mkosi boot or mkosi qemu. These are passed directly to the --property options of systemd-nspawn and systemd-run respectively.

SshKey=, --ssh-key=

Path to the X509 private key in PEM format to use to connect to a virtual machine started with mkosi qemu and built with the Ssh= option enabled via the mkosi ssh command. If not configured and mkosi.key exists in the working directory, it will automatically be used for this purpose. Run mkosi genkey to automatically generate a key in mkosi.key.

SshCertificate=, --ssh-certificate=

Path to the X509 certificate in PEM format to provision as the SSH public key in virtual machines started with mkosi qemu. If not configured and mkosi.crt exists in the working directory, it will automatically be used for this purpose. Run mkosi genkey to automatically generate a certificate in mkosi.crt.

Machine=, --machine=

Specify the machine name to use when booting the image. Can also be used to refer to a specific image when SSH-ing into an image (e.g. mkosi --image=myimage ssh).

ForwardJournal=, --forward-journal=

Specify the path to which journal logs from containers and virtual machines should be forwarded. If the path has the .journal extension, it is interpreted as a file to which the journal should be written. Otherwise, the path is interpreted as a directory to which the journal should be written.

[Match] Section.¶

Profile=

Matches against the configured profile.

Distribution=

Matches against the configured distribution.

Release=

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.

Architecture=

Matches against the configured architecture. If this condition is used and no architecture has been explicitly configured yet, the host architecture is used.

Repositories=

Matches against repositories enabled with the Repositories= setting. Takes a single repository name.

PathExists=

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.

ImageId=

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.

ImageVersion=

Matches against the configured image version. Image versions can be prepended by the operators ==, !=, >=, <=, <, > 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.

Bootable=

Matches against the configured value for the Bootable= feature. Takes a boolean value or auto.

Format=

Matches against the configured value for the Format= option. Takes an output format (see the Format= option).

SystemdVersion=

Matches against the systemd version on the host (as reported by systemctl --version). Values can be prepended by the operators ==, !=, >=, <=, <, > for rich version comparisons according to the UAPI group version format specification. If no operator is prepended, the equality operator is assumed by default.

BuildSources=

Takes a build source target path (see BuildSources=). This match is satisfied if any of the configured build sources uses this target path. For example, if we have a mkosi.conf file containing:

HostArchitecture=

Matches against the host’s native architecture. See the Architecture= setting for a list of possible values.

ToolsTreeDistribution=

Matches against the configured tools tree distribution.

Environment=

Matches against a specific key/value pair configured with Environment=. If no value is provided, check if the given key is in the environment regardless of which value it has.

This table shows which matchers support globs, rich comparisons and the default value that is matched against if no value has been configured at the time the config file is read:

[Config] Section¶

Profile=, --profile=

Select the given profile. A profile is a configuration file or directory in the mkosi.profiles/ directory. When selected, this configuration file or directory is included after parsing the mkosi.conf file, but before any mkosi.conf.d/*.conf drop in configuration.

Include=, --include=, -I

Include extra configuration from the given file or directory. The extra configuration is included immediately after parsing the setting, except when used on the command line, in which case the extra configuration is included after parsing all command line arguments.

InitrdInclude=, --initrd-include=

Same as Include=, but the extra configuration files or directories are included when building the default initrd.

Dependencies=, --dependency=

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.

MinimumVersion=, --minimum-version=

The minimum mkosi version required to build this configuration. If specified multiple times, the highest specified version is used.

ConfigureScripts=, --configure-script=

Takes a comma-separated list of paths to executables that are used as the configure scripts for this image. See the Scripts section for more information.

PassEnvironment=, --pass-environment=

Takes a list of environment variable names separated by spaces. When building multiple images, pass the listed environment variables to each individual subimage as if they were “universal” settings. See the Building multiple images section for more information.

Specifiers¶

The current value of various settings can be accessed when parsing configuration files by using specifiers. To write a literal % character in a configuration file without treating it as a specifier, use %%. The following specifiers are understood:

There are also specifiers that are independent of settings:

Finally, there are specifiers that are derived from a setting:

Note that the current working directory changes as mkosi parses its configuration. Specifically, each time mkosi parses a directory containing a mkosi.conf file, mkosi changes its working directory to that directory.

Note that the directory that mkosi was invoked in is influenced by the --directory= command line argument.

The following table shows example values for the directory specifiers listed above:

Supported distributions¶

Images may be created containing installations of the following distributions:

•

Fedora Linux

•

Debian

•

Ubuntu

•

Arch Linux

•

openSUSE

•

Mageia

•

CentOS

•

RHEL

•

RHEL UBI

•

OpenMandriva

•

Rocky Linux

•

Alma Linux

•

None (Requires the user to provide a pre-built rootfs)

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 apt may be used to build Debian or Ubuntu images. Any distribution that packages dnf may be used to build images for any of the rpm-based distributions. Any distro that packages pacman may be used to build Arch Linux images. Any distribution that packages zypper may be used to build openSUSE images. Other distributions and build automation tools for embedded Linux systems such as Buildroot, OpenEmbedded and Yocto Project may be used by selecting the custom distribution, and populating the rootfs via a combination of base trees, skeleton trees, and prepare scripts.

Currently, Fedora Linux packages all relevant tools as of Fedora 28.

Note that when not using a custom mirror, RHEL images can only be built from a host system with a RHEL subscription (established using e.g. subscription-manager).

Different ways to boot with qemu¶

The easiest way to boot a virtual machine is to build an image with the required components and let mkosi call qemu with all the right options:

$ mkosi -d fedora \


    --autologin \


    -p systemd-udev,systemd-boot,kernel-core \


    build
$ mkosi -d fedora qemu
...
fedora login: root (automatic login)
[root@fedora ~]#
    

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 Ctrl-a c. The qemu monitor may for example be used to inject special keys or shut down the machine quickly. Alternatively the machine can be shut down using Ctrl-a x.

To boot with a graphical window, add --qemu-qui:

$ mkosi -d fedora --qemu-gui qemu
    

A kernel may be booted directly with mkosi qemu -kernel ... -initrd ... -append '...'. 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’s -append option replaces the default kernel commandline embedded in the kernel and any previous -append specifications.

The UKI is also copied into the output directory and may be booted directly:

$ mkosi qemu -kernel mkosi.output/fedora~38/image.efi
    

When booting using an external kernel, we don’t need the kernel in the image, but we would still want the kernel modules to be installed.

It is also possible to do a direct kernel boot into a boot loader, taking advantage of the fact that systemd-boot(7) is a valid UEFI binary:

$ mkosi qemu -kernel /usr/lib/systemd/boot/efi/systemd-bootx64.efi
    

In this scenario, the kernel is loaded from the ESP in the image by systemd-boot.