mkosi

https://github.com/systemd/mkosi
Admin
mkosi is a tool that builds customized operating system disk images using package managers like dnf,...
Tokens:82,351
Snippets:690
Trust Score:9.4
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Packages= example with dnf package specifications

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md

Example configuration for the Packages= setting when using a distro that uses dnf. Installs the meson package, the 32-bit libfdisk-devel, all packages starting with git-, a systemd RPM from the local file system, a package providing /usr/bin/ld, the Development Tools group, and the package containing the mypy python module.

```ini
Packages=meson
         libfdisk-devel.i686
         git-*
         /usr/bin/ld
         @development-tools
         python3dist(mypy)
```

--------------------------------

### Install mkosi manually in a virtual environment

Source: https://github.com/systemd/mkosi/blob/main/README.md

Manually create a virtual environment and install mkosi from git, equivalent to the pipx method but with explicit control over the virtual environment path and the mkosi binary location.

```shell
python3 -m venv mkosivenv
mkosivenv/bin/pip install git+https://github.com/systemd/mkosi.git
mkosivenv/bin/mkosi --version
```

--------------------------------

### Prepare script to install BuildRequires

Source: https://github.com/systemd/mkosi/blob/main/docs/building-rpms-from-source.md

Prepare script that installs static and dynamic BuildRequires dependencies in the build overlay. It runs rpmspec to get static deps, then repeatedly runs rpmbuild -bd until it succeeds or fails with a non-11 exit code, installing dynamic deps from the generated SRPM.

```shell
#!/bin/sh
set -e

if [ "$1" = "final" ]; then
    exit 0
fi

mkosi-chroot \
    env --chdir=mkosi \
    rpmspec \
    --query \
    --buildrequires \
    --define "_topdir /var/tmp" \
    --define "_sourcedir $PWD/mkosi/rpm" \
    rpm/mkosi.spec |
        sort --unique |
        tee /tmp/buildrequires |
        xargs --delimiter '\n' mkosi-install

until mkosi-chroot \
    env --chdir=mkosi \
    rpmbuild \
    -bd \
    --noprep \
    --build-in-place \
    --define "_topdir /var/tmp" \
    --define "_sourcedir $PWD/mkosi/rpm" \
    --define "_build_name_fmt %%{NAME}-%%{VERSION}-%%{RELEASE}.%%{ARCH}.rpm" \
    rpm/mkosi.spec
do
    EXIT_STATUS=$?
    if [ $EXIT_STATUS -ne 11 ]; then
        exit $EXIT_STATUS
    fi

    mkosi-chroot \
        rpm \
        --query \
        --package \
        --requires \
        /var/tmp/SRPMS/mkosi-*.buildreqs.nosrc.rpm |
            grep --invert-match '^rpmlib(' |
            sort --unique >/tmp/dynamic-buildrequires

    sort /tmp/buildrequires /tmp/dynamic-buildrequires |
        uniq --unique |
        tee --append /tmp/buildrequires |
        xargs --delimiter '\n' mkosi-install
done
```

--------------------------------

### Run installation tests

Source: https://github.com/systemd/mkosi/blob/main/README.md

Runs installation tests (venv, editable, zipapp) which are skipped by default because they create virtual environments and install packages from the network.

```sh
bin/mkosi box -- pytest -m install
```

--------------------------------

### Run a single integration test

Source: https://github.com/systemd/mkosi/blob/main/README.md

Example of setting up an Arch image with a Fedora tools tree and then running a single integration test. Requires KVM; tests are skipped or very slow without /dev/kvm.

```sh
tools/integration-test-setup.sh arch fedora

bin/mkosi box -- pytest -m integration --distribution arch --capture=no --verbose \
    'tests/test_boot.py::test_bootloader[systemd-boot]'
```

--------------------------------

### Install mkosi with pipx from git

Source: https://github.com/systemd/mkosi/blob/main/README.md

Install mkosi from the git repository using pipx, which transparently installs it into a Python virtual environment and places a mkosi binary in ~/.local/bin.

```shell
pipx install git+https://github.com/systemd/mkosi.git
mkosi --version
```

--------------------------------

### Post-install script: Install mkosi and copy RPMs

Source: https://github.com/systemd/mkosi/blob/main/docs/building-rpms-from-source.md

Post-installation script that installs the built mkosi package and copies the produced RPMs from $PACKAGEDIR to $OUTPUTDIR. The RPMs are added to a local package repository and become available for installation via a post-installation script or the VolatilePackages= setting.

```shell
#!/bin/sh
set -e

mkosi-install mkosi

cp "$PACKAGEDIR"/*mkosi*.rpm "$OUTPUTDIR"
```

--------------------------------

### mkosi.conf: Basic image build configuration

Source: https://github.com/systemd/mkosi/blob/main/blog/content/a-reintroduction-to-mkosi.md

Configuration file for mkosi that specifies the distribution, output format, and packages to install. This is equivalent to the command line options used in the example above.

```ini
[Distribution]
Distribution=arch

[Output]
Format=disk

[Content]
Packages=
        systemd
        udev
        linux
```

--------------------------------

### Install rpm-build in mkosi.conf

Source: https://github.com/systemd/mkosi/blob/main/docs/building-rpms-from-source.md

Adds rpm-build to the image so that rpmspec and rpmbuild are available. RemovePackages removes it from the final image if desired.

```ini
[Content]
Packages=rpm-build
# If you don't want rpm-build in the final image.
RemovePackages=rpm-build
```

--------------------------------

### Install mkosi dependencies with dnf

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md

Pipes the output of `mkosi dependencies` to `dnf install` to install required packages. The `-d '\n'` option for `xargs` ensures each package name is treated as a separate argument.

```sh
mkosi dependencies | xargs -d '\n' dnf install
```

--------------------------------

### mkosi.build.chroot script for meson projects

Source: https://github.com/systemd/mkosi/blob/main/blog/content/a-reintroduction-to-mkosi.md

Build script for a meson-based project. It sets up the build directory, builds, optionally runs tests, and installs into the image. The script is executed by mkosi when present as mkosi.build or mkosi.build.chroot.

```sh
#!/bin/sh
meson setup "$BUILDDIR" "$SRCDIR"
ninja -C "$BUILDDIR"
if ((WITH_TESTS)); then
    meson test -C "$BUILDDIR"
fi
meson install -C "$BUILDDIR"
```

--------------------------------

### Create a compressed disk image with SSH and checksum

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md

Creates a compressed image image.raw.xz with SSH installed and adds a checksum file.

```console
$ mkosi --distribution fedora --format disk --checksum=yes --compress-output=yes --package=openssh-clients
```

--------------------------------

### mkosi initrd configuration (Format=cpio, MakeInitrd=yes)

Source: https://github.com/systemd/mkosi/blob/main/docs/initrd.md

Configuration for building an initrd image with mkosi. Uses the cpio output format, sets MakeInitrd=yes, and installs systemd, udev, and kmod packages. The cpio format is compressed by default.

```ini
[Output]
Format=cpio

[Content]
MakeInitrd=yes
Packages=systemd
         udev
         kmod

```

--------------------------------

### mkosi.conf.d/10-arch.conf: Conditional package installation

Source: https://github.com/systemd/mkosi/blob/main/blog/content/a-reintroduction-to-mkosi.md

Drop-in configuration file that conditionally installs the 'pacman' package only when the distribution is Arch Linux, using the [Match] section.

```ini
[Match]
Distribution=arch

[Content]
Packages=pacman
```

--------------------------------

### Define A/B update and encrypted /var partitions in mkosi.extra

Source: https://github.com/systemd/mkosi/blob/main/docs/root-verity.md

Provides partition definitions in the image itself for an A/B update setup and an encrypted /var. Includes reduced definitions for matching existing partitions, plus swap and var partitions encrypted with TPM2.

```ini
# mkosi.extra/usr/lib/repart.d/00-esp.conf
[Partition]
Type=esp

# mkosi.extra/usr/lib/repart.d/10-root-verity-sig.conf
[Partition]
Type=root-verity-sig
Label=%M_%A_verity_sig

# mkosi.extra/usr/lib/repart.d/11-root-verity.conf
[Partition]
Type=root-verity
Label=%M_%A_verity

# mkosi.extra/usr/lib/repart.d/12-root.conf
[Partition]
Type=root
Label=%M_%A
SizeMinBytes=2G
SizeMaxBytes=2G

# mkosi.extra/usr/lib/repart.d/20-root-verity-sig.conf
[Partition]
Type=root-verity-sig
Label=_empty

# mkosi.extra/usr/lib/repart.d/21-root-verity.conf
[Partition]
Type=root-verity
Label=_empty
SizeMinBytes=300M
SizeMaxBytes=300M

# mkosi.extra/usr/lib/repart.d/22-root.conf
[Partition]
Type=root
Label=_empty
SizeMinBytes=2G
SizeMaxBytes=2G

# mkosi.extra/usr/lib/repart.d/30-swap.conf
[Partition]
Type=swap
Format=swap
Encrypt=tpm2
SizeMinBytes=4G
SizeMaxBytes=4G

# mkosi.extra/usr/lib/repart.d/40-var.conf
[Partition]
Type=var
Format=ext4
Encrypt=tpm2
SizeMinBytes=2G
```

--------------------------------

### Base image definition (mkosi.images/base/mkosi.conf)

Source: https://github.com/systemd/mkosi/blob/main/docs/sysext.md

Defines the base image using the directory format to avoid root privileges. Installs systemd and udev, and keeps package metadata.

```ini
[Output]
Format=directory

[Content]
CleanPackageMetadata=no
Packages=systemd
         udev

```

--------------------------------

### System extension definition (mkosi.images/btrfs/mkosi.conf)

Source: https://github.com/systemd/mkosi/blob/main/docs/sysext.md

Defines a sysext that depends on the base image, uses the sysext format with overlay, and installs btrfs-progs. BaseTrees points to the base image output.

```ini
[Config]
Dependencies=base

[Output]
Format=sysext
Overlay=yes

[Content]
BaseTrees=%O/base
Packages=btrfs-progs

```

--------------------------------

### Run mkosi with python3 -m mkosi

Source: https://github.com/systemd/mkosi/blob/main/README.md

Invoke mkosi via the Python module when not installed as a zipapp. The python module exists solely for the usage of the mkosi binary and is not a public API.

```shell
python3 -m mkosi
```

--------------------------------

### mkosi --debug --debug-shell failure log

Source: https://github.com/systemd/mkosi/blob/main/docs/debugging.md

Example log output shown when a sandboxed command fails. The first line reports the command and its non-zero exit code; the second line shows the full sandbox invocation that can be re-run from a separate host shell to reproduce the failure.

```text
‣ [main] "/usr/bin/some-command --some-option" returned non-zero exit code 1.
‣ [main] Sandbox command: mkosi-sandbox --bind … -- /usr/bin/some-command --some-option
```

--------------------------------

### Start bash in current directory with own network namespace

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi-sandbox.1.md

Runs bash in the current working directory, binding the entire root filesystem and using a new network namespace. The --same-dir flag keeps the current working directory.

```sh
mkosi-sandbox --bind / / --same-dir --unshare-net
```

--------------------------------

### Define systemd-sysupdate transfers for verity image

Source: https://github.com/systemd/mkosi/blob/main/docs/root-verity.md

Example systemd-sysupdate transfer definitions for updating the verity-protected image. They are missing a [Source] section whose contents depend on how updates are deployed. The definitions target root-verity-sig, root-verity, root partitions, and a UKI regular file.

```ini
# /usr/lib/sysupdate.d/10-root-verity-sig.transfer
[Transfer]
ProtectVersion=%A

[Target]
Type=partition
Path=auto
MatchPattern=%M_@v_verity_sig
MatchPartitionType=root-verity-sig
PartitionFlags=0
ReadOnly=1

# /usr/lib/sysupdate.d/11-root-verity.transfer
[Transfer]
ProtectVersion=%A

[Target]
Type=partition
Path=auto
MatchPattern=%M_@v_verity
MatchPartitionType=root-verity
PartitionFlags=0
ReadOnly=1

# /usr/lib/sysupdate.d/12-root.transfer
[Transfer]
ProtectVersion=%A

[Target]
Type=partition
Path=auto
MatchPattern=ParticleOS_@v
MatchPartitionType=root
PartitionFlags=0
ReadOnly=1

# /usr/lib/sysupdate.d/20-uki.transfer
[Transfer]
ProtectVersion=%A

[Target]
Type=regular-file
Path=/EFI/Linux
PathRelativeTo=boot
MatchPattern=%M_@v+@l-@d.efi \
             %M_@v+@l.efi \
             %M_@v.efi
Mode=0444
TriesLeft=3
TriesDone=0
InstancesMax=2
```

--------------------------------

### Create and run a bootable GPT image as foobar.raw

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md

Creates a bootable GPT image as foobar.raw, then boots it with the boot command and runs it in a VM with the vm command.

```console
$ 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 vm
```

--------------------------------

### Build and boot a VM with automatic login

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md

Builds a Fedora image with the required components and boots it in a VM with automatic root login.

```console
$ mkosi -d fedora -p systemd-udev,systemd-boot,kernel-core build
$ mkosi -d fedora vm
...
fedora login: root (automatic login)
[root@fedora ~]#
```

--------------------------------

### Boot with graphical console using --console=gui

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md

Boots a Fedora image in a graphical QEMU window by adding --console=gui.

```console
$ mkosi -d fedora --console=gui qemu
```

--------------------------------

### Set up integration test environment

Source: https://github.com/systemd/mkosi/blob/main/README.md

Writes a local configuration for the given image and tools tree distribution and builds both.

```sh
tools/integration-test-setup.sh $DISTRIBUTION $TOOLS_TREE_DISTRIBUTION
```

--------------------------------

### Build and boot an Arch Linux disk image in qemu

Source: https://github.com/systemd/mkosi/blob/main/blog/content/a-reintroduction-to-mkosi.md

Builds an Arch Linux GPT disk image and boots it in qemu. Requires mkosi, bubblewrap, and the distribution's package manager.

```sh
$ mkosi -d arch -p systemd -p udev -p linux -t disk qemu
```

--------------------------------

### Enable mkosi companion tools via symlinks

Source: https://github.com/systemd/mkosi/blob/main/README.md

Symlink the companion tools mkosi-addon, mkosi-initrd, and mkosi-sandbox from the repository into ~/.local/bin, similar to the main mkosi shim.

```shell
ln -s $PWD/mkosi/bin/mkosi-addon ~/.local/bin/mkosi-addon
ln -s $PWD/mkosi/bin/mkosi-initrd ~/.local/bin/mkosi-initrd
ln -s $PWD/mkosi/bin/mkosi-sandbox ~/.local/bin/mkosi-sandbox
```

--------------------------------

### Build and boot an Arch Linux disk image in systemd-nspawn

Source: https://github.com/systemd/mkosi/blob/main/blog/content/a-reintroduction-to-mkosi.md

Builds an Arch Linux GPT disk image and boots it in systemd-nspawn instead of qemu. The image is written to image.raw in the current directory.

```sh
$ mkosi -d arch -p systemd -p udev -p linux -t disk boot
```

--------------------------------

### Configure drives and QEMU arguments in [Runtime] section

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md

Configures two drives (btrfs and ext4) with 10G and 20G sizes, and passes corresponding QEMU device arguments to attach them as NVMe drives. The drives are created under /var/tmp by default and can be referenced by their IDs in QemuArgs.

```ini
[Runtime]
Drives=btrfs:10G
       ext4:20G
QemuArgs=-device nvme,serial=btrfs,drive=btrfs
         -device nvme,serial=ext4,drive=ext4
```

--------------------------------

### Build an OS image from an automake project

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md

Configures mkosi for an automake-based project so that invoking mkosi without parameters builds an OS image containing the project. Creates mkosi.conf and mkosi.build, makes the build script executable, then builds and boots the image with mkosi -i boot and runs it with systemd-nspawn.

```console
$ cat >mkosi.conf <<EOF
[Distribution]
Distribution=fedora

[Output]
Format=disk

[Content]
Packages=kernel,systemd,systemd-udev,openssh-clients,httpd
BuildPackages=make,gcc,libcurl-devel
EOF
$ cat >mkosi.build <<EOF
#!/bin/sh

if [ "$container" != "mkosi" ]; then
    exec mkosi-chroot "$CHROOT_SCRIPT" "$@"
fi

cd $SRCDIR
./autogen.sh
./configure --prefix=/usr
make -j `nproc`
make install
EOF
$ chmod +x mkosi.build
# mkosi -i boot
# systemd-nspawn -bi image.raw
```

--------------------------------

### Use initrd in top-level image with Initrds=%O/initrd

Source: https://github.com/systemd/mkosi/blob/main/docs/root-verity.md

Adds the initrd built in mkosi.images/initrd to the top-level image via the Initrds= setting in mkosi.conf.

```ini
[Content]
Initrds=%O/initrd
```

--------------------------------

### Create and run a Fedora Linux image in a directory

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md

Creates and runs a Fedora Linux image in a plain directory.

```console
# mkosi --distribution fedora --format directory boot
```

--------------------------------

### Initrd packaging configuration (mkosi.conf)

Source: https://github.com/systemd/mkosi/blob/main/docs/sysext.md

Adds a cpio initrd output that uses the base image as its base tree. Run mkosi -f to build both the initrd and the extension.

```ini
[Output]
Format=cpio
Output=initrd

[Content]
MakeInitrd=yes
BaseTrees=%O/base

```

--------------------------------

### Create and run a raw GPT image with ext4

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md

Creates and runs a raw GPT image with ext4 as image.raw. The -i option builds and boots the image.

```console
# mkosi -p systemd -i boot
```

--------------------------------

### Create initrd with systemd-repart drop-in for sysroot

Source: https://github.com/systemd/mkosi/blob/main/docs/root-verity.md

Creates an initrd with a systemd-repart drop-in that ensures systemd-repart runs after the root partition is mounted. The drop-in adds After=sysroot.mount and a ConditionDirectoryNotEmpty check for /sysroot/usr/lib/repart.d.

```ini
# mkosi.images/initrd/mkosi.conf
[Include]
Include=mkosi-initrd

# mkosi.images/initrd/mkosi.extra/usr/lib/systemd/system/systemd-repart.service.d/sysroot.conf
[Unit]
After=sysroot.mount
ConditionDirectoryNotEmpty=|/sysroot/usr/lib/repart.d
```

--------------------------------

### Boot the UKI directly with mkosi vm

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md

Boots the UKI directly from the output directory, bypassing the boot loader.

```console
$ mkosi vm -- -kernel mkosi.output/fedora~38/image.efi
```

--------------------------------

### Python: Enter sandbox in-process with mkosi.sandbox.enter

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi-sandbox.1.md

Imports mkosi.sandbox and calls enter with only options to run in a sandbox without a command. Only the enter function is supported; other functions may break.

```python
import mkosi.sandbox

mkosi.sandbox.enter(["--become-root"])
print(os.getuid())
```

--------------------------------

### Shared mkosi configuration (mkosi.conf)

Source: https://github.com/systemd/mkosi/blob/main/docs/sysext.md

Sets the output and cache directories for all images. Place this in the top-level mkosi.conf.

```ini
[Output]
OutputDirectory=mkosi.output
CacheDirectory=mkosi.cache

```

--------------------------------

### mkosi command to use initrd (--initrd option)

Source: https://github.com/systemd/mkosi/blob/main/docs/initrd.md

Command to build a distribution image with a custom initrd. Pass the path to the initrd image via the --initrd option. mkosi will add kernel modules from the distribution image to the initrd.

```bash
mkosi --initrd=<path-to-initrd-image> ...

```

--------------------------------

### Define base image with directory format in mkosi.images/base/mkosi.conf

Source: https://github.com/systemd/mkosi/blob/main/blog/content/a-reintroduction-to-mkosi.md

Base image definition written to mkosi.images/base/mkosi.conf. Uses the directory output format to avoid requiring root privileges when building the extension.

```ini
[Output]
Format=directory

[Content]
CleanPackageMetadata=no
Packages=systemd
         udev
```

--------------------------------

### Build a custom tools tree with mkosi --include=mkosi-tools

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md

Build a fully custom tools tree using the builtin mkosi-tools include, which provides the default tools tree packages. The output format for tools trees cannot currently be changed via configuration files.

```bash
mkosi --include=mkosi-tools --format=directory
```

--------------------------------

### Add a regular user in a post-installation script

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md

Use in a post-installation script to add a regular user to an image. The password is read from the file referenced by $USER_PASSWORD_FILE and hashed with SHA-512. From systemd v256 onwards, if enabled, systemd-homed-firstboot.service will prompt to create a regular user on first boot if there are no regular users.

```sh
useradd --create-home --user-group $USER --password "$(openssl passwd -stdin -6 <$USER_PASSWORD_FILE)"
```

--------------------------------

### Run id as root with minimal host filesystem

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi-sandbox.1.md

Runs id as the root user in a sandbox that only exposes /usr from the host, plus necessary symlinks and pseudo-filesystems. Uses --become-root to switch to root and --tmpfs for /tmp.

```sh
mkosi-sandbox \
    --ro-bind /usr /usr \
    --symlink usr/bin /bin \
    --symlink usr/lib /lib \
    --symlink usr/lib64 /lib64 \
    --symlink usr/sbin /sbin \
    --dev /dev \
    --bind /proc /proc \
    --tmpfs /tmp \
    --become-root \
    id
```

--------------------------------

### Package mkosi as a zipapp

Source: https://github.com/systemd/mkosi/blob/main/README.md

Build mkosi as a zipapp using tools/generate-zipapp.sh. This leaves a mkosi binary in builddir/ that can be deployed anywhere in your PATH.

```shell
git clone https://github.com/systemd/mkosi
cd mkosi
tools/generate-zipapp.sh
builddir/mkosi --version
```

--------------------------------

### Direct kernel boot into systemd-boot

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md

Performs a direct kernel boot into systemd-boot, which then loads the kernel from the ESP in the image.

```console
$ mkosi vm -- -kernel /usr/lib/systemd/boot/efi/systemd-bootx64.efi
```

--------------------------------

### mkosi.build.chroot: Build RPM with rpmbuild --build-in-place

Source: https://github.com/systemd/mkosi/blob/main/docs/building-rpms-from-source.md

Build script for mkosi that runs inside the image (suffixed .chroot). It invokes rpmbuild with --build-in-place to build the RPM from upstream sources, sets _sourcedir to the spec sources, and _rpmdir to $PACKAGEDIR. The _vpath_builddir is used for out-of-tree builds (CMake, Meson) to enable incremental builds. It disables compression, debug packages, and various build root policy scripts (CentOS/Fedora specific) to speed up the build.

```shell
#!/bin/sh
set -e

env --chdir=mkosi \
    rpmbuild \
    -bb \
    --noprep \
    --build-in-place \
    $([ "$WITH_TESTS" = "0" ] && echo --nocheck) \
    --define "_topdir /var/tmp" \
    --define "_sourcedir $PWD/mkosi/rpm" \
    --define "_rpmdir $PACKAGEDIR" \
    ${BUILDDIR:+--define} \
    ${BUILDDIR:+"_vpath_builddir $BUILDDIR"} \
    --define "_build_name_fmt %%{NAME}-%%{VERSION}-%%{RELEASE}.%%{ARCH}.rpm" \
    --define "_binary_payload w.ufdio" \
    --define "debug_package %{nil}" \
    --define "__brp_strip %{nil}" \
    --define "__brp_compress %{nil}" \
    --define "__brp_mangle_shebangs %{nil}" \
    --define "__brp_strip_comment_note %{nil}" \
    --define "__brp_strip_static_archive %{nil}" \
    rpm/mkosi.spec
```

--------------------------------

### Multiple [Match] sections with OR conditions

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md

This configuration matches only when the output format is 'disk' or 'directory' and the architecture is 'x86-64' or 'arm64'. Each [Match] section must be satisfied; triggering conditions apply only to the current section.

```ini
[Match]
Format=|disk
Format=|directory

[Match]
Architecture=|x86-64
Architecture=|arm64

```

--------------------------------

### Match BuildSources target path

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md

Shows how a drop-in configuration file is conditionally included when the build source target path matches. The first block defines a build source with target path 'kernel'; the second block matches on that target path, causing the drop-in to be included.

```ini
[Build]
BuildSources=../abc/qed:kernel
```

```ini
[Match]
BuildSources=kernel
```

--------------------------------

### Run full test suite in tools tree

Source: https://github.com/systemd/mkosi/blob/main/README.md

Runs the full test suite (linting, type checking, unit tests) inside the tools tree.

```bash
bin/mkosi box -- pytest
```

--------------------------------

### Build mkosi tools tree

Source: https://github.com/systemd/mkosi/blob/main/README.md

Builds the mkosi tools tree (mkosi.tools/) used to run linters and type checks in a consistent environment.

```sh
bin/mkosi -f box -- true
```

--------------------------------

### Default partition definitions for mkosi.repart

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md

Default partition definitions used by mkosi when no mkosi.repart/ directory or RepartDirectories= setting is present. The first defines an ESP partition, the second a BIOS boot partition (only used for BIOS bootable images), and the third a root partition. All files are optional and their locations can be overridden via command line switches or settings in mkosi.conf.

```ini
[Partition]
Type=esp
Format=vfat
CopyFiles=/boot:/
CopyFiles=/efi:/
SizeMinBytes=512M
SizeMaxBytes=512M

```

```ini
[Partition]
# UUID of the grub BIOS boot partition which grubs needs on GPT to
# embed itself into.
Type=21686148-6449-6e6f-744e-656564454649
SizeMinBytes=1M
SizeMaxBytes=1M

```

```ini
[Partition]
Type=root
Format=<distribution-default-filesystem>
CopyFiles=/
Minimize=guess

```

--------------------------------

### Enable unprivileged user namespaces on Ubuntu

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md

Enable unprivileged user namespaces on Ubuntu by disabling AppArmor restrictions. Run these commands as root to immediately allow mkosi to create and act within user namespaces.

```sh
sudo sysctl -w kernel.apparmor_restrict_unprivileged_unconfined=0
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
```

--------------------------------

### Run build script in image with mkosi-chroot

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.news.7.md

Place at the top of a build script to execute it inside the image instead of on the host. The script is run on the host by default; this snippet re-executes it in the image using mkosi-chroot when the container environment variable is not set to 'mkosi'.

```sh
if [ "$container" != "mkosi" ]; then
    exec mkosi-chroot "$SCRIPT" "$@"
fi
```

--------------------------------

### Avoid splitting command-line option and value

Source: https://github.com/systemd/mkosi/blob/main/docs/CODING_STYLE.md

Discouraged formatting that splits an option from its value; use the `# fmt: skip` style instead.

```python
cmd = [
    "--option",
    "foo",
]

```

--------------------------------

### Configure BuildSources in mkosi.local.conf

Source: https://github.com/systemd/mkosi/blob/main/docs/building-rpms-from-source.md

Mounts the upstream mkosi repository and the Fedora RPM spec into the working directory when running mkosi scripts. BuildSourcesEphemeral=yes prevents rpmbuild artifacts from persisting in the source directory.

```ini
[Build]
BuildSources=../mkosi:mkosi
             ../fedora/mkosi:mkosi/rpm
BuildSourcesEphemeral=yes
```

--------------------------------

### Run mkosi from the git repository using bin/mkosi

Source: https://github.com/systemd/mkosi/blob/main/README.md

Clone the mkosi repository and symlink the bin/mkosi shim into ~/.local/bin so it is accessible from the PATH. The MKOSI_INTERPRETER environment variable can be set when using the shim to choose the Python interpreter. You may need to add ~/.local/bin to your user's PATH.

```shell
git clone https://github.com/systemd/mkosi
ln -s $PWD/mkosi/bin/mkosi ~/.local/bin/mkosi
mkosi --version
```

--------------------------------

### TriggerMatch sections for OR matching

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md

This configuration matches if the distribution is 'debian' with release 'bookworm' OR if the distribution is 'ubuntu' with release 'noble'. TriggerMatch sections use OR semantics across sections.

```ini
[TriggerMatch]
Distribution=debian
Release=bookworm

[TriggerMatch]
Distribution=ubuntu
Release=noble

```

--------------------------------

### Persist sysctl settings in /etc/sysctl.d/unprivileged-userns.conf

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md

Persist the sysctl settings across reboots by placing these lines in /etc/sysctl.d/unprivileged-userns.conf. This ensures the AppArmor restrictions remain disabled for future boots.

```conf
kernel.apparmor_restrict_unprivileged_unconfined=0
kernel.apparmor_restrict_unprivileged_userns=0
```

--------------------------------

### Define verity-protected root partitions in mkosi.repart

Source: https://github.com/systemd/mkosi/blob/main/docs/root-verity.md

Defines the ESP, root-verity-signature, root-verity-hash, and root partitions in mkosi.repart to build a disk image with a verity-protected root partition. The root partition uses erofs format, excludes /var, and is minimized; the verity partitions use SplitName for A/B updates.

```ini
# mkosi.repart/00-esp.conf
[Partition]
Type=esp
Format=vfat
CopyFiles=/efi:/
CopyFiles=/boot:/
SizeMinBytes=1G
SizeMaxBytes=1G

# mkosi.repart/10-root-verity-sig.conf
[Partition]
Type=root-verity-sig
Label=%M_%A_verity_sig
Verity=signature
VerityMatchKey=root
SplitName=%t.%U

# mkosi.repart/11-root-verity.conf
[Partition]
Type=root-verity
Label=%M_%A_verity
Verity=hash
VerityMatchKey=root
SizeMinBytes=300M
SizeMaxBytes=300M
SplitName=%t.%U

# mkosi.repart/12-root.conf
[Partition]
Type=root
Format=erofs
Label=%M_%A_root
Verity=data
VerityMatchKey=root
CopyFiles=/
ExcludeFilesTarget=/var/
Minimize=yes
SplitName=%t.%U
```

--------------------------------

### Format command-line argument list with # fmt: skip

Source: https://github.com/systemd/mkosi/blob/main/docs/CODING_STYLE.md

Preferred formatting for command-line argument lists: keep option and value on the same line, add a trailing comma, and use a `# fmt: skip` comment to prevent ruff from splitting them.

```python
cmd = [
    "--option", "foo",
]  # fmt: skip

```

--------------------------------

### Match and TriggerMatch logical formula

Source: https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md

Logical formula for matching when mixing [Match] and [TriggerMatch] sections: all Match sections must match and at least one TriggerMatch section must match.

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

```

--------------------------------

### Run only linter tests

Source: https://github.com/systemd/mkosi/blob/main/README.md

Runs only the linter tests using pytest's -k option.

```sh
bin/mkosi box -- pytest -k test_linters
```
Tokens:
Raw