ja:Mkosi

mkosi stands for Make Operating System Image, and is a tool for easily building customized OS images. It's a fancy Python wrapper around dnf, apt, pacman and zypper that may generate disk images with a number of bells and whistles.

It has nifty features like:

• no_new_privileges to build images as an unpriviliged user

• An Overlay filesystem to re-use existing distribution package caches reducing disk space requirements

• Deep Freedesktop.org and systemd integration

• Wide range of output formats like Raw GPT disk image, plain directory, tar, cpio and USI / UKI.

The project is actively maintained and provides mkosi(1) for customizing images across various distributions.

On Arch Linux, mkosi can be used to build bootable Unified Kernel Images (UKI), including those signed for Secure Boot. Creating images with encrypted LUKS volumes is as straightforward as defining Passphrase in mkosi.conf. Package lists can be defined directly in the mkosi.default file under the Packages section, and additional files or configuration can be added using overlay directories such as mkosi.extra/.

mkosi has a strong focus on developer workflows such as testing, debugging, and producing minimal, production-ready images. A common use case involves adding a mkosi.default configuration file to a project (e.g. written in C or Python), which then allows automated image generation tailored to the project’s needs.

During the build process, mkosi can create a temporary development image that includes headers and tooling, compile the project within it, run tests, and then discard this image. It subsequently builds a second image without development dependencies, containing only the resulting build artifacts and any other explicitly configured packages.

This resulting image is minimal, self-contained, and suitable for deployment via tools such as RAUC, or OSTree, making it well-suited for automated provisioning of servers, embedded systems, or IoT targets.

Installation

Install mkosi. Depending on what distribution you want to use in your OS tree/image, install the following packages:

Basic usage

You can create an image by just running it without any arguments:

$ mkosi

You can specify option as arguments or by editing files in the current folder.

Create and boot a Debian image

The following example will create a bootable image with the latest Debian version and packages openssh-client and vim installed. This command requires mkosi's optional dependencies mtools and systemd-ukify. Depending on the image, can also be built by an unprivileged (non-root) user:

$ mkosi --distribution debian --release trixie --format disk --checksum --root-password password --include mkosi-vm --package openssh-client,vim --repository-key-fetch=yes --output image.raw

systemd-nspawn can boot the resulting image:

# systemd-nspawn --boot --image image.raw

It can also be virtualized with QEMU/KVM or with systemd-vmspawn(1):

$ mkosi --output image.raw --qemu-smp 2 qemu

You can also write this image to a USB drive and use it to boot your computer.

Using configuration files

The same Debian image can be created using a configuration file, mkosi.conf, and then run mkosi without any arguments:

[Distribution]
Distribution=debian
Release=trixie
RepositoryKeyFetch=true

[Output]
Format=disk
Output=image.raw

[Include]
Include=mkosi-vm

[Content]
Bootable=yes
Packages=openssh-client
         vim
RootPassword=password

[Validation]
Checksum=yes

mkosi.conf

The built-in mkosi-vm profile adds the necessary packages in order to run a system and is maintained by the mkosi maintainers.

Downloaded package files and temporary build files are stored in the home cache directory or in /var/cache/mkosi and /var/tmp.

Configuration settings

Settings can be specified as command-line arguments or, for example, in a file called mkosi.conf in the current directory. The most important settings are:

Usage as initramfs generator

Mkosi provides a kernel-install plugin to build an initramfs, similarly to mkinitcpio or dracut.

In order to use it, install cpio and edit the kernel-install configuration file:

initrd_generator=mkosi-initrd

/etc/kernel/install.conf

See also

• Mkosi on Github

• Longer introduction by Poettering, one of its developers

• A re-introduction to mkosi by Daan De Meyer, the current maintainer

• Building Arch Linux USIs with mkosi

• Creating Arch Linux rescue image with Secure Boot

• Jelle's video presentation at All Systems Go on creating Arch Linux images using mkosi