`mkosi [options…] summary`
-`mkosi [options…] build [script parameters…]`
+`mkosi [options…] build`
`mkosi [options…] shell [command line…]`
`build`
: This builds the image based on the settings passed in on the command line or
- read from a `mkosi.conf` file. This command is the default if no verb is
- explicitly specified. This command must be executed as `root`. Any arguments
- passed after the `build` verb are passed as arguments to the build script (if
- there is one).
+ read from configuration files. This command is the default if no verb is
+ explicitly specified.
`shell`
`boot`
-: Similar to `shell`, but boots the image using `systemd-nspawn`. An optional
- command line may be specified after the `boot` verb, which is then passed as
- the "kernel command line" to the init system in the image.
+: 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 `qemu` to boot up the image, i.e. instead of
- container virtualization virtual machine virtualization is used. This verb is
- only supported for disk images that contain a boot loader. Any arguments
- specified after the `qemu` verb are appended to the `qemu` invocation.
+: Similar to `boot`, but uses `qemu` 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 `-kernel` qemu argument to
+ the `qemu` verb. Any arguments specified after the `qemu` verb are
+ appended to the `qemu` invocation.
`ssh`
-: When the image is built with the `Ssh=yes` option, this command connects
- to a booted (`boot`, `qemu` verbs) container or VM via SSH. Make sure to
+: 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` was run with so
- that it has the necessary information available to connect to the running
- container/VM via SSH. Any arguments passed after the `ssh` verb are passed as
- arguments to the `ssh` invocation.
+ that it has the necessary information available to connect to the
+ running virtual machine via SSH. 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`.
`clean`
`--directory=`, `-C`
-: Takes a path to a directory. `mkosi` switches to this directory
- before doing anything. Note that the various `mkosi.*` files are
- searched for only after changing to this directory, hence using this
- option is an effective way to build a project located in a specific
- directory.
+: 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=`
in consecutive runs with data from the cached one.
- Copy package manager trees into the workspace
+* Copy base trees (`--base-tree=`) into the image
* Copy skeleton trees (`mkosi.skeleton`) into image
-* Install distribution and packages into image or use cache tree if available
+* Install distribution and packages into image or use cache tree if
+ available
+* Run prepare script on image with the `final` argument (`mkosi.prepare`)
* Install build packages in overlay if a build script is configured
-* Run prepare script on image and on image + build overlay if a build script is configured (`mkosi.prepare`)
-* Run build script on image + build overlay if a build script is configured (`mkosi.build`)
+* Run prepare script on overlay with the `build` argument if a build
+ script is configured (`mkosi.prepare`)
+* Cache the image if configured (`--incremental`)
+* Run build script on image + overlay if a build script is configured (`mkosi.build`)
+* Finalize the build if the output format `none` is configured
* Copy the build script outputs into the image
* Copy the extra trees into the image (`mkosi.extra`)
-* Install systemd-boot
+* Install systemd-boot and configure secure boot if configured (`--secure-boot`)
* Run post-install script (`mkosi.postinst`)
+* Run `systemd-sysusers`
* Run `systemctl preset-all`
+* Run `depmod`
+* Run `systemd-firstboot`
+* Run `systemd-hwdb`
* Remove packages and files (`RemovePackages=`, `RemoveFiles=`)
* Run finalize script (`mkosi.finalize`)
* Run SELinux relabel is a SELinux policy is installed
-* Generate unified kernel image
+* Generate unified kernel image if configured to do so
* Generate final output format
## Supported output formats
The following output formats are supported:
-* Raw *GPT* disk image, created using systemd-repart
+* Raw *GPT* disk image, created using systemd-repart (*disk*)
* Plain directory, containing the OS tree (*directory*)
* Tar archive (*tar*)
-* CPIO archive (*cpio*) in the format appropriate for a kernel initrd
+* 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 script (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.
Configuration is parsed in the following order:
* The command line arguments are parsed
-* `mkosi.conf` is parsed if it exists in the directory set with
+* `mkosi.conf` is parsed if it exists in the directory configured with
`--directory=` or the current working directory if `--directory=` is
not used.
* `mkosi.conf.d/` is parsed in the same directory if it exists. Each
: The distribution to install in the image. Takes one of the following
arguments: `fedora`, `debian`, `ubuntu`, `arch`, `opensuse`, `mageia`,
- `centos`, `openmandriva`, `rocky`, and `alma`. If not specified,
- defaults to the distribution of the host. Whenever a distribution is
- assigned, the release is reset to the default release configured
- for that distribution.
+ `centos`, `openmandriva`, `rocky`, `alma` or `gentoo`. If not
+ specified, defaults to the distribution of the host.
`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.
+ 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.
`Mirror=`, `--mirror=`, `-m`
`Output=`, `--output=`, `-o`
-: Path for the output image file to generate. Takes a relative or
- absolute path where the generated image will be placed. If neither
- this option nor `OutputDirectory=` is used, the image is
+: Filename to use for the generated output image file or directory. If
+ neither this option nor `OutputDirectory=` is used, the image is
generated under the name `image`, but its name suffixed with an
- appropriate file suffix (e.g. `image.raw.xz` in case `gpt_ext4` is
- used in combination with `xz` compression). If the `ImageId=` option
- is configured it is used instead of `image` in the default output
- name. If an image version is specified via `ImageVersion=`, it is
- included in the default name, e.g. a specified image version of
- `7.8` might result in an image file name of `image_7.8.raw.xz`.
+ appropriate file suffix (e.g. `image.raw.xz` in case `disk` is used in
+ combination with `xz` compression). If the `ImageId=` option is
+ configured it is used instead of `image` in the default output name.
+ If an image version is specified via `ImageVersion=`, it is included
+ in the default name, e.g. a specified image version of `7.8` might
+ result in an image file name of `image_7.8.raw.xz`.
`OutputDirectory=`, `--output-dir=`, `-O`
-: Path to a directory where to place all generated artifacts (i.e. the
- generated image when an output path is not given, `SHA256SUMS` file,
- etc.). If this is not specified and the directory `mkosi.output/`
- exists in the local directory, it is automatically used for this
- purpose. If the setting is not used and `mkosi.output/` does not
- exist, all output artifacts are placed adjacent to the output image
- file. If an output directory is configured, mkosi will create
- `distro~release` subdirectories in it to store the artfifacts per
- distro, release combination that's built.
+: 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=`
: 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
`mkosi.cache/` directory is found in the local directory it is
- automatically used for this purpose. The directory configured this
- way is mounted into both the development and the final image while
- the package manager is running.
+ automatically used for this purpose.
`BuildDirectory=`, `--build-dir=`
-: Takes a path of a directory to use as build directory for build
+: Takes a path to a directory to use as build directory for build
systems that support out-of-tree builds (such as Meson). The
directory used this way is shared between repeated builds, and
allows the build system to reuse artifacts (such as object files,
root or `/usr` partition along with its Verity partition and unified
kernel.
-`RepartDirectory=`, `--repart-dir=`
+`RepartDirectories=`, `--repart-dir=`
-: Path to a directory containing systemd-repart partition definition files that
+: Paths to directories containing systemd-repart partition definition files that
are used when mkosi invokes systemd-repart when building a disk image. If not
specified and `mkosi.repart/` exists in the local directory, it will be used
instead. Note that mkosi invokes repart with `--root=` set to the root of the
`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. Packages specified this way will be installed both in the
- development and the final image. Use `BuildPackages=` to specify packages
- that shall only be used for the image generated in the build image, but that
- shall not appear in the final image.
-
-: The types and syntax of "package specifications" that are allowed depend on
- the package installer (e.g. `dnf` or `yum` for `rpm`-based distros or `apt`
- for `deb`-based distros), but may include package names, package names with
- version and/or architecture, package name globs, paths to packages in the
- file system, package groups, and virtual provides, including file paths.
-
-: To remove a package e.g. added by a `mkosi.conf` configuration
- file prepend the package name with `!`. For example -p "!apache2"
- would remove the apache2 package. To replace the apache2 package by
- the httpd package just add -p "!apache2,httpd" to the command line
- arguments. To remove all packages use "!\*".
-
-: Example: when using an distro that uses `dnf`,
- `Packages=meson libfdisk-devel.i686 git-* prebuilt/rpms/systemd-249-rc1.local.rpm /usr/bin/ld @development-tools python3dist(mypy)`
- would install
- the `meson` package (in the latest version),
- the 32-bit version of the `libfdisk-devel` package,
- all available packages that start with the `git-` prefix,
- a `systemd` rpm from the local file system,
- one of the packages that provides `/usr/bin/ld`,
- the packages in the "Development Tools" group,
- and the package that contains the `mypy` python module.
+ 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
+ script is executed with the `build` argument and when the build script
+ is executed.
+
+: The types and syntax of "package specifications" that are allowed
+ depend on the package installer (e.g. `dnf` for `rpm`-based distros or
+ `apt` for `deb`-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 `dnf`,
+
+ ```
+ Packages=meson
+ libfdisk-devel.i686
+ git-*
+ prebuilt/rpms/systemd-249-rc1.local.rpm
+ /usr/bin/ld
+ @development-tools
+ python3dist(mypy)
+ ```
+
+ would install the `meson` package (in the latest version), the 32-bit
+ version of the `libfdisk-devel` package, all available packages that
+ start with the `git-` prefix, a `systemd` rpm from the local file
+ system, one of the packages that provides `/usr/bin/ld`, the packages
+ in the "Development Tools" group, and the package that contains the
+ `mypy` python module.
`WithDocs=`, `--with-docs`
`KernelCommandLine=`, `--kernel-command-line=`
-: Use the specified kernel command line when building images. By default
- command line arguments get appended. To remove all arguments from the
- current list pass "!\*". To remove specific arguments add a space
- separated list of "!" prefixed arguments. For example adding
- "!\* console=ttyS0 rw" to a `mkosi.conf` file or the command line
- arguments passes "console=ttyS0 rw" to the kernel in any case. Just
- adding "console=ttyS0 rw" would append these two arguments to the kernel
- command line created by lower priority configuration files or previous
- `KernelCommandLine=` command line arguments.
+: Use the specified kernel command line when building images.
`BaseTrees=`, `--base-tree=`
`CleanPackageMetadata=`, `--clean-package-metadata=`
-: Enable/disable removal of package manager databases, caches, and
- logs at the end of installation. Can be specified as true, false, or
- "`auto`" (the default). With "`auto`", files will be removed if the
- respective package manager executable is *not* present at the end of
- the installation.
+: Enable/disable removal of package manager databases at the end of
+ installation. Can be specified as true, false, or "`auto`" (the
+ default). With "`auto`", files will be removed if the respective
+ package manager executable is *not* present at the end of the
+ installation.
`RemoveFiles=`, `--remove-files=`
`Environment=`, `--environment=`
-: Adds variables to the environment that the
- build/prepare/postinstall/finalize scripts are executed with. Takes
+: 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.
`BuildPackages=`, `--build-package=`
-: Similar to `Packages=`, but configures packages to install only in
- the first phase of the build, into the development image. This
- option should be used to list packages containing header files,
+: Similar to `Packages=`, but configures packages to install only in an
+ overlay that is made available on top of the image to the prepare
+ script when executed with the `build` argument and the build script.
+ This option should be used to list packages containing header files,
compilers, build systems, linkers and other build tools the
`mkosi.build` script requires to operate. Note that packages listed
- here are only included in the image created during the first phase
- of the build, and are absent in the final image. Use `Packages=` to
- list packages that shall be included in both.
-
-: Packages are appended to the list. Packages prefixed with "!" are
- removed from the list. "!\*" removes all packages from the list.
+ here will be absent in the final image.
`Autologin=`, `--autologin`
`BuildScript=`, `--build-script=`
: Takes a path to an executable that is used as build script for this
- image. The specified script is copied onto the development image and
- executed inside a namespaced chroot environment. If this option is not
- used, but the `mkosi.build` file found in the local directory it is
- automatically used for this purpose (also see the "Files" section below).
- Specify an empty value to disable automatic detection.
+ image. The specified script is mounted into the image with the build
+ overlay mounted on top. This script is invoked inside a namespaced
+ chroot environment, and thus does not have access to host resources.
+ If this option is not used, but the `mkosi.build` file found in the
+ local directory it is automatically used for this purpose (also see
+ the "Files" section below). Specify an empty value to disable
+ automatic detection.
`PrepareScript=`, `--prepare-script=`
-: Takes a path to an executable that is invoked inside the image right
- after installing the software packages. It is the last step before
- the image is cached (if incremental mode is enabled). This script
- is invoked inside a namespaced chroot environment, and thus does not
- have access to host resources. If this option is not used, but an
- executable script `mkosi.prepare` is found in the local directory, it
- is automatically used for this purpose. Specify an empty value to
- disable automatic detection.
+: Takes a path to an executable that is invoked with the `final`
+ argument inside the image right after installing the software
+ packages. It is the last step before the image is cached (if
+ incremental mode is enabled). If a build script is provided, this
+ script is also invoked with the `build` argument inside the image with
+ the build overlay mounted right after installing the packages
+ configured with `BuildPackages=`. This script is is invoked inside a
+ namespaced chroot environment, and thus does not have access to host
+ resources. If this option is not used, but an executable script
+ `mkosi.prepare` is found in the local directory, it is automatically
+ used for this purpose. Specify an empty value to disable automatic
+ detection.
`PostInstallationScript=`, `--postinst-script=`
-: Takes a path to an executable that is invoked inside the final image
- right after copying in the build artifacts generated in the first
- phase of the build. This script is invoked inside a namespaced chroot
+: Takes a path to an executable that is invoked inside the image right
+ after copying in the build artifacts generated by the build script
+ (if configured). This script is invoked inside a namespaced chroot
environment, and thus does not have access to host resources. If this
option is not used, but an executable `mkosi.postinst` is found in the
local directory, it is automatically used for this purpose. Specify an
`FinalizeScript=`, `--finalize-script=`
-: Takes a path to an executable that is invoked outside the final
- image right after copying in the build artifacts generated in the
- first phase of the build, and after having executed the
- `mkosi.postinst` script (see `PostInstallationScript=`). This script
- is invoked directly in the host environment, and hence has full
- access to the host's resources. If this option is not used, but an
- executable `mkosi.finalize` is found in the local directory, it is
- automatically used for this purpose. Specify an empty value to
- disable automatic detection.
+: Takes a path to an executable that is invoked outside the image after
+ the build is finished but before the image is packaged. This script is
+ invoked directly in the host environment, and hence has full access to
+ the host's resources. If this option is not used, but an executable
+ `mkosi.finalize` is found in the local directory, it is automatically
+ used for this purpose. Specify an empty value to disable automatic
+ detection.
`WithNetwork=`, `--with-network=`
: If specified, the package manager is instructed not to contact the
network for updating package data. This provides a minimal level of
- reproducibility, as long as the package data cache is already fully
+ reproducibility, as long as the package cache is already fully
populated.
`Initrd=`, `--initrd`
`SecureBoot=`, `--secure-boot`
-: Sign the resulting kernel/initrd image for UEFI SecureBoot.
+: Sign systemd-boot (if it is not signed yet) and the resulting
+ kernel/initrd image for UEFI SecureBoot. Also set up secure boot key
+ auto enrollment as documented in the systemd-boot [man page](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)
`SecureBootKey=`, `--secure-boot-key=`
`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
- [`cryptography`](https://cryptography.io/) module is importable and
- the `systemd-measure` binary is in `PATH`.
+ `systemd-measure` binary is in `PATH`.
`Checksum=`, `--checksum`
`Incremental=`, `--incremental=`, `-i`
-: Enable incremental build mode. This only applies if the two-phase
- `mkosi.build` build script logic is used. In this mode, a copy of
- the OS image is created immediately after all OS packages are
- unpacked but before the `mkosi.build` script is invoked in the
- development container. Similarly, a copy of the final image is
- created immediately before the build artifacts from the
- `mkosi.build` script are copied in. On subsequent invocations of
- `mkosi` with the `-i` switch these cached images may be used to skip
- the OS package unpacking, thus drastically speeding up repetitive
- build times. Note that when this is used and a pair of cached
- incremental images exists they are not automatically regenerated,
- even if options such as `Packages=` are modified. In order to force
- rebuilding of these cached images, combine `-i` with `-ff` to ensure
- cached images are first removed and then re-created.
+: 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 script has executed but before the `mkosi.build` script is
+ 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=`
`Ssh=`, `--ssh`
-: If specified, an sshd socket unit and matching service are installed in the final
- image that expose sshd over VSock. When building with this option and running the
- image using `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. Also note that mkosi doesn't provision
- a public SSH key into the image automatically. One way to do this is by setting the
- `ssh.authorized_keys.root` credential using the `Credential=` option or by copying it
- in using `ExtraTrees=`. To access images booted using `mkosi boot`, use `machinectl`.
+: 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. mkosi will automatically provision the
+ user's public SSH key into the image using the
+ `ssh.authorized_keys.root` credential if it can be retrieved from a
+ running SSH agent. To access images booted using `mkosi boot`, use
+ `machinectl`.
`Credentials=`, `--credential=`
`ToolsTree=`, `--tools-tree=`
-: If specified, programs executed by mkosi are looked up inside the given tree instead of in the host system
- (aside from a few exceptions). 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. Note that when looking up binaries
- in `--tools-tree=`, only `/usr/bin` and `/usr/sbin` are considered. Specifically, paths specified by
- `--extra-search-path=` are ignored when looking up binaries in the given tools tree.
-
-### Commandline-only Options
-
-Those settings cannot be configured in the configuration files.
-
-`--directory=`, `-C`
-
-: Takes a path to a directory. `mkosi` switches to this directory
- before doing anything. Note that the various `mkosi.*` files are
- searched for only after changing to this directory, hence using this
- option is an effective way to build a project located in a specific
- directory.
-
-`--incremental`, `-i`
-
-: Enable incremental build mode. This only applies if the two-phase
- `mkosi.build` build script logic is used. In this mode, a copy of
- the OS image is created immediately after all OS packages are
- unpacked but before the `mkosi.build` script is invoked in the
- development container. Similarly, a copy of the final image is
- created immediately before the build artifacts from the
- `mkosi.build` script are copied in. On subsequent invocations of
- `mkosi` with the `-i` switch these cached images may be used to skip
- the OS package unpacking, thus drastically speeding up repetitive
- build times. Note that when this is used and a pair of cached
- incremental images exists they are not automatically regenerated,
- even if options such as `Packages=` are modified. In order to force
- rebuilding of these cached images, combine `-i` with `-ff` to ensure
- cached images are first removed and then re-created.
-
-`--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.
-
-`--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 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.
+: 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
+ `mkosi.tools/` 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 `--tools-tree=`, only `/usr/bin`
+ and `/usr/sbin` are considered. Specifically, paths specified by
+ `--extra-search-path=` are ignored when looking up binaries in the
+ given tools tree.
## Supported distributions
-Images may be created containing installations of the
-following operating systems:
+Images may be created containing installations of the following
+distributions:
* *Fedora Linux*
* *Gentoo*
-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 *CentOS*, *Alma Linux*, *Rocky Linux*,
-*Fedora Linux*, *Mageia* or *OpenMandriva* images. 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. Any distribution
-that packages `emerge` may be used to build *Gentoo* images.
+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 *CentOS*, *Alma Linux*, *Rocky
+Linux*, *Fedora Linux*, *OpenSUSE*, *Mageia* or *OpenMandriva* images.
+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.
Currently, *Fedora Linux* packages all relevant tools as of Fedora 28.
tree. Specifically, the following files are used if they exist in the
local directory:
-* The **`mkosi.conf`** file provides the default configuration for the image building process. For example,
- it may specify the distribution to use (`fedora`, `ubuntu`, `debian`, `arch`, `opensuse`, `mageia`,
- `openmandriva`, `gentoo`) for the image, or additional distribution packages to install. Note that all
- options encoded in this configuration file may also be set on the command line, and this file is hence
- little more than a way to make sure invoking `mkosi` without further parameters in your *source* tree is
- enough to get the right image of your choice set up.
-
- Additionally, if a `mkosi.conf.d/` directory exists, each file in it is loaded in the same manner extending
- the values specified in `mkosi.conf`. Each directory in `mkosi.conf.d/` containing a `mkosi.conf` file is
- parsed as another top level directory.
-
- The file format is inspired by Windows `.ini` files and supports multi-line assignments: any line with
- initial whitespace is considered a continuation line of the line before. Command-line arguments, as shown
- in the help description, have to be included in a configuration block (e.g. "`[Content]`") corresponding
- to the argument group (e.g. "`Content`"), and the argument gets converted as follows: "`--with-network`"
- becomes "`WithNetwork=yes`".
-
* The **`mkosi.skeleton/`** directory or **`mkosi.skeleton.tar`**
archive may be used to insert files into the image. The files are
copied *before* the distribution packages are installed into the
copied will be owned by root. To preserve ownership, use a tar
archive.
-* **`mkosi.build`** may be an executable script. If it exists, the configured build packages will be
- installed as a build overlay on top of the image. The build overlay is used to build the project in the
- current working directory (the *source* tree). For that the whole directory is mounted into the image,
- along with the `mkosi.build` script. The script is then invoked inside the build overlay, with `$SRCDIR`
- pointing to the *source* tree. `$DESTDIR` points to a directory where the script should place any files
- generated it would like to end up in the image. Note that `make`/`automake`/`meson` based build systems
- generally honor `$DESTDIR`, thus making it very natural to build *source* trees from the build script.
- After running the build script, the contents of `$DESTDIR` are copied into the image.
+* **`mkosi.build`** may be an executable script. If it exists, the build
+ sources (`BuildSources=`) are mounted into the image with the build
+ overlay mounted on top, along with the `mkosi.build` script. The
+ script is then invoked inside the build overlay, with `$SRCDIR`
+ pointing to the *source* tree. `$DESTDIR` points to a directory where
+ the script should place any files generated it would like to end up in
+ the image. Note that `make`/`automake`/`meson` based build systems
+ generally honor `$DESTDIR`, thus making it very natural to build
+ *source* trees from the build script. After running the build script,
+ the contents of `$DESTDIR` are copied into the image.
- The `$MKOSI_CONFIG` environment variable will be set inside of this script so that you know which
- `mkosi.conf` (if any) was passed in.
+ The `$MKOSI_CONFIG` environment variable will be set inside of this
+ script so that you know which `mkosi.conf` (if any) was passed in.
* The **`mkosi.prepare`** script is invoked directly after the software packages are installed, from within
- the image context, if it exists. It is first called for the image with the "final" command line argument,
+ the image context, if it exists. It is first called for the image with the `final`` command line argument,
right after the software packages are installed. It is called a second time for the build overlay (if
- this is enabled, see above) with the "build" command line parameter, right after the build packages are
+ this is enabled, see above) with the `build`` command line parameter, right after the build packages are
installed and before the build script is executed. This script has network access and may be used to
install packages from other sources than the distro's package manager (e.g. `pip`, `npm`, ...), after all
software packages are installed but before the image is cached (if incremental mode is enabled). This
not set, and it is up to build script to decide whether to do in in-tree or an out-of-tree build, and which
build directory to use.
-* The **`mkosi.installdir/`** directory, if it exists, is automatically used as the install directory.
- Specifically, this directory will be mounted into the build overlay at `$DESTDIR` when running the build
- script. After running the build script, the contents of this directory are installed into the final image.
- This is useful to inspect the results of the install step of the build.
-
* The **`mkosi.rootpw`** file can be used to provide the password for the root user of the image. If the
password is prefixed with `hashed:` 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
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 `/etc/crypttab` expect the passphrase
- files). The file must have an access mode of 0600 or less. If this
- file does not exist and encryption is requested, the user is queried
- instead.
+ files). The file must have an access mode of 0600 or less.
* The **`mkosi.crt`** and **`mkosi.key`** files contain an X.509 certificate and PEM private key to use when
signing is required (UEFI SecureBoot, verity, ...).
-* The **`mkosi.output/`** directory will be used for all build
- artifacts, if the image output path is not configured (i.e. no
- `--output=` setting specified), or configured to a filename (i.e. a
- path containing no `/` character). This includes the image itself,
- the root hash file in case Verity is used, the checksum and its
- signature if that's enabled, and the nspawn settings file if there
- is any. Note that this directory is not used if the image output
- path contains at least one slash, and has no effect in that case.
- This setting is particularly useful if multiple different images
- shall be built from the same working directory, as otherwise the
- build result of a preceding run might be copied into a build image
- as part of the source tree (see above).
+* The **`mkosi.output/`** directory is used to store all build
+ artifacts.
* The **`mkosi.credentials/`** directory is used as a
source of extra credentials similar to the `Credentials=` option. For
sources from a previous built, thus speeding up the build process
of the `mkosi.build` build script.
-The package cache (i.e. the first item above) is unconditionally
-useful. The latter two caches only apply to uses of `mkosi` with a
-source tree and build script. When all three are enabled together
-turn-around times for complete image builds are minimal, as only
-changed source files need to be recompiled: an OS image rebuilt will
-be almost as quick to build the source tree only.
+The package cache and incremental mode are unconditionally useful. The
+final cache only apply to uses of `mkosi` 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.
# ENVIRONMENT VARIABLES
* `$SRCDIR` contains the path to the sources to build.
-* `$DESTDIR` is a directory into which any artifacts generated by the
- build script shall be placed.
+* `$DESTDIR` is a directory into which any installed software generated
+ by the build script may be placed.
* `$BUILDDIR` is only defined if `mkosi.builddir` 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.
+* `$OUTPUTDIR` is the staging directory used to store build artifacts
+ generated by the build script.
+
* `$WITH_DOCS` is either `0` or `1` depending on whether a build
without or with installed documentation was requested
(`WithDocs=yes`). The build script should suppress installation of
Create and run a bootable *GPT* image, as `foobar.raw`:
```console
-$ mkosi -d fedora -p kernel -p systemd -p udev -o foobar.raw
+$ 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
```
# REQUIREMENTS
mkosi is packaged for various distributions: Debian, Ubuntu, Arch
-Linux, Fedora Linux, OpenMandriva, Gentoo. It is usually easiest to use the
-distribution package.
+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.
-The latest code from git requires systemd 253.
+The latest code from git requires systemd 254.
When not using distribution packages make sure to install the
necessary dependencies. For example, on *Fedora Linux* you need:
projects / thirdparty / mkosi.git / commitdiff
