Releases: systemd/mkosi
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=/:/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. -
Support for --qemu-boot was dropped
-
Support for --use-host-repositories was dropped, use --repository-directory instead
-
RepositoryDirectory
was removed, usePackageManagerTrees=
orSkeletonTrees=
instead. -
--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. -
The
_epel
distributions were removed. Use--repositories=epel
instead to enable
the EPEL repository. -
Removed
-stream
from CentOS release specifiers. Instead of specifying8-stream
,
you know just specify8
. -
Removed default kernel command line arguments
rhgb
,selinux=0
andaudit=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
,--idmap
and--nspawn-keep-unit
options as they were made obsolete by moving to
rootless builds. -
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. -
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. -
Removed
--skip-final-phase
as 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-port
and--ssh-timeout
options were dropped as the SSH support was
reimplemented using VSock.mkosi ssh
can only be used with images booted withmkosi qemu
. Use
machinectl
to access images booted withmkosi boot
. Use --extra-tree or --credential with the
.ssh.authorized_keys.root
credentials as alternatives for provisioning the public key inside the image. -
Only configuration files matching
*.conf
are 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-gui
option 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-packages
as it's not needed anymore since we don't install any packages by default anymore
aside from the base filesystem layout package. -
Removed
--qcow2
option in favor of supporting only raw disk images as the disk image output format. -
Removed
--bmap
option as it can be trivially added manually by utilizing a finalize script. -
The
never
value for--with-network
was spun of into its own custom option--cache-only
. -
--bootable
now 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
debootstrap
to build Ubuntu or Debian images. -
Apt now uses the keyring from the host instead of the keyring from the image. This means
debian-archive-keyring
orubuntu-archive-keyring
are now required to be installed to build Debian or
Ubuntu images respectively. -
--base-image
is split into--base-tree
and--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
SCRIPTS
section
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
documentation
has 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-format
option. Distro packagers are encouraged to
add a filemkosi.1
into themkosi/resources
directory 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.md
e.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
timedatectl
orssh-add
when they're not installed.
v14
-
Support for Clear Linux was dropped. See #1037 for more information.
-
Support for Photon was dropped. See #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.
-
mkosi now creates
distro~release
subdirectories inside the build, cache and output directories for eachdistro~release
combination that is built. This allows building for multiple distros without throwing away the results of a previous distro build every time. -
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.
-
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 isSigLevel = Required DatabaseOptional
. If this results in keyring errors, you need to update the keyring by runningpacman-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.
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 whichgrub
(or any other bootloader) can be installed with the help of mkosi's script support (depending on your needs most likelymkosi.postinst
ormkosi.finalize
). This method can also be used for other EFI bootloaders that mkosi intentionally does not support. -
mkosi now unconditionally copies the kernel, initrd and kernel cmdline from the image that were previously only copied out for Qemu boot.
-
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 forusr
variants). -
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 toSUDO_UID
orPKEXEC_UID
if defined, unless--no-chown
is used. -
If
systemd-nspawn
v252 or newer is used, bind-mounted directories withsystemd-nspawn
will use the newrootidmap
option so files and directories created from within the container will be owned by the actual directory owner on the host.
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. - 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 thevirtio_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
to configure other interfaces, you'll have to re-create it with the correct match and a lower initial number in the filename to make suresystemd-networkd
will keep configuring your interface, e.g. via themkosi.skeleton
ormkosi.extra
trees or amkosi.postinst
script. - The
kernel-install
script for building unified kernel images has been removed. From v13 onwards, on systems usingkernel-install
,mkosi
won't automatically build new unified kernel images when a kernel is updated or installed. To keep the old behavior, you can install thekernel-install
script manually via a skeleton tree; a copy can be found here. - New
QemuKvm
option configures whether to use KVM when runningmkosi qemu
. mkosi
will not default to the same OS release as the host system anymore 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.mkosi
will now use thepacman
keyring from the host when building Arch images. This means that users will, on top of installingarchlinux-keyring
, also have to runpacman-key --init
andpacman-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 afterarchlinux-keyring
updates by runningpacman-key --populate archlinux
andpacman-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 toqemu
bymkosi qemu
to directly boot into the kernel image without a bootloader. This can be used to boot for example s390x images inqemu
. - The initrd will now always be rebuilt after the extra trees and build artifacts have been installed into the image.
- 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. - 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 forpacman
and
dnf
-based distros. - Option
--skeleton-tree
is now supported on Debian-based distros.
v12
mkosi 12
v11
mkosi 11
v10
v9
mkosi 9
v8
mkosi 8
v7
mkosi 7
v6
mkosi 6