Releases: systemd/mkosi
mkosi v21
- We now handle unmerged-usr systems correctly
- Builtin configs (
mkosi-initrd,mkosi-tools) can now be included
usingInclude=(e.g.Include=mkosi-initrd) - The kernel-install plugin now uses the builtin
mkosi-initrdconfig
so there's no need anymore to copy the fullmkosi-initrdconfig into
/usr/lib/mkosi-initrd. - We don't require a build anymore for the
journalctland
coredumpctlverbs. mkosi sshworks again when used withToolsTree=default- We now use
.zstinstead of.zstdfor compressed split artifacts
produced bysystemd-repart. systemd-repartuses 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/varso
that incremental images and extension images can reuse the same
snapshot. When building an image intended to be used with
BaseTrees=, disableCleanPackageMetadata=to make sure the
repository metadata in/varis 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 ofCacheOnly=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,grepandfindutilsto
the default tools tree. - Added
mkosi-install,mkosi-upgrade,mkosi-removeand
mkosi-reinstallscripts which allow writing scripts that are
independent of the package manager being used to build the image. - We now expand specifiers in
Matchsection 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/fstaband/etc/crypttabfor the image if any
partition definitions contain the corresponding settings
(MountPoint=andEncryptedVolume=). bashis now started in the debug shell instead ofsh.- 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 vmspawnwhich boots the image withsystemd-vmspawn.
Note thatsystemd-vmspawnis experimental and its interface may
still change. As suchmkosi vmspawnis also considered experimental.
Note thatsystemd-vmspawnversion256or newer is required. - Added
SyncScripts=which can be used to update various build sources
before starting the image build. - The
DISTRIBUTION=andRELEASE=environment variables are now set
when running scripts. - Added
ToolsTreeRepositories=andToolsTreePackageManagerTrees=. - Added
RuntimeNetwork=to configure the networking used when booting
the image. - Added
SecureBootKeySource=andVerityKeySource=to support signing
images with OpenSSL engines. Note that these settings require various
systemd tools to be version256or newer. - We don't clean up package manager metadata anymore unless explicitly
requested withCleanPackageManagerMetadata=yeswhen building
directoryandtarimages.
mkosi v20.2
- 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
KernelModulesIncludeHostwas including unnecessary
modules - Fixed
--mirrorspecification 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/mtabcompatibility symlink in mkosi's
sandbox. - We now always hash the root password ourselves instead of leaving it
tosystemd-firstboot. /srvand/mntare 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.
mkosi v20.1
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-xxxbinaries are now preferred over the genericqemu
andqemu-kvmbinaries.- 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). gpgis allowed to access/run/pscsd/pscsd.common the host if it
exists to allow interaction with smartcards.
mkosi v20
- The current working directory is not mounted unconditionally to
/work/srcanymore. Instead, the default value forBuildSources=
now mounts the current working directory to/work/src. This means
that the current working directory is no longer implicitly included
whenBuildSources=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=defaultcan 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/tmpand 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 qemucan now direct kernel boots390xandpowerpcimages.- Added
HostArchitecture=match to match against the host
architecture. - We don't use the user's SSH public/private keypair anymore for
mkosi sshbut instead use a separate key pair which can be
generated bymkosi genkey. Users usingmkosi sshwill have to run
mkosi genkeyonce to generate the necessary files to keep
mkosi sshworking. - We don't automatically set
--offline=noanymore when we detect the
Subvolumes=setting is used in asystemd-repartpartition
definition file. Instead, use the newRepartOffline=option to
explicitly disable runningsystemd-repartin 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 usualCopyFiles=/efi:/to their
ESP partition definitions. By installing UKIs/kernels/initrds to
/boot, it becomes possible to use/bootto populate an XBOOTLDR
partition which wasn't possible before. Note that this is also safe to
do beforev20soCopyFiles=/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 whenQemUVsock=is enabled. - Added documentation on how to build sysexts with mkosi.
- Global systemd user presets are now also configured.
- Implemented
WithDocs=forapt. - On supported package managers, locale data for other locales is now
stripped if the local is explicitly configured usingLocale=. - All
rpmplugins 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
useraddandgroupaddscripts 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 forarm64,
s390xandpowerpcarchitectures. - Added
SecureBootAutoEnroll=to control automatic enrollment of secureboot
keys separately from signingsystemd-bootand generated UKIs. ImageVersion=is no longer automatically appended to the output files,
instead this is automatically appended toOutput=if not specified and
results in the%ospecifier being equivalent to%ior%i_%vdepending
on ifImageVersion=is specified.
v19
- Support for RHEL was added!
- Added
journalctlandcoredumpctlverbs for running the respective tools on built directory or disk images. - Added a
burnverb to write the output image to a block device. - Added a new
espoutput format, which is large similar to the existingukioutput format but wraps it in a disk image with only an ESP. Presetswere renamed toImages.mkosi.images/is now used instead ofmkosi.presets/, thePresets=setting was renamed toImages=and thePresetssection was merged into theConfigsection. 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 newProfile=setting. - mkosi will now parse
mkosi.local.confbefore 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
--jsonoption to get the output ofmkosi summaryas JSON. - Added shorthand
-afor--autologin. - Scripts with the
.chrootextension are now executed in the image automatically. - Added
rpmhelper script to haverpmautomatically operate on the image when running scripts. - Added
mkosi-as-callerhelper script that can be used in scripts to run commands as the user invoking mkosi. mkosi-chrootwill 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 theqemuverb. - Added
BuildSources=match to match against configured build source targets. PackageManagerTrees=was moved to theDistributionsection.- We now automatically configure the qemu firmware, kernel cmdline and initrd based on what type of kernel is passed by the user via
-kernelorQemuKernel=. - The mkosi repository itself now ships configuration to build basic bootable images that can be used to test mkosi.
- Added support for enabling
updates-testingrepositories 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
gitcan 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/.cacheor/var/tmpdepending on the situation. - Added environment variable
MKOSI_DNFto override which dnf to use for building images (dnfordnf5). - 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.confwill now only be mounted for scripts when they are run with network access.
v18
$SCRIPTwas renamed to$CHROOT_SCRIPT.$SCRIPTcan still be used
but is considered deprecated.- Added
RuntimeTrees=setting to mount directories when booting images
viamkosi boot,mkosi shellormkosi 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 useVirtioFSviavirtiofsd. Note that this
requires systemd v254 or newer to be installed in the image. - Added support for booting directory images with
mkosi qemuvia
VirtioFS. WhenCONFIG_VIRTIOFSandCONFIG_VIRTIO_PCIare builtin
modules, no initramfs is required to make this work. - Added
Include=or--includeto include extra configuration files
or directories. - Added support for specifiers to access the current value of certain
settings during configuration file parsing. mkosiwill 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 usingcustomas 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-keyspackage is installed on the host. - Added
RuntimeSize=to grow the image to a specific size before
booting it when usingmkosi bootormkosi qemu. - We now set
MKOSI_UIDandMKOSI_GIDwhen 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=andImageVersion=are now written to os-release as
IMAGE_IDandIMAGE_VERSIONif provided.- We pass command line arguments passed to the
buildverb to the build
script again. - We added support for the "RHEL Universal Base Image" distribution.
v17.1
- Fixed bug where
--autologinwas broken when used in combination with
a tools tree when using a packaged version of mkosi.
v17
- 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
--helpto show all options again - We now warn when settings are configured in the wrong section
v16
mkosi.versionis 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. Addedukioption to install just the UKI without
systemd-boot andgrubto 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-idis now removed if it was added by a package
manager postinstall script.- The manifest is not generated by default anymore. Use
ManifestFormat=jsonto 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 todefault, 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=andToolsTreeRelease=or are determined
automatically based on the image being built. - Added
ukioutput format. This is similar tocpio, except the cpio
is packaged up as a UKI with a kernel image and stub picked up from
the rootfs.
v15.1
-
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=/:/usrin 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. -
Support for --qemu-boot was dropped
-
Support for --use-host-repositories was dropped, use --repository-directory instead
-
RepositoryDirectorywas removed, usePackageManagerTrees=orSkeletonTrees=instead. -
--repositoriesis 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. -
The
_epeldistributions were removed. Use--repositories=epelinstead to enable
the EPEL repository. -
Removed
-streamfrom CentOS release specifiers. Instead of specifying8-stream,
you know just specify8. -
Removed default kernel command line arguments
rhgb,selinux=0andaudit=0. -
Dropped --all and --all-directory as this functionality is better implemented by
using a build system. -
mkosi now builds images without needing root privileges.
-
Removed
--no-chown,--idmapand--nspawn-keep-unitoptions as they were made obsolete by moving to
rootless builds. -
Removed
--source-file-transfer,--source-file-transfer-final,--source-resolve-symlinksand
--source-resolve-symlinks-finalin favor of always mounting the source directory into the build image.
--source-file-transfer-finalmight be reimplemented in the future using virtiofsd. -
Dropped
--include-diroption. Usage can be replaced by using--incrementaland reading includes from
the cached build image tree. -
Removed
--machine-idin favor of shipping images without a machine ID at all. -
Removed
--skip-final-phaseas we only have a single phase now. -
The post install script is only called for the final image now and not for the build image anymore. Use the
prepare script instead. -
--ssh-key,--ssh-agent,--ssh-portand--ssh-timeoutoptions were dropped as the SSH support was
reimplemented using VSock.mkosi sshcan only be used with images booted withmkosi qemu. Use
machinectlto access images booted withmkosi boot. Use --extra-tree or --credential with the
.ssh.authorized_keys.rootcredentials as alternatives for provisioning the public key inside the image. -
Only configuration files matching
*.confare parsed in dropin directories now. -
Removed
--qemu-headless, we now start qemu in the terminal by default and configure the serial console at
runtime. Use the new--qemu-guioption to start qemu in its graphical interface. -
Removed
--netdev. Can be replaced by manually installing systemd-networkd, putting a network file in the
image and enabling systemd-networkd. -
If
mkosi.extra/ormkosi.skeleton/exist, they are now always used instead of only when no explicit
extra/skeleton trees are defined. -
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. In practice, this means systemd and other
basic tools have to be installed explicitly from now on. -
Removed
--base-packagesas it's not needed anymore since we don't install any packages by default anymore
aside from the base filesystem layout package. -
Removed
--qcow2option in favor of supporting only raw disk images as the disk image output format. -
Removed
--bmapoption as it can be trivially added manually by utilizing a finalize script. -
The
nevervalue for--with-networkwas spun of into its own custom option--cache-only. -
--bootablenow defaults toauto. When set toauto, mkosi will generate a bootable image only if all
the necessary packages are installed. Documentation was 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.
-
Removed the dependency on
debootstrapto build Ubuntu or Debian images. -
Apt now uses the keyring from the host instead of the keyring from the image. This means
debian-archive-keyringorubuntu-archive-keyringare now required to be installed to build Debian or
Ubuntu images respectively. -
--base-imageis split into--base-treeand--overlay. -
Removed
--cache-initrd, instead, use a prebuilt initrd withInitrds=to avoid rebuilding the initrd all
the time. -
Disk images are now resized to 8G when booted to give some disk space to play around with in the booted
image. -
Removed
--install-directory=option. This was originally added for caching the installation results, but
this doesn't work properly as it might result in leftover files in the install directory from a previous
installation, so we have to empty the directory before reusing it, invalidating the caching, so the option
was removed. -
Build scripts are now executed on the host. See the
SCRIPTSsection
in the manual for more information. 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 to ensure a script 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
-
Removed
--tar-strip-selinux-context=option. 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. -
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. -
A verb
documentationhas been added. Calling mkosi with this verb will show
the documentation. This is useful when running mkosi during development to
always have the documentation in the correct version available. By default it
will try several ways to output the documentation, but a specific option can
be chosen with the--doc-formatoption. Distro packagers are encouraged to
add a filemkosi.1into themkosi/resourcesdirectory of the Python
package, if it is missing, as well es install it in the appropriate search
path for man pages. The man page can be generated from the markdown file
mkosi/resources/mkosi.mde.g viapandoc -t man -s -o mkosi.1 mkosi.md. -
The man page can be generated from the markdown file via
tools/make-man-page.sh. -
Fixed issue where not all packages and data files where included in
the generated python package. -
mkosi doesn't try to unshare the network namespace anymore when it
doesn't haveCAP_NET_ADMIN. -
Fixed issue when the workspace was located in
/tmp. -
Don't try to run
timedatectlorssh-addwhen they're not installed.