Releases: systemd/mkosi
Releases · systemd/mkosi
mkosi v22
- 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, andQemuFirmware=uefi-secure-boot
was introduced
to boot with SecureBoot support. By default we will still boot with
SecureBoot support ifQemuFirmware=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.
IfSecureBoot=
is enabled andShimBootloader=
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.
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-initrd
config
so there's no need anymore to copy the fullmkosi-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 withToolsTree=default
- We now use
.zst
instead of.zstd
for compressed split artifacts
produced bysystemd-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=
, disableCleanPackageMetadata=
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 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
,grep
andfindutils
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=
andEncryptedVolume=
). bash
is 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 vmspawn
which boots the image withsystemd-vmspawn
.
Note thatsystemd-vmspawn
is experimental and its interface may
still change. As suchmkosi vmspawn
is also considered experimental.
Note thatsystemd-vmspawn
version256
or 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 version256
or newer. - We don't clean up package manager metadata anymore unless explicitly
requested withCleanPackageManagerMetadata=yes
when building
directory
andtar
images.
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
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
tosystemd-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.
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-xxx
binaries are now preferred over the genericqemu
andqemu-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.
mkosi v20
- The current working directory is not mounted unconditionally to
/work/src
anymore. 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=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 boots390x
andpowerpc
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 bymkosi genkey
. Users usingmkosi 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 asystemd-repart
partition
definition file. Instead, use the newRepartOffline=
option to
explicitly disable runningsystemd-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 usualCopyFiles=/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 beforev20
soCopyFiles=/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
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
andgroupadd
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 forarm64
,
s390x
andpowerpc
architectures. - Added
SecureBootAutoEnroll=
to control automatic enrollment of secureboot
keys separately from signingsystemd-boot
and 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%o
specifier being equivalent to%i
or%i_%v
depending
on ifImageVersion=
is specified.
v19
- Support for RHEL was added!
- Added
journalctl
andcoredumpctl
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 existinguki
output format but wraps it in a disk image with only an ESP. Presets
were renamed toImages
.mkosi.images/
is now used instead ofmkosi.presets/
, thePresets=
setting was renamed toImages=
and thePresets
section was merged into theConfig
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 newProfile=
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 ofmkosi 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 haverpm
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 theqemu
verb. - Added
BuildSources=
match to match against configured build source targets. PackageManagerTrees=
was moved to theDistribution
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
orQemuKernel=
. - 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
ordnf5
). - 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
$SCRIPT
was renamed to$CHROOT_SCRIPT
.$SCRIPT
can still be used
but is considered deprecated.- Added
RuntimeTrees=
setting to mount directories when booting images
viamkosi boot
,mkosi shell
ormkosi 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 useVirtioFS
viavirtiofsd
. 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
. WhenCONFIG_VIRTIOFS
andCONFIG_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 usingcustom
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 usingmkosi boot
ormkosi qemu
. - We now set
MKOSI_UID
andMKOSI_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=
andImageVersion=
are now written to os-release as
IMAGE_ID
andIMAGE_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
- Fixed bug where
--autologin
was 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
--help
to show all options again - We now warn when settings are configured in the wrong section
v16
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. Addeduki
option to install just the UKI without
systemd-boot andgrub
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 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
uki
output 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.