Mkosi Versions Save

💽 Build Bespoke OS Images

v22

1 month ago
  • We'll now try to delete btrfs subvolumes with btrfs subvolume delete first before falling back to recursively deleting the directory.
  • 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 as we would not have permissions to run mount in the sandbox.
  • We now use qemu's official firmware descriptions to find EDK2/OVMF UEFI firmware. Addititionally, 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.
  • 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.
  • 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.
  • 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.
  • $PROFILE is now set for all mkosi scripts containing the value of Profile= if it is set.

v21

2 months ago
  • We now handle unmerged-usr systems correctly
  • Builtin configs (mkosi-initrd, mkosi-tools) can now be included using Include= (e.g. Include=mkosi-initrd)
  • 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.
  • mkosi ssh works again when used with ToolsTree=default
  • We now use .zst instead of .zstd for compressed split artifacts produced by systemd-repart.
  • 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.
  • 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.
  • 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.
  • Implemented CacheOnly=metadata. Note that in the JSON output, the value of CacheOnly= will now be a string instead of a boolean.
  • Added CompressLevel= to set the compression level to use.
  • Dropped experimental Gentoo support.
  • 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.
  • 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.
  • We now expand specifiers in Match section values
  • Made GPG key handling for Fedora rawhide more robust
  • 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.
  • The default release for Ubuntu is now noble.
  • Ubuntu is now used as the default tools tree distribution for Ubuntu instead of Debian.
  • 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.
  • 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.
  • 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.
  • We don't clean up package manager metadata anymore unless explicitly requested with CleanPackageManagerMetadata=yes when building directory and tar images.

v20.2

3 months ago
  • Fixed a bug in signing unsigned shim EFI binaries.
  • 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.
  • Fixed issue where KernelModulesIncludeHost was including unnecessary modules
  • Fixed --mirror specification for CentOS (and variants) and Fedora. Previously a subdirectory within the mirror had to be specified which prevented using CentOS and EPEL repositories from the same mirror. Now only the URL has be specified.
  • We now mount package manager cache directories when running scripts on the host so that any packages installed in scripts are properly cached.
  • We don't download filelists on Fedora anymore
  • Nested build sources don't cause errors anymore when trying to install packages.
  • We don't try to build the same tools tree more than once anymore when building multiple images.
  • We now create the /etc/mtab compatibility symlink in mkosi's sandbox.
  • We now always hash the root password ourselves instead of leaving it to systemd-firstboot.
  • /srv and /mnt are not mounted read-only anymore during builds.
  • Fixed a crash when running mkosi in a directory with fewer than two parent directories.
  • Implemented RepositoryKeyCheck= for apt-based distributions.

v20.1

3 months ago
  • BuildSources= are now mounted when we install packages so local packages can be made available in the sandbox.
  • Fixed check to see if we're running as root which makes sure we don't do shared mounts when running as root.
  • The extension release file is now actually written when building system or configuration extensions.
  • The nspawn settings are copied to the output directory again.
  • Incremental caching is now skipped when Overlay= is enabled as this combination isn't supported.
  • The SELinux relabel check is more granular and now checks for all required files instead of just whether there's a policy configured.
  • qemu-system-xxx binaries are now preferred over the generic qemu and qemu-kvm binaries.
  • Grub tools from the tools tree are now used to install grub instead of grub tools from the image itself. The grub tools were added to the default tools trees as well.
  • The pacman keyring in tools trees is now only populated from the Arch Linux keyring (and not the Debian/Ubuntu ones anymore).
  • gpg is allowed to access /run/pscsd/pscsd.comm on the host if it exists to allow interaction with smartcards.

v20

4 months ago
  • The current working directory is not mounted unconditionally to /work/src anymore. Instead, the default value for BuildSources= now mounts the current working directory to /work/src. This means that the current working directory is no longer implicitly included when BuildSources= is explicitly configured.
  • Assigning the empty string to a setting that takes a list of values now overrides any configured default value as well.
  • The github action does not build and install systemd from source anymore. Instead, ToolsTree=default can be used to make sure a recent version of systemd is used to do the image build.
  • Added EnvironmentFiles= to read environment variables from environment files.
  • 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.
  • Added RuntimeScratch= to automatically mount a directory with extra scratch space into mkosi-spawned containers and virtual machines.
  • 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.
  • Added SELinuxRelabel= to specify whether to relabel selinux files or not.
  • Many fixes to tools trees were made and tools trees are now covered by CI. Some combinations aren't possible yet but we're actively working to make these possible.
  • mkosi qemu can now direct kernel boot s390x and powerpc images.
  • Added HostArchitecture= match to match against the host architecture.
  • We don't use the user's SSH public/private keypair anymore for mkosi ssh but instead use a separate key pair which can be generated by mkosi genkey. Users using mkosi ssh will have to run mkosi genkey once to generate the necessary files to keep mkosi ssh working.
  • We don't automatically set --offline=no anymore when we detect the Subvolumes= setting is 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. While this will generally not be noticeable, users with custom systemd-repart ESP partition definitions will need to add CopyFiles=/boot:/ along with the usual CopyFiles=/efi:/ to their ESP partition definitions. By installing UKIs/kernels/initrds to /boot, it becomes possible to use /boot to populate an XBOOTLDR partition which wasn't possible before. Note that this is also safe to do before v20 so CopyFiles=/boot:/ can unconditionally be added to any ESP partition definition files.
  • Added QemuFirmwareVariables= to allow specifying a custom OVMF variables file to use.
  • Added MinimumVersion= to allow specifying the minimum required mkosi version to build an image.
  • Added support for Arch Linux's debug repositories
  • Merged the mkosi-initrd project into mkosi itself. mkosi-initrd is now used to build the default initrd.
  • Implemented mkosi-initrd for all supported distributions.
  • Added ShimBootloader= to support installing shim to the ESP.
  • Added sysext, confext and portable output formats. These will produce signed disk images that can be used as sysexts, confexts and portable services respectively.
  • Added QemuVsockConnectionId= to configure how to allocate the vsock connection ID when QemUVsock= is enabled.
  • Added documentation on how to build sysexts with mkosi.
  • Global systemd user presets are now also configured.
  • Implemented WithDocs= for apt.
  • On supported package managers, locale data for other locales is now stripped if the local is explicitly configured using Locale=.
  • All rpm plugins are now disabled when building images.
  • Added KernelModulesIncludeHost= and KernelModulesInitrdIncludeHost= to only include modules loaded on the host system in the image/initrd respectively.
  • Implemented RemovePackages= for Arch Linux.
  • Added useradd and groupadd scripts to configure these binaries to operate on the image during builds instead on the host.
  • Added microcode support. If installed into the image, an early microcode initrd will automatically be built and prepended to the initrd.
  • A passwordless root account may now be created by specifying hashed:
  • The Autologin= feature was extended with support for arm64, s390x and powerpc architectures.
  • Added SecureBootAutoEnroll= to control automatic enrollment of secureboot keys separately from signing systemd-boot and generated UKIs.
  • ImageVersion= is no longer automatically appended to the output files, instead this is automatically appended to Output= if not specified and results in the %o specifier being equivalent to %i or %i_%v depending on if ImageVersion= is specified.

v19

5 months ago
  • Support for RHEL was added!
  • Added journalctl and coredumpctl verbs for running the respective tools on built directory or disk images.
  • Added a burn verb to write the output image to a block device.
  • Added a new esp output format, which is large similar to the existing uki output format but wraps it in a disk image with only an ESP.
  • Presets were renamed to Images. 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. The old names can still be used for backwards compatibility.
  • Added profiles to support building variants of the same image in one repository. Profiles can be defined in mkosi.profiles/ and one can be selected using the new Profile= setting.
  • mkosi will now parse mkosi.local.conf before any other config files if that exists.
  • Added a kernel-install plugin. This is only shipped in source tree and not included in the Python module.
  • Added a --json option to get the output of mkosi summary as JSON.
  • Added shorthand -a for --autologin.
  • Scripts with the .chroot extension are now executed in the image automatically.
  • Added rpm helper script to have rpm automatically operate on the image when running scripts.
  • Added mkosi-as-caller helper script that can be used in scripts to run commands as the user invoking mkosi.
  • mkosi-chroot will now start a shell if no arguments are specified.
  • Added WithRecommends= to configure whether to install recommended packages by default or not where this is supported. It is disabled by default.
  • Added ToolsTreeMirror= setting for configuring the mirror to use for the default tools tree.
  • WithDocs= is now enabled by default.
  • Added BuildSourcesEphemeral= to make source directories ephemeral when running scripts. This means any changes made to source directories while running scripts will be undone after the scripts have finished executing.
  • Added QemuDrives= to have mkosi create extra qemu drives and pass them to qemu when using the qemu verb.
  • Added BuildSources= match to match against configured build source targets.
  • PackageManagerTrees= was moved to the Distribution section.
  • We now automatically configure the qemu firmware, kernel cmdline and initrd based on what type of kernel is passed by the user via -kernel or QemuKernel=.
  • The mkosi repository itself now ships configuration to build basic bootable images that can be used to test mkosi.
  • Added support for enabling updates-testing repositories for Fedora.
  • GPG keys for CentOS, Fedora, Alma and Rocky are now looked up locally first before fetching them remotely.
  • Signatures are not required for local packages on Arch anymore.
  • Packages on opensuse are now always downloaded in advance before installation when using zypper.
  • The tar output is now reproducible.
  • We now make sure git can be executed from mkosi scripts without running into permission errors.
  • We don't create subdirectories beneath the configured cache directory anymore.
  • 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.
  • Added environment variable MKOSI_DNF to override which dnf to use for building images (dnf or dnf5).
  • The rootfs can now be modified when running build scripts (with all changes thrown away after the last build script has been executed).
  • mkosi now fails if configuration specified via the CLI does not apply to any image (because it is overridden).
  • Added a new doc on building rpms from source with mkosi (docs/building-rpms-from-source.md).
  • /etc/resolv.conf will now only be mounted for scripts when they are run with network access.

v18

7 months ago
  • $SCRIPT was renamed to $CHROOT_SCRIPT. $SCRIPT can still be used but is considered deprecated.
  • 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.
  • 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.
  • Added Include= or --include to include extra configuration files or directories.
  • Added support for specifiers to access the current value of certain settings during configuration file parsing.
  • mkosi will now exit with an error when no configuration was provided.
  • Multiple scripts of the same type are now supported.
  • 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.
  • We now use local GPG keys for rpm based distributions if the distribution-gpg-keys package is installed on the host.
  • Added RuntimeSize= to grow the image to a specific size before booting it when using mkosi boot or mkosi qemu.
  • 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.
  • Added an Architecture= match
  • Initrds specified with Initrds= are now used for grub menuentries as well.
  • ImageId= and ImageVersion= are now written to os-release as IMAGE_ID and IMAGE_VERSION if provided.
  • We pass command line arguments passed to the build verb to the build script again.
  • We added support for the "RHEL Universal Base Image" distribution.

v17.1

7 months ago
  • Fixed bug where --autologin was broken when used in combination with a tools tree when using a packaged version of mkosi.

v17

7 months ago
  • Added ToolsTreePackages= to add extra packages to the default 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
  • UKIs can now be booted using direct linux boot.
  • We don't try to make images UEFI bootable anymore on architectures that do not support UEFI
  • Fixed --help to show all options again
  • We now warn when settings are configured in the wrong section

v16

8 months ago
  • mkosi.version is now picked up from preset and dropin directories as well following the usual config precedence logic
  • Removed the "first assignment wins" logic from configuration parsing. Settings parsed later will now override earlier values
  • Removed the ! operator for lists. Instead, assign the empty string to the list to remove all previous values.
  • Added support for configuring custom default values for settings by prefixing their name in the configuration file with @.
  • Added QemuCdrom= to attach the image to the virtual machine as a CD-ROM instead of a block device.
  • Added SectorSize= to set the sector size of the disk images built by systemd-repart.
  • 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.
  • 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.
  • Added BiosBootloader= to configure whether grub for BIOS gets installed or not.
  • Added QemuFirmware= to select which qemu firmware to use (OVMF, Seabios or direct kernel boot).
  • Added QemuKernel= to specify the kernel that should be used with direct kernel boot.
  • /var/lib/dbus/machine-id is now removed if it was added by a package manager postinstall script.
  • The manifest is not generated by default anymore. Use ManifestFormat=json to make sure the manifest is generated.
  • Added SourceDateEpoch= to enable more reproducible image builds.
  • Added Seed= to set the seed passed to systemd-repart.
  • Updated the default Fedora release to Fedora 39.
  • 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.
  • 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.