mkosi.news(7)

📦
version 27.1 · 7 versions
, in arch rolling

🎀 mkosi Changelog 🎀

okay so bestie, this is mkosi.news(7) — the literal receipts of every change that ever landed in mkosi, version by version 💖 it's basically the group chat scrollback of the whole project, so grab a snack and let's get into it. every flag, every setting, every "we removed this, sorry" is right here, no cap.

🌟 v27.1 🌟

  • Fix tests failing in restricted build environments 🔧
  • SignInitrdPCRs= can be used with SplitArtifacts=pcrs, fixing initrd-specific PCR policies with systemd v262 ✨
  • Don't fail creating initrds when there are directories mixed in with microcode files 🫶
  • Fix builds when using unsigned local repositories with opensuse 💅
  • Only use repositories and variables from the sandbox tree when using DNF 👀
  • The mkosi-obs no longer sets MakeScriptsExecutable=, except for the main image, so it can be included again 🎀
  • The security and debug repositories are switched back to deb.debian.org and are no longer set by the Repositories= setting 💖
  • Add an environment variable MKOSI_FORCE_USERNS_FALLBACK that when set to a value that parses as a truthy bool, skips using systemd-nsresourced ⭐
  • A new setting DelegateRanges= is added that defaults to 0 when mkosi is run as the root user. This fixes builds run as the root user 👑

🔥 v27 🔥

  • Debug output (with --debug) will now show the duration of all steps ⏱️ lowkey so satisfying
  • When booting an image it is always registered with user session machined instance 🌀
  • gzip compressed outputs have been made reproducible ✨ yes bestie, reproducibility ate
  • Generate locales configured in /etc/locale.gen 🌍
  • PORTABLE_PREFIXES= can be set via Environment= 💜
  • The special value default is now understood for Initrds=, so that it can be used in conjunction with custom initrds 🎀
  • Plugins for DNF can be configured via the environment variables MKOSI_DNF_DISABLE_PLUGINS and MKOSI_DNF_ENABLE_PLUGINS. This is meant for advanced use cases and is not supported further 👀 (iykyk, don't come crying if it breaks)
  • A new option MakeScriptsExecutable= has been added to make scripts, that are not executable, executable instead of exiting with an error 🔧
  • A new option OutputSize= has been added to resize output images to that size after creation 📏
  • Two new options OciLabels= and OciAnnotations= have been added to support adding custom labels and annotations for images using the OCI output 🏷️
  • Default initrds are no longer built by default for images using the directory output 🙈
  • All cached images are removed when repository metadata will be synced to avoid partial upgrade scenarios 💀
  • When booting images the hostname is no longer set via the kernel command line so as not to overwrite the hostname set via other means in the image 🖥️
  • Support for using systemd-nsresourced's foreign UID range has been added for directory images via the new ForeignUIDRange=. This is now the only supported way for booting directory images unprivileged. Building images unprivileged without a sufficiently new systemd-nsresourced is still supported 🦋
  • If a mkosi/ directory exists and no output location is configured, the .mkosi-private will be put there 🗂️
  • LocalMirror= can now be set for tools trees 💫
  • A new setting DiskType= has been added to configures the disk type to use for the root disk when booting a virtual machine 💽
  • Four new settings ElTorito=, ElToritoSystem=, ElToritoVolume=, and ElToritoPublisher= for use with systemd-repart's El Torito support have been added 🔥
  • mkosi box does not tint the background by itself anymore 🎨
  • The GitHub integration tests have been made runnable locally 🧪
  • Support for distribution-built UKIs have been fixed and they are picked up as /usr/lib/modules/<kver>/vmlinuz*.efi if a signed bootloader or UnifiedKernelImages=signed is requested 👑
  • The update-grub trigger of APK is disabled for postmarketOS if /etc/update-grub.conf does not exist. If you define the file yourself, you must set disable_trigger=1 yourself, if you pull in the grub package 🫶 (yes bestie, that one's on you)
  • A new option ToolsTreeSnapshot was added, which defaults to the value of the regular Snapshot= setting if the same distribution is used for the image and the tools tree 🌈

✨ v26 ✨

  • Extra options to commands invoked by mkosi (e.g. when using mkosi boot or mkosi shell) should now be delimited from regular options using --. Options passed after the verb without using the -- delimiter are now interpreted as regular mkosi options ⚠️
  • Boolean options specified on the command line now always expect a boolean argument. For example, --repository-key-check needs to become --repository-key-check=yes. The reason for this change is to remove ambiguity when parsing e.g. --repository-key-check build where build would be interpreted as the argument for --repository-key-check whereas now it'll be properly interpreted as the verb 💅
  • Teach --verity a new hash value, which skips the verity signature partition for extension / portable images. To align the possible values, yes is renamed to signed 🖊️
  • Teach --verity a new defer value, which defers creation of the verity signature partition for disk, extension and portable images (but still allocates space for it). This is useful to implement offline signing of the verity roothash 🔐
  • A new way to specify modules included in the initrd has been added. The new default is that modules need to be specified to be included. Previous separate Include and Exclude options that take regexps are now deprecated and are replaced by a single option that takes a list of positive and negative globs. The new options are KernelModules= and KernelInitrdModules= 🧩
  • A new way to specify firmware files included in the initrd has been added. Previous separate Include and Exclude options that take regexps are now deprecated and are replaced by a single option that takes a list of positive and negative globs. The new option is FirmwareFiles= 🫶
  • The RuntimeScratch= option has been dropped. Use RuntimeSize= instead to grow the image before booting it 🗑️
  • The CDROM= option has been dropped 🗑️
  • Unknown settings now generate a warning message instead of failing the image build. This allows configs to work across a wider range of mkosi versions while still taking advantage of newer settings. MinimumVersion can still be used to enforce a minimum version of mkosi that knows all required settings 💡

🦋 v25 🦋

  • Instead of using bubblewrap, sandboxing is now done with a new tool mkosi-sandbox. This tool has a public API and can be used independently of mkosi 🏗️
  • Image builds are now done in a user namespace with a single user when running unprivileged instead of using newuidmap/newgidmap. When running unprivileged, all files and directories in the image will be owned by the invoking user (and by root inside any produced archives). Any attempt to chown files to other users in scripts will fail unless the new environment variable $MKOSI_CHROOT_SUPPRESS_CHOWN is set to a true value ⚠️
  • mkosi does not drop privileges anymore to the invoking user when running as root for various steps 👑
  • A new cat-config verb will show all configuration files that were included for each configured image 🐈
  • Added support for Azure Linux 💙
  • Added support for Kali Linux 🐉
  • If mkosi.version is executable, we now execute it and read the version from stdout 📜
  • Added --wipe-build-dir to wipe the build directory before rebuilding the image 🧹
  • Introduced RepositoryKeyFetch= to control whether to fetch distribution GPG keys remotely. This setting is disabled by default for security reasons except when building rpm based or Arch Linux images on Ubuntu 🔑
  • We now handle SIGHUP gracefully 🫶
  • Universal settings that take a collection of values cannot be appended to anymore in subimages. Usage of package manager trees in subimages will have to be moved to the top level image. Similarly, repositories will have to be enabled in the top level image 💅
  • Repository metadata is not copied into images anymore 🙅
  • Repository metadata from base trees is not used anymore 🙅
  • Package manager trees are now named sandbox trees 🏷️
  • Package manager trees (sandbox trees) do not use the skeleton trees as their default anymore if unset 🦴
  • Note to packagers: The manual pages have been moved to resources/man and now include man pages for mkosi-initrd and mkosi-sandbox as well 📚
  • InitrdInclude= was removed. If you're using InitrdInclude=, please build your initrd via a subimage in mkosi.images containing Include=mkosi-initrd and any customizations you wish to add and use the Initrds= setting to use it as the initrd for the main image instead of the default initrd 💔
  • Added History= to have mkosi save the config used to build the image and reuse it when verbs such as qemu, boot, ... are invoked without -f 🕰️
  • Introduced new [Build] section and moved various settings to it 📦
  • Moved Include= to [Include] section 📂
  • Added sysupdate verb as a wrapper around systemd-sysupdate which invokes it with definitions from mkosi.sysupdate 🔄
  • Added RuntimeHome= to mount the current home directory to /root when running a command that boots the image 🏠
  • More directories aside from /etc and /usr are now picked up from sandbox trees (formerly known as package manager trees) 🌳
  • Profile configuration from mkosi.profiles is now parsed after mkosi.conf.d instead of before it. To set defaults for use in mkosi.conf.d based on the configured profile, use an early dropin in mkosi.conf.d that matches on the configured profile instead 🎯
  • Profile= is renamed to Profiles= and takes a comma separated list of profiles now. Scripts now receive $PROFILES with a space-separated list of profiles instead of $PROFILE. The %p specifier for profiles is removed 🔤
  • Multiple sync, prepare, build, postinst, finalize, postoutput and clean scripts are now picked up from mkosi.$SCRIPT.d 📜
  • run0 is now automatically used to escalate privileges for commands that need it, like the burn verb 🔥
  • /usr/share/keyrings and /usr/share/distribution-gpg-keys are no longer automatically picked up from the tools tree when ToolsTreeCertificates= is set, since they aren't certificates, use a sandbox tree instead. This allows one to override SignedBy= keys for APT repositories 🔑
  • The agetty.autologin and login.noauth credentials are no longer set unconditionally 🙈
  • Access to the output directory in build scripts was removed. To put artifacts from the build directory into the output directory, copy them from the build directory to the output directory in a post-installation script which does have access to the build directory and the output directory 📤
  • BuildDirectory= is not a thing in PrepareScripts= anymore — like, gone gone. If your prepare script needs to grab files for the build, drop them somewhere sensible inside $BUILDROOT so they can actually get cached when you build incrementally. That's the whole vibe 💅
  • When you're using a tools tree and a relaxed sandbox to run a command (qemu, nspawn, ...), we now keep all entries from $PATH outside of /usr intact. Sounds iconic, right? But heads up — this can cause issues if a $PATH entry contains binaries linked against libraries in /usr from the host. 😭
  • New specifier just dropped: %I ✨ It resolves to the name of the current subimage when you use it in a config under mkosi.images/. And how is it different from %o? It's always the name of the config file without extension (or the name of the directory). iykyk 🫶
  • If /dev/fuse is found in the host context, it gets made available in the sandbox context too. Sharing is caring bestie 💖
  • Added a sandbox verb so you can run a command inside a relaxed mkosi sandbox — literally the same sandbox that mkosi vm, mkosi boot, ... run in. 🧚
  • OpenSSL providers are now supported as key sources for the various key settings, as long as you're on a recent enough systemd version (257 or newer). 🔑
  • Also added support for loading X.509 certificates from OpenSSL providers if you've got a recent enough systemd version (257 or newer). Double slay.
  • Added ToolsTreePackageDirectories= ✨
  • Added --kernel-image= to mkosi-initrd so you can specify which kernel image to use when building a UKI. 👑
  • Okay so this one's a subtle but real behaviour change: if you set a collection based setting to the empty string via the CLI and then append to that same setting, it will now override the settings coming from configuration files. Before, the CLI values would've been appended to the values from configuration files. So, different. Noted. 📝
  • The mkosi-initrd default config now includes various extra kernel modules by default. More modules, more fun 🌸
  • The coredumpctl and journalctl verbs will now always operate on the image — even if ForwardJournal= is configured. No cap. 🔥
  • Bumped the default Fedora release to 41 🎀
  • Added the addon output format for building UKI addons 🦋
  • Renamed the [Host] section to [Runtime]. Get used to the new name, bestie 💅
  • Also renamed various settings from [Host] — so go check your configs, this is your sign 🙈
  • Binaries coming from ExtraSearchPaths= are now executed with the tools tree mounted if one is configured (unlike before, where the tools tree was not mounted). Which means: any binaries coming from ExtraSearchPaths= have to be linked against libraries from the tools tree (or be statically linked). Alternatively, the tools tree distribution and release have to match the host. Pick your fighter 😭
  • Binaries from ExtraSearchPaths= are not used anymore when building the default tools tree. Periodt.
  • Dropped support for pesign as a secure boot signing tool. It's over 💀
  • Added support for systemd-sbsign as a secure boot signing tool. We love a glow-up ✨
  • Added --register= to control whether to register containers and VMs with systemd-machined or not. Your call, main character 💅
  • mkosi.profiles is now parsed in subimages as well 🎀
  • mkosi-initrd now uses dnf5 on systems where it is the default. Matching energy.
  • Added various packages to the default tools tree. Snacks for the tools tree, basically 🍓
  • Dropped support for Ubuntu Focal. RIP, respect 🫶
  • Added the Devicetree= setting for configuring bootloader device trees 🌈
  • Added systemd-machined registration using varlink for mkosi qemu vms — and it includes the vsock CID so that ssh vsock/<cid> or ssh machine/<name> will work on systems running systemd-machined 257 or newer. ssh-ing into your vm like a boss 👑
  • Bumped the CentOS Stream default release to 10 🔥
  • mkosi now manages the pacman keyring itself, so /etc/pacman.d/gnupg from the host is not used anymore. mkosi will run pacman-key --init and pacman-key --populate itself. Self-sufficient queen behaviour 💅
  • Added ToolsTreeRelease= match ✨
  • mkosi now enforces that images built with Overlay=yes only add files on top of the base tree(s) and don't overwrite any existing files or directories. No sneaky overwrites allowed 🙅
  • Added a mkosi-addon tool and an accompanying kernel-install plugin that lets you build PE addons to extend a vendor provided unified kernel image. Extend the UKI, extend the lore 🧚
  • Added systemd-boot-signed, uki-signed and grub-signed variants for the Bootloader= option, which instruct mkosi to only install pre-signed EFI binaries. Signed and delivered 💖
  • mkosi.profiles is now parsed in configuration included with Include= as well 🌸
  • Any initrds configured with Initrds= are now used as a fallback when booting with qemu direct kernel boot (--firmware=linux) if no split initrd was produced by the image build. Backup initrd, love that for you 🫶
  • mkosi now makes a greater effort to ensure the crypto-policies are configured to allow GPG keys from older distributions. Respecting the elders 💜
Big one: we don't pick up pre-signed bootloader binaries anymore when ShimBootloader=signed is configured. To force usage of pre-signed EFI binaries, use the new systemd-boot-signed, uki-signed and grub-signed variants for the Bootloader= option instead. Don't say I didn't warn you 😭
  • Added a new constant microsoft-mok for the FirmwareVariables= option. If specified, a firmware variables file with the Microsoft keys enrolled will be extended to include a MokList entry that trusts the certificate configured with SecureBootCertificate= and passed to qemu. 🔐
  • We now use mkosi.pkgcache as the package cache directory if that directory exists 👑
  • BuildSourcesEphemeral= learned a new variant: buildcache — in which case the overlay will be cached in the build directory configured with BuildDirectory=. Cache it, bestie 🎀

v24

  • The default kernel command line of console=ttyS0 (or the equivalent for other architectures) has been removed. So from v24 onwards you have to manually add the required console= argument yourself if you want the kernel output on the serial console. It's giving DIY now 😭
  • Support for installing local packages located in directories in BuildSources= was dropped. Instead, you can make those packages available for installation via PackageManagerTrees=. Same goal, different route 💅
  • Configuration parsing got reworked to remove the need for the @ specifier and to streamline building multiple images with mkosi.images/. If you were building multiple images with mkosi.images/, you'll need to adapt your configuration to the rework — go read the Building multiple images section in the documentation for more info. This is your homework, bestie 📚
  • mkosi gained the option to generate completion scripts for bash, fish and zsh 🐟 Packagers should generate the scripts during packaging and ship them in the appropriate places. Do it for the people 🫶
  • Added support for CentOS Stream 10 🔥
  • mkosi now installs a separate mkosi-initrd script that can be used to build initramfs images intended for use on the local system. Local initramfs, iconic ✨
  • We do not automatically append centos-stream or fedora anymore to CentOS (and derivatives) and Fedora mirrors specified with Mirror=, because not all mirrors store the repository metadata under these subdirectories. Users are now required to add these subdirectories themselves in Mirror=. And if the EPEL repositories are enabled for CentOS Stream (and derivatives) and Mirror= is used, we look for the EPEL repositories in ../fedora relative to the mirror specified in Mirror=. Read that twice, it matters 🌸
  • We now support compressed tar archives wherever we already accept tar archives as input. Compression stans rise 🎀
  • We now always rerun the build if Format=none and don't remove previous outputs in that case (unless --force is specified). This lets you use mkosi -t none to rerun the build scripts without removing the previous image — and you can combine that with RuntimeBuildSources=yes to make the build script outputs available in a booted container or virtual machine so they can be installed without having to rebuild the image. Elite workflow behaviour 👑
  • We now use virtconsole to provide the serial console when booting with qemu 💅
  • root=PARTUUID and mount.usr=PARTUUID on the kernel command line are now automatically extended with the actual PARTUUID of the corresponding partition. Auto-magic, love that for us ✨
  • All available OpenSUSE repositories are now supported and can be enabled with Repositories= 🌈
  • Building OpenSUSE aarch64 images is now supported 🦋
  • mkosi dependencies was beefed up to handle more scenarios properly. She's been to the gym 💪
  • The default list of kernel modules that are always added to the initramfs was extended with various virtualization modules 🧚
  • Added a Repositories= match ✨
  • Cached images are now invalidated if packages specified via PackageDirectories= change. Fresh cache only, bestie 💅
  • Added VolatilePackageDirectories=, which can be used to provide local packages that do not invalidate cached images. Cache-friendly local packages, the dream 🌸
  • mkosi.pkgmngr is now used as the default path for PackageManagerTrees=. 🎀
  • The package directory that build scripts can use to make built packages available for installation ($PACKAGEDIR) is now shared between all image builds. Which means packages built in earlier images and stored in $PACKAGEDIR become available for installation in all subsequent image builds. Sharing economy but make it packages 🫶
  • The default tools tree distribution is now chosen based on the host distribution instead of the target distribution. Plot twist 😭
  • mkosi can now be invoked from the initramfs. She's everywhere now 💀

v23.1

  • Respin due to git tag mismatch. That's it, that's the whole changelog entry 🙈 (git said no, so we tried again)

v23

  • Added CleanScripts= so you can run custom cleanup code whenever mkosi cleans up the output directory. Perfect if you produce extra outputs from e.g. a build script that mkosi doesn't know about — now you can clean those up yourself 🧹✨
  • Added ConfigureScripts= to allow dynamically modifying the mkosi configuration. Each configure script receives the current config as JSON on stdin and should output the new config as JSON on stdout. Config-ception, but make it useful 🎀
  • When building a UKI, we don't measure for the TPM SHA1 PCR bank anymore. SHA1, your time is up 💅
  • All keys in the mkosi config JSON output are now in pascal case — except for credentials and environments, where the keys encode names of credentials and environment variables and are therefore case sensitive. Don't mess with case-sensitive names, bestie 🙈
  • Added various settings to allow running mkosi behind a proxy 🔐
  • Various fixes to kernel module filtering that should result in fewer modules being pulled into the default initrd when KernelModulesExclude= or KernelModulesInitrdExclude= are used. Lean initrd era 🌸
  • Added ToolsTreeDistribution= match ✨
  • Removed the vmspawn verb and replaced it with VirtualMachineMonitor=. Out with the old, in with the new 👑
  • New specifiers for various directories were added! 🎉 %D resolves to the directory that mkosi was invoked in, %P to the current working directory, and %C to the parent directory of the config file. Memorize these, they're useful fr fr 📚
  • Added ForwardJournal= to have systemd inside a container/VM forward its journal to the specified file or directory 📓
  • Systemd scopes are now allocated for qemu, swtpm, virtiofsd and systemd-journal-remote if available. Organized queen behaviour 💅
  • The mkosi qemu virtual machine is now registered with systemd-machined if available 🎀
  • Added new oci output format 🦋
  • Runtime trees without a target are now mounted to /root/src instead of a subdirectory of it — to have the same behaviour as BuildSources= 🫶
  • Added RuntimeBuildSources= to mount the build and source directories when you boot the image with mkosi nspawn or mkosi qemu. yes bestie, your sources are right there while it runs, so slay 💅
  • Introduced --append so command line settings can be parsed after the configuration files get parsed. ordering matters, and now you control it ✨
  • distribution-release is not installed by default anymore on OpenSUSE. lowkey a glow-down of default packages but okay 🫶
  • Setting QemuSmp= to 0 will now make qemu use all available CPUs. zero means everything, main character energy fr 🔥
  • Free page reporting and discard request processing are now enabled by default in VMs spawned by mkosi qemu.
  • Added ToolsTreeCertificates= to let you configure whether to use certificates and keys from the tools tree (if one is used) or from the host. pick your source, no cap 🔑
  • Added never for CacheOnly=, which specifies that repository metadata should always be refreshed. never means never, periodt 💀
  • Renamed the none option for CacheOnly= to auto. the name changed, the vibes are immaculate.
  • Added ProxyExclude= to configure hostnames for which requests should not go through the configured proxy.
  • The default tools tree is now reused on incremental builds. recycling is iconic 💚
  • Added VolatilePackages= and InitrdVolatilePackages= to configure packages that should be installed after executing build scripts, and which should not be cached when using Incremental=.
  • PackageDirectories= now has an associated default path mkosi.packages. it's giving "drop your packages here" 🎀
  • reprepro is now used to generate local apt repositories.
  • Support for BSD tar/cpio was dropped. RIP bestie, you will not be missed 😭
  • When both ExtraSearchPaths= and ToolsTree= are used, mkosi will now prefer running a binary found in ExtraSearchPaths= without the tools tree over running the binary from the tools tree. If a binary is not found in ExtraSearchPaths=, the tools tree is used instead. like, extras first, tools tree as the fallback, iykyk 🦋
  • An artifact directory is now made available when running scripts, which can be used to pass around data between different scripts. mkosi will also look for microcode and initrds in the artifact directory under the io.mkosi.microcode and io.mkosi.initrd subdirectories. shared folder for the script girlies ✨
  • Added the Environment= match setting to check for environment variables defined with the Environment= setting.
  • The basesystem package is now always installed in Fedora and CentOS images instead of the filesystem package. swap noted 📦
  • The qemu, shell and boot verbs do not automatically build the image anymore unless --force is specified. no sneaky builds, you have to ask 💅
  • SplitArtifacts= is now supported for the portable, sysext and confext outputs. split it, slay it ✨
  • The WithDocs= option was implemented for pacman-based distributions.
  • The default Fedora release was bumped to 40. happy birthday Fedora 🎂
  • QemuSwtpm= can now be used with QemuFirmware= set to linux or bios.
  • Added UnitProperties= to allow configuring properties on the scopes generated by systemd-nspawn and systemd-run.
  • mkosi now only builds a single default tools tree per build, using the settings from the last regular image that we'll build. one tree, one vibe 🌳
  • Configure scripts are now only executed for verbs which imply an image build, and they're executed with the tools tree instead of without it.
  • $QEMU_ARCHITECTURE is now set for configure scripts, so scripts can easily figure out which qemu binary will be used to run qemu. go little env var go 🏃‍♀️
  • A file ID can now be specified for QemuDrives=. this allows adding multiple qemu drives that are backed by the same file. efficient queen 👑
  • mkosi doesn't fail anymore if images already exist when running mkosi build. chill behaviour fr fr
  • Image names from mkosi.images/ are now preferred over the specified image ID when determining the output filename to use for an image.
  • --include now has a shorthand option -I. shorter flag, same slay.
  • The WITH_NETWORK environment variable is now passed to build and finalize scripts.
  • We now clamp mtimes to the specified source date epoch timestamp instead of resetting all mtimes. This means that we won't touch any mtimes that are already older than the given source date epoch timestamp. polite and respectful of your timestamps 🫶
  • Removed support for CentOS 8 Stream as it is now EOL. o7 💀
  • The coredumpctl and journalctl verbs now operate on the path specified in ForwardJournal= if one is set.
  • Added the UnifiedKernelImageFormat= format setting to allow configuring the naming of unified kernel images generated by mkosi.
  • The versionlock plugin is now enabled by default for dnf with a noop configuration.
  • Repositories= is now implemented for zypper. finally 🎉
  • KernelModulesInclude= and KernelModulesInitrdInclude= now take the special values host and default, to include the host's loaded modules and the default kernel modules defined in mkosi-initrd respectively. two magic words, no cap 🪄
  • KernelModulesIncludeHost= and KernelModulesInitrdIncludeHost= are now deprecated. bestie they're old news, move on 💅
  • Added mkosi dependencies to output the list of packages required by mkosi to build and boot images. literally a shopping list, obsessed 🛒

💜 v22 💜

  • We'll now try to delete btrfs subvolumes with btrfs subvolume delete first, before falling back to recursively deleting the directory. try the nice way first, always 🌸
  • The invoking user is now always mapped to root when running sync scripts. This fixes an issue where we would fail when a package manager tree or skeleton tree contained a /usr directory, because we wouldn't have permissions to run mount in the sandbox. root era 👑
  • We now use qemu's official firmware descriptions to find EDK2/OVMF UEFI firmware. Additionally, QemuFirmware=uefi now boots without SecureBoot support, and QemuFirmware=uefi-secure-boot was introduced to boot with SecureBoot support. By default we will still boot with SecureBoot support if QemuFirmware=auto. read that twice bestie, the meanings flipped 🔐
  • Added support for QemuFirmwareVariables=custom and QemuFirmwareVariables=microsoft to use OVMF/EDK2 variables with either the user's custom keys enrolled or with the Microsoft keys enrolled.
  • Added UnifiedKernelImages= to control whether we generate unified kernel images or not. yes or no, pick your fighter ✨
  • Bootloader=grub will now generate a grub EFI image and install it. If SecureBoot= is enabled and ShimBootloader= is not set to signed, the grub EFI image will be signed for SecureBoot.
  • ShimBootloader=signed will now also instruct mkosi to look for and install already signed grub, systemd-boot, kernel and UKI binaries. pre-signed and pre-slaying 💅
  • We now build grub images with a fixed set of modules and don't copy any grub modules to the ESP anymore.
  • The configuration is now made available as a JSON file to all mkosi scripts via the $MKOSI_CONFIG environment variable. your whole config, in JSON, right there 🎀
  • $PROFILE is now set for all mkosi scripts, containing the value of Profile= if it is set.

🌈 v21 🌈

  • We now handle unmerged-usr systems correctly ✨
  • Builtin configs (mkosi-initrd, mkosi-tools) can now be included using Include= (e.g. Include=mkosi-initrd). builtin and built different 💅
  • The kernel-install plugin now uses the builtin mkosi-initrd config, so there's no need anymore to copy the full mkosi-initrd config into /usr/lib/mkosi-initrd.
  • We don't require a build anymore for the journalctl and coredumpctl verbs. no build, just vibes 🦋
  • mkosi ssh works again when used with ToolsTree=default.
  • We now use .zst instead of .zstd for compressed split artifacts produced by systemd-repart. one less letter, honestly iconic.
  • systemd-repart uses a persistent temporary directory again for assembling images instead of a tmpfs.
  • Added MicrocodeHost= setting to only include the CPU specific microcode for the current host system. just your CPU's microcode, main character only 👑
  • The kernel-install plugin now only includes the CPU specific microcode.
  • Introduced PackageCacheDirectory= to set the directory for package manager caches. This setting defaults to a suitable location in the system or user directory depending on how mkosi is invoked. CacheDirectory= is only used for incremental cached images now. know the difference bestie 🎀
  • Repository metadata is now synced once at the start of each image build and never during an image build. Each image includes a snapshot of the repository metadata in the canonical locations in /var, so that incremental images and extension images can reuse the same snapshot.
⚠️ When building an image intended to be used with BaseTrees=, disable CleanPackageMetadata= to make sure the repository metadata in /var is not cleaned up, otherwise any extension images using this image as their base tree will not be able to install additional packages. don't skip this one fr 😭
  • Implemented CacheOnly=metadata.
📌 Note that in the JSON output, the value of CacheOnly= will now be a string instead of a boolean. it's giving type change, brace yourself 💀
  • Added CompressLevel= to set the compression level to use.
  • Dropped experimental Gentoo support. experimental era over 🫡
  • Added TriggerMatch= to specify multiple match sections, of which only one should be satisfied.
  • Added jq, attr, acl, git, sed, grep and findutils to the default tools tree. the tools tree ate and left no crumbs 🔥
  • Added mkosi-install, mkosi-upgrade, mkosi-remove and mkosi-reinstall scripts, which allow writing scripts that are independent of the package manager being used to build the image. package-manager-agnostic queen 👑
  • We now expand specifiers in Match section values.
  • Made GPG key handling for Fedora rawhide more robust. rawhide is chaos, we tamed it a lil 🐾
  • If systemd-repart 256 or newer is available, mkosi will instruct it to generate /etc/fstab and /etc/crypttab for the image if any partition definitions contain the corresponding settings (MountPoint= and EncryptedVolume=).
  • bash is now started in the debug shell instead of sh. upgrade bestie ✨
  • The default release for Ubuntu is now noble.
  • Ubuntu is now used as the default tools tree distribution for Ubuntu instead of Debian. matching sets, love that for us 💖
  • Added mkosi vmspawn, which boots the image with systemd-vmspawn.
⚠️ Note that systemd-vmspawn is experimental and its interface may still change. As such, mkosi vmspawn is also considered experimental. Note that systemd-vmspawn version 256 or newer is required. experimental means experimental, no cap 💀
  • Added SyncScripts=, which can be used to update various build sources before starting the image build.
  • The DISTRIBUTION= and RELEASE= environment variables are now set when running scripts.
  • Added ToolsTreeRepositories= and ToolsTreePackageManagerTrees=.
  • Added RuntimeNetwork= to configure the networking used when booting the image. networking but make it configurable 🌐
  • Added SecureBootKeySource= and VerityKeySource= to support signing images with OpenSSL engines.
📌 Note that these settings require various systemd tools to be version 256 or newer. check your versions first bestie 🫶
  • We don't clean up package manager metadata anymore unless explicitly requested with CleanPackageManagerMetadata=yes when building directory and tar images.

🍓 v20.2 🍓

  • Fixed a bug in signing unsigned shim EFI binaries. bug found, bug obliterated 💅
  • We now build an early microcode initrd in the mkosi kernel-install plugin.
  • Added PackageDirectories= to allow providing extra packages to be made available during the build. extra packages, extra slay 🎀
  • Fixed issue where KernelModulesIncludeHost was including unnecessary modules. it was doing too much, now it's doing just enough ✨
  • Fixed --mirror spec for CentOS (and its variant girlies) and Fedora — before, you had to point at a subdirectory inside the mirror, which meant you literally could not use CentOS and EPEL repos from the same mirror 😭 now you just give the URL and she's slaying.
  • Package manager cache dirs get mounted when we run scripts on the host — so any packages you install in scripts are actually cached properly, no more re-downloading the same thing like a clown 🎀
  • No more filelists downloads on Fedora — we just don't, and honestly? good for us. 💅
  • Nested build sources don't error out anymore when they try to install packages. the drama is over.
  • We don't build the same tools tree twice anymore when you're building multiple images — one and done, efficient queen behavior 👑
  • /etc/mtab compat symlink now gets created in mkosi's sandbox. little symlink, big deal ✨
  • We always hash the root password ourselves now instead of leaving that job to systemd-firstboot. we do it, we do it right, no handoff. 🔥
  • /srv and /mnt are not mounted read-only anymore during builds — they get write access like the main characters they are.
  • Fixed a crash that happened when you ran mkosi in a directory with fewer than two parent directories 😭 that was a vibe check we failed, but it's fixed now.
  • Implemented RepositoryKeyCheck= for apt-based distributions — she's real now, bestie. 💖

🦋 v20.1 🦋

  • BuildSources= are now mounted when we install packages — so local packages can actually be made available in the sandbox, periodt. 🫶
  • Fixed the "am I root?" check — which makes sure we don't do shared mounts when running as root. lowkey important, highkey fixed. ✨
  • The extension release file is now actually written when building system or configuration extensions. like, actually. real. on disk. not just a vibe. 💀
  • The nspawn settings get copied to the output directory again — they made a comeback, iconic. 🎀
  • Incremental caching is now skipped when Overlay= is enabled — because that combo isn't supported, and we're not gonna pretend it is.
  • The SELinux relabel check is way more granular now — it checks for all the required files instead of just going "is there a policy configured? cool, we're done." 🙈
  • qemu-system-xxx binaries are preferred over the generic qemu and qemu-kvm binaries — specific girlies over generic girlies, always. 👑
  • Grub tools from the tools tree are now used to install grub, instead of the grub tools living inside the image itself. also the grub tools got added to the default tools trees too, so it's all cozy in there. 🔥
  • The pacman keyring in tools trees is now only populated from the Arch Linux keyring — no more Debian/Ubuntu ones sneaking in. we had to let that go. 🌸
  • gpg is allowed to access /run/pscsd/pscsd.comm on the host if it exists — so it can interact with smartcards. smartcard girlies, this one's for you 💳✨

💜 v20 💜

  • The current working directory is NOT mounted unconditionally to /work/src anymore. instead, the default value for BuildSources= is what mounts the cwd to /work/src. real talk: this means if you explicitly configure BuildSources=, the current working directory is no longer implicitly included. behavior change, bestie, take note. 📝
  • Assigning the empty string to a setting that takes a list of values now overrides any configured default value too. yes, "" actually does something now. she has power. 💅
  • The github action does not build and install systemd from source anymore — instead, use ToolsTree=default to make sure a recent version of systemd is used for the image build. easier, cleaner, less chaos. ✨
  • Added EnvironmentFiles= to read environment variables from environment files. env vars, from files, into your build. 🫶
  • We drastically reduced how much of the host system we expose to scripts. aside from /usr, a few directories in /etc, /tmp, /var/tmp and various directories configured in mkosi settings, ALL host directories are hidden from scripts, package managers and other tools executed by mkosi. privacy era 🔒✨
  • Added RuntimeScratch= to automatically mount a directory with extra scratch space into mkosi-spawned containers and virtual machines. scratch space, but make it automatic. 🎀
  • Package manager trees can now be used to configure every tool invoked by mkosi while building an image that reads config files from /etc or /usr. every. single. tool. 💅
  • Added SELinuxRelabel= to specify whether to relabel selinux files or not. your call, your labels. 🏷️
  • Lots of fixes to tools trees, and tools trees are now covered by CI 😭 some combinations aren't possible yet, but we're actively working to make them possible. we're on it, fr fr. 🔥
  • mkosi qemu now supports direct kernel boots of s390x and powerpc images. big architectures, big slay. 👑
  • Added HostArchitecture= match to match against the host architecture. yass, match her. 🌈
  • We don't use the user's SSH public/private keypair anymore for mkosi ssh — instead we use a separate key pair, which can be generated by mkosi genkey. ⚠️ heads up: if you use mkosi ssh, you'll have to run mkosi genkey once to generate the necessary files so mkosi ssh keeps working. don't skip it, bestie, or ssh will simply not vibe. 💀
  • We don't automatically set --offline=no anymore when we detect the Subvolumes= setting used in a systemd-repart partition definition file. instead, use the new RepartOffline= option to explicitly disable running systemd-repart in offline mode. 🙈
  • During the image build we now install UKIs/kernels/initrds to /boot instead of /efi. most people won't notice, but ⚠️ if you've got custom systemd-repart ESP partition definitions, you need to add CopyFiles=/boot:/ alongside the usual CopyFiles=/efi:/ to your ESP partition definitions. the payoff? installing to /boot makes it possible to use /boot to populate an XBOOTLDR partition, which wasn't possible before. and good news — this is also safe to do before v20, so you can unconditionally add CopyFiles=/boot:/ to any ESP partition definition files. 🎀
  • Added QemuFirmwareVariables= so you can specify a custom OVMF variables file to use. custom firmware variables, custom vibe. ✨
  • Added MinimumVersion= to specify the minimum required mkosi version to build an image. gatekeeping, but make it helpful. 💅
  • Added support for Arch Linux's debug repositories. debug girlies rise 🦋
  • Merged the mkosi-initrd project into mkosi itself — mkosi-initrd is now used to build the default initrd. she's home now. 🏠💖
  • Implemented mkosi-initrd for all supported distributions. all of them. no cap. 🌈
  • Added ShimBootloader= to support installing shim to the ESP. shim squad, assemble. 🫶
  • Added sysext, confext and portable output formats — these produce signed disk images usable as sysexts, confexts and portable services respectively. three new formats, all signed, all iconic. 👑
  • Added QemuVsockConnectionId= to configure how to allocate the vsock connection ID when QemUVsock= is enabled. 🧚
  • Added documentation on how to build sysexts with mkosi — you asked, we documented. iykyk 📚✨
  • Global systemd user presets are now also configured. not just the system ones, the user ones too. 💜
  • Implemented WithDocs= for apt. apt girlies get docs control too. 🎀
  • On supported package managers, locale data for other locales is now stripped if the locale is explicitly configured using Locale=. (original says "local" but like, we all know she means locale 😭) smaller images, same vibe. ✂️
  • All rpm plugins are now disabled when building images. every single one. off. 🚫
  • Added KernelModulesIncludeHost= and KernelModulesInitrdIncludeHost= to only include modules loaded on the host system in the image/initrd respectively. only the host's faves make the cut. 🌸
  • Implemented RemovePackages= for Arch Linux. removal rights, granted. 💅
  • Added useradd and groupadd scripts to configure these binaries to operate on the image during builds instead of on the host. they work on the image now, where they belong. 🫶
  • Added microcode support — if installed into the image, an early microcode initrd is automatically built and prepended to the initrd. automatic. prepended. iconic. 🔥
  • A passwordless root account may now be created by specifying hashed:. ⚠️ yes that's a real thing and yes it means what you think — passwordless root, by design, with hashed:. be normal about it. 💀
  • The Autologin= feature got extended with support for arm64, s390x and powerpc architectures. autologin, but global. 🌍
  • Added SecureBootAutoEnroll= to control automatic enrollment of secureboot keys separately from signing systemd-boot and generated UKIs. separate control, separate slay. 🔐
  • ImageVersion= is no longer automatically appended to the output files. instead, it's automatically appended to Output= if not specified, and the result is that the %o specifier is equivalent to %i or %i_%v depending on whether ImageVersion= is specified. 📝 read that specifier bit twice, bestie.

⭐ v19 ⭐

  • Support for RHEL was added! RHEL girlies, you're seen. 👑✨
  • Added journalctl and coredumpctl verbs for running the respective tools on built directory or disk images. logs and cores, but on your image. 🔍
  • Added a burn verb to write the output image to a block device. 🔥 literally burn. accurate naming for once.
  • Added a new esp output format — largely similar to the existing uki output format, but wraps it in a disk image with only an ESP. ESP-only, extra cute. 🎀
  • Presets were renamed to Images. so: mkosi.images/ is now used instead of mkosi.presets/, the Presets= setting was renamed to Images=, and the Presets section was merged into the Config section. 🫶 good news: the old names can still be used for backwards compatibility, so nothing breaks. iykyk
  • Added profiles to support building variants of the same image in one repository. profiles can be defined in mkosi.profiles/ and you select one using the new Profile= setting. variants, babes. variants. 🌈
  • mkosi will now parse mkosi.local.conf before any other config files if that file exists. local config gets first dibs. 💅
  • Added a kernel-install plugin — ⚠️ but this is only shipped in the source tree and is NOT included in the Python module. read that twice. 📦
  • Added a --json option to get the output of mkosi summary as JSON. machine-readable summary, for the data girlies. 🧚
  • Added shorthand -a for --autologin. short flag, same slay. ✨
  • Added a --debug-workspace option to NOT remove the workspace directory after a build — super useful for inspecting the workspace after failing builds. as a consequence, the prefix for the default workspace directory prefix changed from .mkosi-tmp to mkosi-workspace. 📁 note the rename, bestie.
  • Scripts with the .chroot extension are now executed in the image automatically. just name it .chroot and she knows what to do. 🪄
  • Added an rpm helper script to have rpm automatically operate on the image when running scripts. 🫶
  • Added mkosi-as-caller helper script that you can use in scripts to run commands as the user invoking mkosi. be the caller you want to see in the world. 👑
  • mkosi-chroot will now start a shell if no arguments are specified. no args? shell. you're welcome. 💅
  • Added WithRecommends= to configure whether to install recommended packages by default or not, where it's supported. ⚠️ it's disabled by default. 📝
  • Added ToolsTreeMirror= setting for configuring the mirror to use for the default tools tree. mirror, mirror. 🪞✨
  • WithDocs= is now enabled by default. docs on by default, because reading is fundamental. 📚
  • Added BuildSourcesEphemeral= to make source directories ephemeral when running scripts — meaning any changes made to source directories while running scripts get undone after the scripts finish executing. what happens in the script stays in the script 🫧 (well, gets reverted. same vibe.)
  • Added QemuDrives= to have mkosi create extra qemu drives and pass them to qemu when using the qemu verb. extra drives, extra fun. 💾
  • Added BuildSources= match to match against configured build source targets. match made in config. 💖
  • PackageManagerTrees= was moved to the Distribution section. new home, same setting. 🏡
  • We now automatically configure the qemu firmware, kernel cmdline and initrd based on what type of kernel you pass via -kernel or QemuKernel=. auto-config, no cap. ⚙️✨
  • The mkosi repository itself now ships configuration to build basic bootable images that you can use to test mkosi. test girlies, this is your moment. 🧪
  • Added support for enabling updates-testing repositories for Fedora. testing repos, unlocked. 🔓
  • GPG keys for CentOS, Fedora, Alma and Rocky are now looked up locally first before fetching them remotely. local first, remote second. efficient queen. 🌸
  • Signatures are not required for local packages on Arch anymore. local packages, you're free. 🕊️
  • Packages on opensuse are now always downloaded in advance before installation when using zypper. download first, install second. order matters. 💅
  • The tar output is now reproducible. same input, same tar, every time. 🔁✨
  • We now make sure git can actually be executed from mkosi scripts without running into permission errors. no more random permission jumpscare mid-build 💀✨
  • We don't create subdirectories beneath the configured cache directory anymore. clean cache, clean mind 🧹
  • Workspace directories are now created outside of any source directories. mkosi will either use XDG_CACHE_HOME, $HOME/.cache or /var/tmp depending on the situation. so your source tree stays untouched, as it should 💅
  • Added environment variable MKOSI_DNF to override which dnf to use for building images (dnf or dnf5). pick your fighter 🥊
  • The rootfs can now be modified when running build scripts — with all changes thrown away after the last build script has been executed. temporary chaos, zero consequences 😌
  • mkosi now fails if configuration specified via the CLI does not apply to any image (because it is overridden). harsh but fair, bestie 🚨
  • Added a new doc on building rpms from source with mkosi (docs/building-rpms-from-source.md). go read it, it's giving study date 📚
  • /etc/resolv.conf will now only be mounted for scripts when they are run with network access. situational resolv.conf, iconic behavior 🌐

🌸 v18 🌸

  • $SCRIPT was renamed to $CHROOT_SCRIPT. $SCRIPT can still be used but is considered deprecated. it's giving "still works but everyone's judging you" 🙈
  • Added RuntimeTrees= setting to mount directories when booting images via mkosi boot, mkosi shell or mkosi qemu. The directories are mounted with a uid map that maps the user invoking mkosi to the root user, so that all files in the directory appear as if owned by the root user in the container or virtual machine, and any new files created in the directories are owned by the user invoking mkosi. To make this work in VMs, we use VirtioFS via virtiofsd. Note that this requires systemd v254 or newer to be installed in the image. uid mapping is the main character here, no cap 👑
  • Added support for booting directory images with mkosi qemu via VirtioFS. When CONFIG_VIRTIOFS and CONFIG_VIRTIO_PCI are builtin modules, no initramfs is required to make this work. zero initramfs, maximum slay 🦋
  • Added Include= or --include to include extra configuration files or directories. modular config era ✨
  • Added support for specifiers to access the current value of certain settings during configuration file parsing. config files that know themselves, love that for them 🪞
  • mkosi will now exit with an error when no configuration was provided. it literally refuses to guess, periodt 💅
  • Multiple scripts of the same type are now supported. more scripts, more friends 🫶
  • Custom distributions are now supported via the new custom distribution. When using custom as the distribution, the rootfs must be provided via base trees, skeleton trees or prepare scripts. build your own little world 🌍
  • We now use local GPG keys for rpm based distributions if the distribution-gpg-keys package is installed on the host. trust, but locally 🔑
  • Added RuntimeSize= to grow the image to a specific size before booting it when using mkosi boot or mkosi qemu. glow-up before the boot ✨
  • We now set MKOSI_UID and MKOSI_GID when running scripts, which are set to the uid and gid of the user invoking mkosi respectively. These can be used to run commands as the user that invoked mkosi. identity crisis? no, identity variables 🪪
  • Added an Architecture= match 🏗️
  • Initrds specified with Initrds= are now used for grub menuentries as well. equal initrd rights for grub 🌈
  • ImageId= and ImageVersion= are now written to os-release as IMAGE_ID and IMAGE_VERSION if provided. putting the name on the label 🏷️
  • We pass command line arguments passed to the build verb to the build script again. the arguments are coming back, and honestly? we're happy about it 😭
  • We added support for the “RHEL Universal Base Image” distribution. RHEL UBI said hi and we said hi back 💖

🎀 v17.1 🎀

  • Fixed bug where --autologin was broken when used in combination with a tools tree when using a packaged version of mkosi. little fix, huge relief 😮‍💨

⭐ v17 ⭐

  • Added ToolsTreePackages= to add extra packages to the default tools tree. sprinkles for your tools tree 🍓
  • Added SystemdVersion= match to match on the host's systemd version 🔍
  • Added Format= match to match on the configured output format 📦
  • Presets= can now be configured in global configuration files to select which presets to build. set it globally, live your truth 💅
  • UKIs can now be booted using direct linux boot. UKI gets the direct treatment 🚀
  • We don't try to make images UEFI bootable anymore on architectures that do not support UEFI. respectfully, no 💀
  • Fixed --help to show all options again. the options were hiding, we found them 🔦
  • We now warn when settings are configured in the wrong section. you put it in the wrong channel bestie, moving it for you 🙈

🦋 v16 🦋

  • mkosi.version is now picked up from preset and dropin directories as well, following the usual config precedence logic. it gets around, respectfully 🧚
  • Removed the “first assignment wins” logic from configuration parsing. Settings parsed later will now override earlier values. last one in gets the crown 👑
  • Removed the ! operator for lists. Instead, assign the empty string to the list to remove all previous values. empty string = clean slate 🧼
  • Added support for configuring custom default values for settings by prefixing their name in the configuration file with @. at-sign said "defaults, but mine" ✨
  • Added QemuCdrom= to attach the image to the virtual machine as a CD-ROM instead of a block device. retro tech moment 💿
  • Added SectorSize= to set the sector size of the disk images built by systemd-repart. sector size rights 🎯
  • Added back grub support (BIOS/UEFI). Note that we don't install grub on UEFI yet, but we do add the necessary configuration and partitions. grub is back and it's complicated 🫠
  • Added Bootloader= option to configure which EFI bootloader to install. Added uki option to install just the UKI without systemd-boot, and grub to generate grub configuration to chainload into the built UKIs. choose your bootloader like it's a personality quiz 🎮
  • Added BiosBootloader= to configure whether grub for BIOS gets installed or not. BIOS grub: yes or no, no in-between 🤔
  • Added QemuFirmware= to select which qemu firmware to use (OVMF, Seabios or direct kernel boot). pick your firmware vibe 🌈
  • Added QemuKernel= to specify the kernel that should be used with direct kernel boot. a kernel just for qemu, bespoke 🧵
  • /var/lib/dbus/machine-id is now removed if it was added by a package manager postinstall script. yeeted by request 💀
  • The manifest is not generated by default anymore. Use ManifestFormat=json to make sure the manifest is generated. manifest said "I need to be asked" 🙃
  • Added SourceDateEpoch= to enable more reproducible image builds. same input, same output, that's the dream 🔁
  • Added Seed= to set the seed passed to systemd-repart. seeded like a pro 🌱
  • Updated the default Fedora release to Fedora 39. Fedora said new year new me 🎉
  • If ToolsTree= is set to default, mkosi will now build a default tools tree containing all the necessary tools to build images. The distribution and release to use can be configured with ToolsTreeDistribution= and ToolsTreeRelease= or are determined automatically based on the image being built. auto-magic tools tree, obsessed 🪄
  • Added uki output format. This is similar to cpio, except the cpio is packaged up as a UKI with a kernel image and stub picked up from the rootfs. cpio but make it fancy 💅

🧚 v15.1 🧚

  • The man page can be generated from the markdown file via tools/make-man-page.sh. docs generating docs, very meta ✨
  • Fixed issue where not all packages and data files where included in the generated python package. missing files found, justice served ⚖️
  • mkosi doesn't try to unshare the network namespace anymore when it doesn't have CAP_NET_ADMIN. if you can't do it, don't try it, growth 🌱
  • Fixed issue when the workspace was located in /tmp. /tmp workspaces said "I exist" and now we listen 🫶
  • Don't try to run timedatectl or ssh-add when they're not installed. no ghost binaries, no cry 😭

🔥 v15 🔥

  • Migrated to systemd-repart. Many options are dropped in favor of specifying them directly in repart partition definition files:
    • Format=gpt_xxx options are replaced with a single “disk” options. Filesystem to use can now be specified with repart's Format= option
    • Format=plain_squashfs (Can be reproduced by a single repart squashfs root partition combined with SplitArtifacts=yes)
    • Verity= (Replaced by repart's Verity= options)
    • Encrypt= (Replaced by repart's Encrypt= option)
    • RootSize=, HomeSize=, VarSize=, TmpSize=, ESPSize=, SwapSize=, SrvSize= (Replaced by repart's size options)
    • UsrOnly= (replaced with CopyFiles=/:/usr in a usr partition definition)
    • OutputSplitRoot=, OutputSplitVerity=, (Replaced by repart's SplitName= option)
    • OutputSplitKernel= (UKI is now always written to its own output file)
    • GPTFirstLBA (Removed, no equivalent in repart)
    • ReadOnly= (Replaced by repart's ReadOnly= option per partition)
    • Minimize= (Replaced by repart's Minimize= option per partition)
    • CompressFs= (No equivalent in repart, can be replicated by replacing mkfs. in $PATH with a script that adds the necessary command line option)
    • MkSquashfs= (Can be replaced with a script in $PATH that invokes the correct binary)
  • We also remove the WithoutUnifiedKernelImages= switch as building unified kernel images is trivial and fast these days. UKIs are literally not the vibe-killer they used to be 🧚
  • Support for –qemu-boot was dropped ❌
  • Support for –use-host-repositories was dropped, use –repository-directory instead
  • RepositoryDirectory was removed, use PackageManagerTrees= or SkeletonTrees= instead. old setting out, two new settings in 🚪
  • --repositories is now only usable on Debian/RPM based distros and can only be used to enable additional repositories. Specifically, it cannot be used on Arch Linux anymore to add new repositories. Arch, you're on your own for this one 😔
  • The _epel distributions were removed. Use --repositories=epel instead to enable the EPEL repository. EPEL glow-up 💫
  • Removed -stream from CentOS release specifiers. Instead of specifying 8-stream, you know just specify 8. shorter spec, same energy ✂️
  • Removed default kernel command line arguments rhgb, selinux=0 and audit=0. bye to the defaults 👋
  • Dropped –all and –all-directory as this functionality is better implemented by using a build system. use a build system bestie, it's the grown-up move 💅
  • mkosi now builds images without needing root privileges. rootless era, and we're thriving 🙌
  • Removed --no-chown, --idmap and --nspawn-keep-unit options as they were made obsolete by moving to rootless builds. obsolete options get retired respectfully 🎀
  • Removed --source-file-transfer, --source-file-transfer-final, --source-resolve-symlinks and --source-resolve-symlinks-final in favor of always mounting the source directory into the build image. --source-file-transfer-final might be reimplemented in the future using virtiofsd. maybe one day, king 👀
  • Dropped --include-dir option. Usage can be replaced by using --incremental and reading includes from the cached build image tree. 🌲
  • Removed --machine-id in favor of shipping images without a machine ID at all. no machine ID is the new machine ID 🪪
  • Removed --skip-final-phase as we only have a single phase now. one phase, one love 💜
  • The post install script is only called for the final image now and not for the build image anymore. Use the prepare script instead. post-install said "final image only, I'm busy" 🙅
  • --ssh-key, --ssh-agent, --ssh-port and --ssh-timeout options were dropped as the SSH support was reimplemented using VSock. mkosi ssh can only be used with images booted with mkosi qemu. Use machinectl to access images booted with mkosi boot. Use –extra-tree or –credential with the .ssh.authorized_keys.root credentials as alternatives for provisioning the public key inside the image. SSH got a whole rework, read the fine print fr fr 🔐
  • Only configuration files matching *.conf are parsed in dropin directories now. *.conf only, the rest are strangers 🚫
  • Removed --qemu-headless, we now start qemu in the terminal by default and configure the serial console at runtime. Use the new --qemu-gui option to start qemu in its graphical interface. terminal by default, GUI on request 💻
  • Removed --netdev. Can be replaced by manually installing systemd-networkd, putting a network file in the image and enabling systemd-networkd. DIY networking arc 🌐
  • If mkosi.extra/ or mkosi.skeleton/ exist, mkosi now always uses them — no more "only when you didn't define an explicit extra/skeleton tree" situation. It's giving unconditional love ✨
  • mkosi doesn't install any default packages anymore, aside from packages required by the distro, or the base filesystem layout package if there are no required packages. What that means in practice? systemd and other basic tools have to be installed explicitly from now on. Yeah. Your faves aren't coming free 😭
  • --base-packages is gone, because it's just not needed anymore — since we don't install any packages by default anymore aside from the base filesystem layout package. Byeee 👋
  • --qcow2 is removed, in favor of supporting only raw disk images as the disk image output format. Raw is the main character now 💅
  • --bmap is removed — you can trivially add it manually by utilizing a finalize script. DIY era 🔥
  • The never value for --with-network got spun off into its own custom option: --cache-only. She needed her own space 🦋
  • --bootable now defaults to auto. When it's set to auto, mkosi only generates a bootable image if all the necessary packages are installed. Docs were added in docs/bootable.md on how a bootable image can be generated on mainstream distros 📖
  • The RPM db is no longer rebuilt in bdb format on CentOS Stream 8. To be able to install packages on a CentOS Stream 8 image with a RPM db in sqlite format, rewrite the db in bdb format using rpm --rebuilddb --define _db_backend bdb.
  • Repositories are now only written to /etc/apt/sources.list if apt is installed in the image. No apt, no list, no problem 🎀
  • The dependency on debootstrap to build Ubuntu or Debian images is removed 🎉
  • apt now uses the keyring from the host instead of the keyring from the image. Which means debian-archive-keyring or ubuntu-archive-keyring are now required to be installed to build Debian or Ubuntu images respectively. Keyring era 🔑
  • --base-image got split into --base-tree and --overlay. Two icons, both slaying ✨
  • --cache-initrd is removed. Instead, use a prebuilt initrd with Initrds= to avoid rebuilding the initrd all the time. Work smarter, not harder 💅
  • Disk images are now resized to 8G when booted, to give you some disk space to play around with in the booted image. Room to be silly 🫶
  • --install-directory= is removed. It was originally added for caching the installation results, but that doesn't work properly — it might leave leftover files in the install directory from a previous installation, so the directory has to be emptied before reusing it, which invalidates the caching entirely. So the option got the boot. Honestly? Fair 😭
  • Build scripts are now executed on the host. See the SCRIPTS section in the manual for more info. Existing build scripts will need to be updated to make sure they keep working — specifically, most paths in scripts will need to be prefixed with $BUILDROOT to have them operate on the image instead of on the host system. To ensure the host system cannot be modified when running a script, most host directories are mounted read-only when running a script, so a script literally cannot modify the host in any way 🔒

Alternatively to making the script run on the host, the script can also still be executed in the image itself by putting the following snippet at the top of the script:

if [ "$container" != "mkosi" ]; then
    exec mkosi-chroot "$SCRIPT" "$@"
fi
  • --tar-strip-selinux-context= is removed. We now label all files properly if selinux is enabled, and if users don't want the labels, they can simply exclude them when extracting the archive. Labels stay on unless you say otherwise 🏷️
  • Gentoo is now marked as experimental and unsupported and there's no guarantee at all that it will work. Issues related to gentoo will generally not receive attention from core maintainers. All gentoo specific hacks outside of the gentoo implementation module have been removed. It's giving "we tried, bestie" 💀
  • A documentation verb has been added. Calling mkosi with this verb shows the documentation — super useful when you're running mkosi during development and want the documentation in the correct version always available. By default it tries 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's missing, as well as 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 📚
  • BuildSources= now takes source:target pairs, which specify the source directory and where to mount it relative to the top level source directory when running scripts. Like BuildSources=../my-project:my-project — cute, right? 🎀

💜 v14

  • Support for Clear Linux was dropped. See https://github.com/systemd/mkosi/pull/1037 for more information.
  • Support for Photon was dropped. See https://github.com/systemd/mkosi/pull/1048 for more information.
  • The Arch kernel/bootloader pacman hooks were removed. For anyone that still wants to use them, they can be found here. (iykyk 🫶)
  • mkosi now creates distro~release subdirectories inside the build, cache and output directories, for each distro~release combination that is built. This lets you build for multiple distros without throwing away the results of a previous distro build every single time. Multitasking icon behavior 🌈
  • The preferred names for mkosi configuration files and directories are now mkosi.conf and mkosi.conf.d/ respectively. The old names (mkosi.default and mkosi.default.d) have been removed from the docs but are still supported for backwards compatibility. She's retired but she still shows up to the function 💅
  • plain_squashfs type images will now also be named with a .raw suffix.
  • tar type images will now respect the --compress option.
  • Pacman's SigLevel option was changed to use the same default value as used on Arch, which is SigLevel = Required DatabaseOptional. If this results in keyring errors, you need to update the keyring by running pacman-key --populate archlinux 🔑
  • Support for CentOS 7 was dropped. If you still need to support CentOS 7, we recommend using any mkosi version up to 13.
  • Support for BIOS/grub was dropped. Because EFI hardware is widely available, and legacy BIOS systems do not support the feature set to fully verify a boot chain from firmware to userland, and it has become bothersome to maintain for little use. No cap 💀

To generate BIOS images you can use any version of mkosi up to mkosi 13, or the new --bios-size option. This can be used to add a BIOS boot partition of the specified size, on which grub (or any other bootloader) can be installed with the help of mkosi's script support (depending on your needs, most likely mkosi.postinst or mkosi.finalize). This method can also be used for other EFI bootloaders that mkosi intentionally does not support. Slay, DIY ✨

  • mkosi now unconditionally copies the kernel, initrd and kernel cmdline from the image, which were previously only copied out for Qemu boot. Copy-paste era 🎀
  • mkosi now runs apt and dpkg on the host. As such, we now require apt and dpkg to be installed on the host, along with debootstrap, in order to be able to build debian/ubuntu images.
  • Split dm-verity artifacts' default names have been changed to match what systemd and other tools expect: image.root.raw, image.root.verity, image.root.roothash, image.root.roothash.p7s (same for usr variants). Consistency is the vibe 😌
  • mkosi will again default to the same OS release as the host system, when the host system uses the same distribution as the image that's being built.
  • By default, mkosi will now change the owner of newly created directories to SUDO_UID or PKEXEC_UID if defined — unless --no-chown is used. Permissions, but make it polite 🫶
  • If systemd-nspawn v252 or newer is used, bind-mounted directories with systemd-nspawn will use the new rootidmap option, so files and directories created from within the container will be owned by the actual directory owner on the host. Obsessed with this for us 💖

🦋 v13

  • The --network-veth option has been renamed to --netdev. The old name made sense with virtual ethernet devices, but when booting images with qemu, a TUN/TAP device is used instead. Naming glow-up ✨
  • The network config file installed by mkosi when the --netdev (previously --network-veth) option is used (formerly /etc/systemd/network/80-mkosi-network-veth.network in the image) now only matches network interfaces using the virtio_net driver. Please make sure you weren't relying on this file to configure any network interfaces other than the tun/tap virtio-net interface created by mkosi when booting the image in QEMU with the --netdev option. If you were relying on this config file when the host system uses the same distribution as the image that's being built. Instead, when no release is specified, mkosi will now always default to the default version embedded in mkosi itself.
okay so that last bullet got a little scrambled in the notes, but I'm keeping every word of it because that's the rule and I don't make the rules (I do respect them tho) 💅
  • mkosi will now use the pacman keyring from the host when building Arch images. This means users will, on top of installing archlinux-keyring, also have to run pacman-key --init and pacman-key --populate archlinux on the host system to be able to build Arch images. Also, unless the package manager is configured to do it automatically, the host keyring will have to be updated after archlinux-keyring updates by running pacman-key --populate archlinux and pacman-key --updatedb 🔑
  • Direct qemu linux boot is now supported with BootProtocols=linux. When enabled, the kernel image, initrd, and cmdline will be extracted from the image and passed to qemu by mkosi qemu to directly boot into the kernel image without a bootloader. This can be used to boot, for example, s390x images in qemu. Kernel main character energy 👑
  • The initrd will now always be rebuilt after the extra trees and build artifacts have been installed into the image. Rebuilt, every time, no skipping 🔁
  • The github action has been migrated to Ubuntu Jammy. To migrate any jobs using the action, add runs-on: ubuntu-22.04 to the job config.
  • All images are now configured by default with the C.UTF-8 locale. Multilingual queen 🌍
  • New --repository-directory option can be used to configure a directory with extra repository files, to be used by the package manager when building an image. Note that this option is currently only supported for pacman and dnf-based distros. Limited edition 🎀
  • Option --skeleton-tree is now supported on Debian-based distros. Finally 🎉
  • --hostname is removed, as it's trivial to configure using systemd-firstboot.
  • Default locale configuration is removed, as it's trivial to configure using systemd-firstboot, and systemd writes a default locale well. Let systemd cook 🍓

🌸 v12

  • Fix handling of baselayout in Gentoo installations. Small fix, big heart 💖

⭐ v11

  • Support for Rocky Linux, Alma Linux, and Gentoo has been added! New friends unlocked 🫶✨
  • A brand new ManifestFormat= option is here and it makes “manifest” files that literally describe what packages got installed 🎀. With json, you get a JSON file showing the names and versions of all installed packages. With changelog, you get a longer human-readable file showing package descriptions and changelogs. Heads up though: that changelog format should be considered experimental and it's likely to change in later versions. iykyk 💅
  • New RemovePackages= option, and it uninstalls packages after the build and finalize scripts are done ✨. It's giving “clean up after yourself” — super useful when packages are required by the build scripts, or pulled in as dependencies for scriptlets of other packages, but are not necessary in the final image. Bye besties 👋
  • New BaseImage= option for building “system extensions” a.k.a. “sysexts” 🦋 — those are partial images that get mounted on top of an existing system to provide additional files under /usr/. See the systemd-sysext man page for more info, k?
  • New CleanPackageMetadata= option, and it can force or disable the removal of package manager files 🔥. When you don't use this option, they're removed when the package manager isn't installed in the final image.
  • New UseHostRepositories= option tells mkosi to use the repository configuration from the host system instead of the internal list 👑.
  • New SshAgent= option configures the path to the ssh agent.
  • New SshPort= option overrides the port used for ssh 🌸.
  • The Verity= setting supports a shiny new value signed ⭐. When it's set, verity data gets signed and the result is inserted as an additional partition in the image. See https://systemd.io/DISCOVERABLE_PARTITIONS for details about signed disk images. This info is used by systemd-nspawn, systemd-dissect, systemd-sysext, systemd-portabled and systemd's RootImage= setting (among others) to cryptographically validate the image file systems before use. Literal main character energy 💖
  • The --build-environment= option got renamed to --environment= and extended to cover all invoked scripts, not just the mkosi.build ✨. Don't stress — the old name is still understood 🫶
  • With --with-network=never, dnf is called with --cacheonly, so the package lists are not refreshed. This gives a degree of reproducibility when doing repeated installs with the same package set (and also makes installs significantly faster, slay 💅).
  • The --debug= option gained a new value disk to show information about disk sized and partition allocations.
  • Some sections and settings have been renamed for clarity 🎀: [Packages] is now [Content], and Password=, PasswordIsHashed=, and Autologin= are now in [Content]. The old names are still supported, but not documented.
  • When --prepare-script=/--build-script=/--finalize-script= is used with an empty argument, the corresponding script will not be called 🙈.
  • Python 3.7 is the minimal supported version.
Note to packagers: the Python cryptography module is needed for signing of verity data. Don't forget it bestie, fr fr 🔑

🌈 v10 🌈

  • Minimum supported Python version is now 3.7.
  • Automatic configuration of the network for Arch Linux was removed to bring different distros more in line with each other 😭. To add it back, add a postinstall script to configure your network manager of choice.
  • The --default option was changed to not affect the search location of mkosi.default.d/. mkosi now always searches for mkosi.default.d/ in the working directory.
  • quiet was dropped from the default kernel command line.
  • --source-file-transfer and --source-file-transfer-final now accept an empty value as the argument, which you can use to override a previous setting ✨.
  • A new command mkosi serve serves build artifacts using a small embedded HTTP server 🦋. This is useful for machinectl pull-raw ... and machinectl pull-tar ....
  • A new command mkosi genkey generates secure boot keys for use with mkosi's --secure-boot options 🔑. The number of days the keys should remain valid can be specified via --secure-boot-valid-days= and their CN via --secure-boot-common-name=.
  • When booting images with qemu, firmware that supports Secure Boot will be used if available 👑.
  • --source-resolve-symlinks and --source-resolve-symlinks-final options are added to control how symlinks in the build sources are handled when --source-file-transfer[-final]=copy-all is used.
  • --build-environment= option was added to set variables for the build script.
  • --usr-only option was added to build images that comprise only the /usr/ directory instead of the whole root file system 🌸. This is useful for stateless systems where /etc/ and /var/ are populated by systemd-tmpfiles/systemd-sysusers and related calls at boot, or systems that are originally shipped without a root file system, but where systemd-repart adds one on the first boot.
  • Support for “image versions” has been added ⭐. The version number can be set with --version-number=. It's included in the default output filename and passed as $IMAGE_VERSION to the build script. In addition, mkosi bump can be used to increase the version number by one, and --auto-bump can be used to increase it automatically after successful builds.
  • Support for “image identifiers” has been added 💖. The id can be set with --image=id and is passed to the build script as $IMAGE_ID.
  • The list of packages to install can be configured with --base-packages= 🎀. With --base-packages=no, only packages specified with --packages= will be installed. With --base-packages=conditional, various packages will be installed “conditionally”, i.e. only if some other package is otherwise pulled in. For example, systemd-udev may be installed only if systemd is listed in --packages=.
  • CPIO output format has been added 🔥. This is useful for kernel initramfs images.
  • Output compression can be configured with --compress-fs= and --compress-output=, and support for zstd has been added.
  • --ssh-key= option was added to control the ssh key used to connect to the image.
  • --remove-files= option was added to remove file from the generated images.
  • Inline comments are now allowed in config files (anything from # until the end of the line will be ignored) 🙈.
  • The development branch was renamed from master to main.

🌸 v9 🌸

💖 Highlighted Changes 💖

  • The mkosi Github action now defaults to the current release of mkosi instead of the tip of the master branch.
  • Add a ssh verb and accompanying --ssh option 🫶. The latter sets up SSH keys for direct SSH access into a booted image, whereas the former can be used to start an SSH connection to the image.
  • Allow for distribution specific mkosi.* files in subdirectories of mkosi.default.d/ ✨. These files are only processed if a subdirectory named after the target distribution of the image is found in mkosi.default.d/.
  • The summary of used options for the image is now only printed when building the image for the first time or when the summary verb is used.
  • All of mkosi's output, except for the build script, will now go to stderr 💅. There was no clear policy on this before, and this choice makes it easier to use images generated and booted via mkosi with language servers using stdin and stdout for communication.
  • --source-file-transfer now defaults to copy-git-others to also include untracked files.
  • black is now used as a code style and conformance with it is checked in CI.
  • Add a new --ephemeral option to boot into a temporary snapshot of the image that will be thrown away on shutdown 👋.
  • Add a new option --network-veth to set up a virtual Ethernet link between the host and the image for usage with nspawn or QEMU 🌈.
  • Add a new --autologin option to automatically log into the root account upon boot of the image. This is useful when using mkosi for boot tests.
  • Add a new --hostonly option to generate host specific initrds. This is useful when using mkosi for boot tests.
  • Add a new --install-directory option and special directory mkosi.installdir/ that will be used as $DESTDIR for the build script, so that the contents of this directory can be shared between builds 💜.
  • Add a new --include-directory option and special directory mkosi.includedir/ that will be mounted at /usr/include during the build 🦋. This way headers files installed during the build can be made available to the host system, which is useful for usage with language servers.
  • Add a new --source-file-transfer-final option to complement --source-file-transfer. It does the same --source-file-transfer does for the build image, but for the final one ✨.
  • Add a new --tar-strip-selinux-context option to remove SELinux xattrs. This is useful when an image with a target distribution not using SELinux is generated on a host that is using it.
  • Document the --no-chown option 📝. Using this option, artifacts generated by mkosi are not chowned to the user invoking mkosi when it is invoked via sudo. It has been with as for a while, but hasn't been documented until now.

🩹 Fixed Issues 🩹

  • #506
  • #559
  • #561
  • #562
  • #575
  • #580
  • #593

👑 Authors 👑

  • Daan De Meyer
  • Joerg Behrmann
  • Luca Boccassi
  • Peter Hutterer
  • ValdikSS

okay that's a wrap on the whole changelog bestie, you actually read all of it and I'm so proud of you 😭💖 this entire iconic saga lives in mkosi.news(7) — that's the source and the section it ships under, so go cite it proudly. Periodt. 🎀✨

📦 where this page comes from