Debian Codegraph @

upstream/debian-unstable/man7/mkosi.news.7

raw
1 .\" Automatically generated by Pandoc 3.9.0.2
2 .\"
3 .TH "mkosi.news" "7" "" ""
4 .SH mkosi Changelog
5 .SS v26
6 .IP \(bu 2
7 Extra options to commands invoked by mkosi (e.g.\ when using \f[B]mkosi
8 boot\f[R] or \f[B]mkosi shell\f[R]) should now be delimited from regular
9 options using \f[B]\-\-\f[R].
10 Options passed after the verb without using the \f[B]\-\-\f[R] delimiter
11 are now interpreted as regular mkosi options.
12 .IP \(bu 2
13 Boolean options specified on the command line now always expect a
14 boolean argument.
15 For example, \f[B]\-\-repository\-key\-check\f[R] needs to become
16 \f[B]\-\-repository\-key\-check=yes\f[R].
17 The reason for this change is to remove ambiguity when parsing
18 e.g.\ \f[B]\-\-repository\-key\-check build\f[R] where \f[B]build\f[R]
19 would be interpreted as the argument for
20 \f[B]\-\-repository\-key\-check\f[R] whereas now it\(cqll be properly
21 interpreted as the verb.
22 .IP \(bu 2
23 Teach \f[B]\-\-verity\f[R] a new \f[B]hash\f[R] value, which skips the
24 verity signature partition for extension / portable images.
25 To align the possible values, \f[B]yes\f[R] is renamed to
26 \f[B]signed\f[R].
27 .IP \(bu 2
28 Teach \f[B]\-\-verity\f[R] a new \f[B]defer\f[R] value, which defers
29 creation of the verity signature partition for disk, extension and
30 portable images (but still allocates space for it).
31 This is useful to implement offline signing of the verity roothash.
32 .IP \(bu 2
33 A new way to specify modules included in the initrd has been added.
34 The new default is that modules need to be specified to be included.
35 Previous separate Include and Exclude options that take regexps are now
36 deprecated and are replaced by a single option that takes a list of
37 positive and negative globs.
38 The new options are KernelModules= and KernelInitrdModules=.
39 .IP \(bu 2
40 A new way to specify firmware files included in the initrd has been
41 added.
42 Previous separate Include and Exclude options that take regexps are now
43 deprecated and are replaced by a single option that takes a list of
44 positive and negative globs.
45 The new option is FirmwareFiles=.
46 .IP \(bu 2
47 The \f[B]RuntimeScratch=\f[R] option has been dropped.
48 Use \f[B]RuntimeSize=\f[R] instead to grow the image before booting it.
49 .IP \(bu 2
50 The \f[B]CDROM=\f[R] option has been dropped.
51 .IP \(bu 2
52 Unknown settings now generate a warning message instead of failing the
53 image build.
54 This allows configs to work across a wider range of mkosi versions while
55 still taking advantage of newer settings.
56 MinimumVersion can still be used to enforce a minimum version of mkosi
57 that knows all required settings.
58 .SS v25
59 .IP \(bu 2
60 Instead of using bubblewrap, sandboxing is now done with a new tool
61 \f[B]mkosi\-sandbox\f[R].
62 This tool has a public API and can be used independently of mkosi.
63 .IP \(bu 2
64 Image builds are now done in a user namespace with a single user when
65 running unprivileged instead of using newuidmap/newgidmap.
66 When running unprivileged, all files and directories in the image will
67 be owned by the invoking user (and by root inside any produced
68 archives).
69 Any attempt to chown files to other users in scripts will fail unless
70 the new environment variable \f[B]$MKOSI_CHROOT_SUPPRESS_CHOWN\f[R] is
71 set to a true value.
72 .IP \(bu 2
73 \f[B]mkosi\f[R] does not drop privileges anymore to the invoking user
74 when running as root for various steps.
75 .IP \(bu 2
76 A new \f[B]cat\-config\f[R] verb will show all configuration files that
77 were included for each configured image.
78 .IP \(bu 2
79 Added support for Azure Linux
80 .IP \(bu 2
81 Added support for Kali Linux
82 .IP \(bu 2
83 If \f[B]mkosi.version\f[R] is executable, we now execute it and read the
84 version from stdout.
85 .IP \(bu 2
86 Added \f[B]\-\-wipe\-build\-dir\f[R] to wipe the build directory before
87 rebuilding the image.
88 .IP \(bu 2
89 Introduced \f[B]RepositoryKeyFetch=\f[R] to control whether to fetch
90 distribution GPG keys remotely.
91 This setting is \f[B]disabled\f[R] by default for security reasons
92 except when building rpm based or Arch Linux images on Ubuntu.
93 .IP \(bu 2
94 We now handle \f[B]SIGHUP\f[R] gracefully
95 .IP \(bu 2
96 Universal settings that take a collection of values cannot be appended
97 to anymore in subimages.
98 Usage of package manager trees in subimages will have to be moved to the
99 top level image.
100 Similarly, repositories will have to be enabled in the top level image.
101 .IP \(bu 2
102 Repository metadata is not copied into images anymore.
103 .IP \(bu 2
104 Repository metadata from base trees is not used anymore.
105 .IP \(bu 2
106 Package manager trees are now named sandbox trees.
107 .IP \(bu 2
108 Package manager trees (sandbox trees) do not use the skeleton trees as
109 their default anymore if unset.
110 .IP \(bu 2
111 Note to packagers: The manual pages have been moved to resources/man and
112 now include man pages for mkosi\-initrd and mkosi\-sandbox as well.
113 .IP \(bu 2
114 \f[B]InitrdInclude=\f[R] was removed.
115 If you\(cqre using \f[B]InitrdInclude=\f[R], please build your initrd
116 via a subimage in \f[B]mkosi.images\f[R] containing
117 \f[B]Include=mkosi\-initrd\f[R] and any customizations you wish to add
118 and use the \f[B]Initrds=\f[R] setting to use it as the initrd for the
119 main image instead of the default initrd.
120 .IP \(bu 2
121 Added \f[B]History=\f[R] to have mkosi save the config used to build the
122 image and reuse it when verbs such as \f[B]qemu\f[R], \f[B]boot\f[R],
123 \&...
124 are invoked without \f[B]\-f\f[R].
125 .IP \(bu 2
126 Introduced new \f[B][Build]\f[R] section and moved various settings to
127 it.
128 .IP \(bu 2
129 Moved \f[B]Include=\f[R] to \f[B][Include]\f[R] section
130 .IP \(bu 2
131 Added \f[B]sysupdate\f[R] verb as a wrapper around
132 \f[B]systemd\-sysupdate\f[R] which invokes it with definitions from
133 \f[B]mkosi.sysupdate\f[R].
134 .IP \(bu 2
135 Added \f[B]RuntimeHome=\f[R] to mount the current home directory to
136 \f[B]/root\f[R] when running a command that boots the image
137 .IP \(bu 2
138 More directories aside from \f[B]/etc\f[R] and \f[B]/usr\f[R] are now
139 picked up from sandbox trees (formerly known as package manager trees).
140 .IP \(bu 2
141 Profile configuration from \f[B]mkosi.profiles\f[R] is now parsed after
142 \f[B]mkosi.conf.d\f[R] instead of before it.
143 To set defaults for use in \f[B]mkosi.conf.d\f[R] based on the
144 configured profile, use an early dropin in \f[B]mkosi.conf.d\f[R] that
145 matches on the configured profile instead.
146 .IP \(bu 2
147 \f[B]Profile=\f[R] is renamed to \f[B]Profiles=\f[R] and takes a comma
148 separated list of profiles now.
149 Scripts now receive \f[B]$PROFILES\f[R] with a space\-separated list of
150 profiles instead of \f[B]$PROFILE\f[R].
151 The \f[B]%p\f[R] specifier for profiles is removed.
152 .IP \(bu 2
153 Multiple sync, prepare, build, postinst, finalize, postoutput and clean
154 scripts are now picked up from \f[B]mkosi.$SCRIPT.d\f[R].
155 .IP \(bu 2
156 \f[B]run0\f[R] is now automatically used to escalate privileges for
157 commands that need it, like the \f[B]burn\f[R] verb.
158 .IP \(bu 2
159 \f[B]/usr/share/keyrings\f[R] and
160 \f[B]/usr/share/distribution\-gpg\-keys\f[R] are no longer automatically
161 picked up from the tools tree when \f[B]ToolsTreeCertificates=\f[R] is
162 set, since they aren\(cqt certificates, use a sandbox tree instead.
163 This allows one to override \f[B]SignedBy=\f[R] keys for APT
164 repositories.
165 .IP \(bu 2
166 The \f[B]agetty.autologin\f[R] and \f[B]login.noauth\f[R] credentials
167 are no longer set unconditionally.
168 .IP \(bu 2
169 Access to the output directory in build scripts was removed.
170 To put artifacts from the build directory into the output directory,
171 copy them from the build directory to the output directory in a
172 post\-installation script which does have access to the build directory
173 and the output directory.
174 .IP \(bu 2
175 \f[B]BuildDirectory=\f[R] is no longer available in
176 \f[B]PrepareScripts=\f[R].
177 If you need to acquire some files for the build process place them
178 somewhere sensible within \f[B]$BUILDROOT\f[R] so that they can be
179 cached when building incrementally.
180 .IP \(bu 2
181 When using a tools tree and a relaxed sandbox is used to run a command
182 (qemu, nspawn, \&...), we now keep all entries from \f[B]$PATH\f[R]
183 outside of \f[B]/usr\f[R] intact.
184 Note that this may cause issues if a \f[B]$PATH\f[R] entry contains
185 binaries linked against libraries in \f[B]/usr\f[R] from the host.
186 .IP \(bu 2
187 Introduced a new specifier \f[B]%I\f[R] which resolves to the name of
188 the current subimage when used in a config under
189 \f[B]mkosi.images/\f[R].
190 This differs to \f[B]%o\f[R] as it is always the name of the config file
191 without extension (or the name of the directory).
192 .IP \(bu 2
193 If \f[B]/dev/fuse\f[R] is found in the host context, it is made
194 available in the sandbox context too.
195 .IP \(bu 2
196 Added a \f[B]sandbox\f[R] verb to run a command within a relaxed mkosi
197 sandbox (the same sandbox that \f[B]mkosi vm\f[R], \f[B]mkosi boot\f[R],
198 \&...
199 run in).
200 .IP \(bu 2
201 OpenSSL providers are now supported as key sources for the various key
202 settings if a recent enough systemd version (257 or newer) is used.
203 .IP \(bu 2
204 Added support for loading X.509 certificates from OpenSSL providers if a
205 recent enough systemd version (257 or newer) is used.
206 .IP \(bu 2
207 Added \f[B]ToolsTreePackageDirectories=\f[R]
208 .IP \(bu 2
209 Added \f[B]\-\-kernel\-image=\f[R] to \f[B]mkosi\-initrd\f[R] to specify
210 the kernel image to use when building a UKI.
211 .IP \(bu 2
212 Setting a collection based setting to the empty string via the CLI and
213 then appending to the same setting will now override the settings coming
214 from configuration files, whereas previously the CLI values would be
215 appended to the values from configuration files.
216 .IP \(bu 2
217 The \f[B]mkosi\-initrd\f[R] default config now includes various extra
218 kernel modules by default.
219 .IP \(bu 2
220 The \f[B]coredumpctl\f[R] and \f[B]journalctl\f[R] verbs will now always
221 operate on the image, even if \f[B]ForwardJournal=\f[R] is configured.
222 .IP \(bu 2
223 Bumped default Fedora release to \f[B]41\f[R].
224 .IP \(bu 2
225 Added \f[B]addon\f[R] output format to build UKI addons.
226 .IP \(bu 2
227 Renamed \f[B][Host]\f[R] section to \f[B][Runtime]\f[R] section.
228 .IP \(bu 2
229 Renamed various settings from \f[B][Host]\f[R].
230 .IP \(bu 2
231 Binaries coming from \f[B]ExtraSearchPaths=\f[R] are now executed with
232 the tools tree mounted if one is configured (unlike before where the
233 tools tree was not mounted).
234 This means that any binaries coming from \f[B]ExtraSearchPaths=\f[R]
235 have to be linked against libraries from the tools tree (or have to be
236 statically linked).
237 Alternatively, the tools tree distribution and release have to match the
238 host.
239 .IP \(bu 2
240 Binaries from \f[B]ExtraSearchPaths=\f[R] are not used anymore when
241 building the default tools tree.
242 .IP \(bu 2
243 Dropped support for \f[B]pesign\f[R] as a secure boot signing tool.
244 .IP \(bu 2
245 Added support for \f[B]systemd\-sbsign\f[R] as a secure boot signing
246 tool.
247 .IP \(bu 2
248 Added \f[B]\-\-register=\f[R] to control whether to register containers
249 and VMs with systemd\-machined or not.
250 .IP \(bu 2
251 \f[B]mkosi.profiles\f[R] is now parsed in subimages as well.
252 .IP \(bu 2
253 \f[B]mkosi\-initrd\f[R] now uses \f[B]dnf5\f[R] on systems where it is
254 the default.
255 .IP \(bu 2
256 Added various packages to the default tools tree.
257 .IP \(bu 2
258 Dropped support for Ubuntu Focal.
259 .IP \(bu 2
260 Added \f[B]Devicetree=\f[R] setting for configuring bootloader device
261 trees
262 .IP \(bu 2
263 Added systemd\-machined registration using varlink for \f[B]mkosi
264 qemu\f[R] vms, which includes the vsock CID so that \f[B]ssh
265 vsock/<cid>\f[R] or \f[B]ssh machine/<name>\f[R] will work on systems
266 running \f[B]systemd\-machined\f[R] 257 or newer.
267 .IP \(bu 2
268 Bumped CentOS Stream default release to 10.
269 .IP \(bu 2
270 mkosi now manages the pacman keyring itself so
271 \f[B]/etc/pacman.d/gnupg\f[R] from the host is not used anymore and
272 mkosi will run \f[B]pacman\-key \-\-init\f[R] and \f[B]pacman\-key
273 \-\-populate\f[R] itself.
274 .IP \(bu 2
275 Added \f[B]ToolsTreeRelease=\f[R] match
276 .IP \(bu 2
277 mkosi now enforces that images built with \f[B]Overlay=yes\f[R] only add
278 files on top of the base tree(s) and don\(cqt overwrite any existing
279 files or directories.
280 .IP \(bu 2
281 Added a \f[B]mkosi\-addon\f[R] tool and accompanying kernel\-install
282 plugin that allows building PE addons to extend a vendor provided
283 unified kernel image.
284 .IP \(bu 2
285 Added \f[B]systemd\-boot\-signed\f[R], \f[B]uki\-signed\f[R] and
286 \f[B]grub\-signed\f[R] variants for the \f[B]Bootloader=\f[R] option
287 which instruct mkosi to only install pre\-signed EFI binaries.
288 .IP \(bu 2
289 \f[B]mkosi.profiles\f[R] is now parsed in configuration included with
290 \f[B]Include=\f[R].
291 .IP \(bu 2
292 Any initrds configured with \f[B]Initrds=\f[R] are now used as fallback
293 when booting with qemu direct kernel boot (\f[B]\-\-firmware=linux\f[R])
294 if no split initrd was produced by the image build.
295 .IP \(bu 2
296 mkosi now makes a greater effort to ensure the crypto\-policies are
297 configured to allow GPG keys from older distributions.
298 .IP \(bu 2
299 We don\(cqt pick up pre\-signed bootloader binaries anymore when
300 \f[B]ShimBootloader=signed\f[R] is configured.
301 To force usage of pre\-signed EFI binaries, use the new
302 \f[B]systemd\-boot\-signed\f[R], \f[B]uki\-signed\f[R] and
303 \f[B]grub\-signed\f[R] variants for the \f[B]Bootloader=\f[R] option.
304 .IP \(bu 2
305 Added a new constant \f[B]microsoft\-mok\f[R] for the
306 \f[B]FirmwareVariables=\f[R] option.
307 If specified, a firmware variables file with the Microsoft keys enrolled
308 will be extended to include a \f[B]MokList\f[R] entry that trusts the
309 certificate configured with \f[B]SecureBootCertificate=\f[R] and passed
310 to \f[B]qemu\f[R].
311 .IP \(bu 2
312 We now use \f[B]mkosi.pkgcache\f[R] as the package cache directory if
313 the directory exists.
314 .IP \(bu 2
315 \f[B]BuildSourcesEphemeral=\f[R] learned a new variant
316 \f[B]buildcache\f[R] in which case the overlay will be cached in the
317 build directory configured with \f[B]BuildDirectory=\f[R].
318 .SS v24
319 .IP \(bu 2
320 The default kernel command line of \f[B]console=ttyS0\f[R] (or
321 equivalent for other architectures) has been removed.
322 The required \f[B]console=\f[R] argument to have the kernel output to
323 the serial console has to be added manually from \f[B]v24\f[R] onwards.
324 .IP \(bu 2
325 Support for installing local packages located in directories in
326 \f[B]BuildSources=\f[R] was dropped.
327 Instead, the packages can be made available for installation via
328 \f[B]PackageManagerTrees=\f[R].
329 .IP \(bu 2
330 Configuration parsing was reworked to remove the need for the
331 \f[B]\(at\f[R] specifier and to streamline building multiple images with
332 \f[B]mkosi.images/\f[R].
333 If you were building multiple images with \f[B]mkosi.images/\f[R],
334 you\(cqll need to adapt your configuration to the rework.
335 Read the \f[B]Building multiple images\f[R] section in the documentation
336 for more information.
337 .IP \(bu 2
338 mkosi has gained the option to generate completion scripts for bash,
339 fish and zsh.
340 Packagers should generate the scripts during packaging and ship them in
341 the appropriate places.
342 .IP \(bu 2
343 Added support for CentOS Stream 10.
344 .IP \(bu 2
345 mkosi now installs a separate \f[B]mkosi\-initrd\f[R] script that can be
346 used to build initramfs images intended for use on the local system.
347 .IP \(bu 2
348 We do not automatically append \f[B]centos\-stream\f[R] or
349 \f[B]fedora\f[R] anymore to CentOS (and derivatives) and Fedora mirrors
350 specified with \f[B]Mirror=\f[R] as not all mirrors store the repository
351 metadata under these subdirectories.
352 Users are now required to add these subdirectories themselves in
353 \f[B]Mirror=\f[R].
354 If the EPEL repositories are enabled for CentOS Stream (and derivatives)
355 and \f[B]Mirror=\f[R] is used, we look for the EPEL repositories in
356 \f[B]../fedora\f[R] relative to the mirror specified in
357 \f[B]Mirror=\f[R].
358 .IP \(bu 2
359 We now support compressed tar archives wherever we already accept tar
360 archives as input.
361 .IP \(bu 2
362 We now always rerun the build if \f[B]Format=none\f[R] and don\(cqt
363 remove previous outputs in that case (unless \f[B]\-\-force\f[R] is
364 specified).
365 This allows using \f[B]mkosi \-t none\f[R] to rerun the build scripts
366 without removing the previous image.
367 This can then be combined with \f[B]RuntimeBuildSources=yes\f[R] to make
368 the build script outputs available in a booted container or virtual
369 machine so they can be installed without having to rebuild the image.
370 .IP \(bu 2
371 We now use \f[B]virtconsole\f[R] to provide the serial console when
372 booting with \f[B]qemu\f[R].
373 .IP \(bu 2
374 \f[B]root=PARTUUID\f[R] and \f[B]mount.usr=PARTUUID\f[R] on the kernel
375 command line are now automatically extended with the actual PARTUUID of
376 the corresponding partition.
377 .IP \(bu 2
378 All available OpenSUSE repositories are now supported and can be enabled
379 with \f[B]Repositories=\f[R].
380 .IP \(bu 2
381 Building OpenSUSE \f[B]aarch64\f[R] images is now supported
382 .IP \(bu 2
383 \f[B]mkosi dependencies\f[R] was beefed up to handle more scenarios
384 properly
385 .IP \(bu 2
386 The default list of kernel modules that are always added to the
387 initramfs was extended with various virtualization modules.
388 .IP \(bu 2
389 Added a \f[B]Repositories=\f[R] match.
390 .IP \(bu 2
391 Cached images are now invalidated if packages specified via
392 \f[B]PackageDirectories=\f[R] change.
393 .IP \(bu 2
394 Added \f[B]VolatilePackageDirectories=\f[R] which can be used to provide
395 local packages that do not invalidate cached images.
396 .IP \(bu 2
397 \f[B]mkosi.pkgmngr\f[R] is now used as the default path for
398 \f[B]PackageManagerTrees=\f[R].
399 .IP \(bu 2
400 The package directory that build scripts can use to make built packages
401 available for installation (\f[B]$PACKAGEDIR\f[R]) is now shared between
402 all image builds.
403 This means that packages built in earlier images and stored in
404 \f[B]$PACKAGEDIR\f[R] become available for installation in all
405 subsequent image builds.
406 .IP \(bu 2
407 The default tools tree distribution is now chosen based on the host
408 distribution instead of the target distribution.
409 .IP \(bu 2
410 mkosi can now be invoked from the initramfs.
411 .SS v23.1
412 .IP \(bu 2
413 Respin due to git tag mismatch
414 .SS v23
415 .IP \(bu 2
416 Added \f[B]CleanScripts=\f[R] to allow running custom cleanup code
417 whenever mkosi cleans up the output directory.
418 This allows cleaning up extra outputs produced by e.g.\ a build script
419 that mkosi doesn\(cqt know about.
420 .IP \(bu 2
421 Added \f[B]ConfigureScripts=\f[R] to allow dynamically modifying the
422 mkosi configuration.
423 Each configure script receives the current config as JSON on stdin and
424 should output the new config as JSON on stdout.
425 .IP \(bu 2
426 When building a UKI, we don\(cqt measure for the TPM SHA1 PCR bank
427 anymore.
428 .IP \(bu 2
429 All keys in the mkosi config JSON output are now in pascal case, except
430 for credentials and environments, where the keys encode names of
431 credentials and environment variables and are therefore case sensitive.
432 .IP \(bu 2
433 Added various settings to allow running mkosi behind a proxy.
434 .IP \(bu 2
435 Various fixes to kernel module filtering that should result in fewer
436 modules being pulled into the default initrd when
437 \f[B]KernelModulesExclude=\f[R] or \f[B]KernelModulesInitrdExclude=\f[R]
438 are used.
439 .IP \(bu 2
440 Added \f[B]ToolsTreeDistribution=\f[R] match.
441 .IP \(bu 2
442 Removed \f[B]vmspawn\f[R] verb and replaced it with
443 \f[B]VirtualMachineMonitor=\f[R].
444 .IP \(bu 2
445 New specifiers for various directories were added.
446 \f[B]%D\f[R] resolves to the directory that mkosi was invoked in,
447 \f[B]%P\f[R] to the current working directory, and \f[B]%C\f[R] to the
448 parent directory of the config file.
449 .IP \(bu 2
450 Added \f[B]ForwardJournal=\f[R] to have systemd inside a container/VM
451 forward its journal to the specified file or directory.
452 .IP \(bu 2
453 Systemd scopes are now allocated for qemu, swtpm, virtiofsd and
454 systemd\-journal\-remote if available.
455 .IP \(bu 2
456 The \f[B]mkosi qemu\f[R] virtual machine is now registered with
457 systemd\-machined if available.
458 .IP \(bu 2
459 Added new \f[B]oci\f[R] output format
460 .IP \(bu 2
461 Runtime trees without a target are now mounted to \f[B]/root/src\f[R]
462 instead of a subdirectory of it (To have the same behaviour as
463 \f[B]BuildSources=\f[R]).
464 .IP \(bu 2
465 Added \f[B]RuntimeBuildSources=\f[R] to mount build and source
466 directories when booting the image with \f[B]mkosi nspawn\f[R] or
467 \f[B]mkosi qemu\f[R].
468 .IP \(bu 2
469 Introduced \f[B]\-\-append\f[R] to allow command line settings to be
470 parsed after parsing configuration files.
471 .IP \(bu 2
472 \f[B]distribution\-release\f[R] is not installed by default anymore on
473 OpenSUSE.
474 .IP \(bu 2
475 Setting \f[B]QemuSmp=\f[R] to \f[B]0\f[R] will now make qemu use all
476 available CPUs
477 .IP \(bu 2
478 Free page reporting and discard request processing are now enabled by
479 default in VMs spawned by \f[B]mkosi qemu\f[R].
480 .IP \(bu 2
481 Added \f[B]ToolsTreeCertificates=\f[R] to allow configuring whether to
482 use certificates and keys from the tools tree (if one is used) or the
483 host.
484 .IP \(bu 2
485 Added \f[B]never\f[R] for \f[B]CacheOnly=\f[R] to specify that
486 repository metadata should always be refreshed.
487 .IP \(bu 2
488 Renamed the \f[B]none\f[R] option for \f[B]CacheOnly=\f[R] to
489 \f[B]auto\f[R].
490 .IP \(bu 2
491 Added \f[B]ProxyExclude=\f[R] to configure hostnames for which requests
492 should not go through the configured proxy.
493 .IP \(bu 2
494 The default tools tree is now reused on incremental builds.
495 .IP \(bu 2
496 Added \f[B]VolatilePackages=\f[R] and \f[B]InitrdVolatilePackages=\f[R]
497 to configure packages that should be installed after executing build
498 scripts and which should not be cached when using
499 \f[B]Incremental=\f[R].
500 .IP \(bu 2
501 \f[B]PackageDirectories=\f[R] now has an associated default path
502 \f[B]mkosi.packages\f[R].
503 .IP \(bu 2
504 \f[B]reprepro\f[R] is now used to generate local apt repositories.
505 .IP \(bu 2
506 Support for BSD tar/cpio was dropped.
507 .IP \(bu 2
508 When both \f[B]ExtraSearchPaths=\f[R] and \f[B]ToolsTree=\f[R] are used,
509 mkosi will now prefer running a binary found in
510 \f[B]ExtraSearchPaths=\f[R] without the tools tree over running the
511 binary from the tools tree.
512 If a binary is not found in \f[B]ExtraSearchPaths=\f[R], the tools tree
513 is used instead.
514 .IP \(bu 2
515 An artifact directory is now made available when running scripts which
516 can be used to pass around data between different scripts.
517 mkosi will also look for microcode and initrds in the artifact directory
518 under the \f[B]io.mkosi.microcode\f[R] and \f[B]io.mkosi.initrd\f[R]
519 subdirectories.
520 .IP \(bu 2
521 Added \f[B]Environment=\f[R] match setting to check for environment
522 variables defined with the \f[B]Environment=\f[R] setting.
523 .IP \(bu 2
524 The \f[B]basesystem\f[R] package is now always installed in Fedora and
525 CentOS images instead of the \f[B]filesystem\f[R] package.
526 .IP \(bu 2
527 The \f[B]qemu\f[R], \f[B]shell\f[R] and \f[B]boot\f[R] verbs do not
528 automatically build the image anymore unless \f[B]\-\-force\f[R] is
529 specified.
530 .IP \(bu 2
531 \f[B]SplitArtifacts=\f[R] is now supported for the portable, sysext and
532 confext outputs.
533 .IP \(bu 2
534 The \f[B]WithDocs=\f[R] option was implemented for pacman\-based
535 distributions.
536 .IP \(bu 2
537 The default Fedora release was bumped to 40.
538 .IP \(bu 2
539 \f[B]QemuSwtpm=\f[R] can now be used with \f[B]QemuFirmware=\f[R] set to
540 \f[B]linux\f[R] or \f[B]bios\f[R].
541 .IP \(bu 2
542 Added \f[B]UnitProperties=\f[R] to allow configure properties on the
543 scopes generated by \f[B]systemd\-nspawn\f[R] and
544 \f[B]systemd\-run\f[R].
545 .IP \(bu 2
546 mkosi now only builds a single default tools tree per build using the
547 settings from the last regular image that we\(cqll build.
548 .IP \(bu 2
549 Configure scripts are now only executed for verbs which imply an image
550 build and are executed with the tools tree instead of without it.
551 .IP \(bu 2
552 \f[B]$QEMU_ARCHITECTURE\f[R] is now set for configure scripts to easily
553 allow scripts to figure out which qemu binary will be used to run qemu.
554 .IP \(bu 2
555 A file ID can now be specified for \f[B]QemuDrives=\f[R].
556 This allows adding multiple qemu drives that are backed by the same
557 file.
558 .IP \(bu 2
559 mkosi doesn\(cqt fail anymore if images already exist when running
560 \f[B]mkosi build\f[R].
561 .IP \(bu 2
562 Image names from \f[B]mkosi.images/\f[R] are now preferred over the
563 specified image ID when determining the output filename to use for an
564 image.
565 .IP \(bu 2
566 \f[B]\-\-include\f[R] now has a shorthand option \f[B]\-I\f[R].
567 .IP \(bu 2
568 The \f[B]WITH_NETWORK\f[R] environment variable is now passed to build
569 and finalize scripts.
570 .IP \(bu 2
571 We now clamp mtimes to the specified source date epoch timestamp instead
572 of resetting all mtimes.
573 This means that we won\(cqt touch any mtimes that are already older than
574 the given source date epoch timestamp.
575 .IP \(bu 2
576 Removed support for CentOS 8 Stream as it is now EOL.
577 .IP \(bu 2
578 The \f[B]coredumpctl\f[R] and \f[B]journalctl\f[R] verbs now operrate on
579 the path specified in \f[B]ForwardJournal=\f[R] if one is set.
580 .IP \(bu 2
581 Added \f[B]UnifiedKernelImageFormat=\f[R] format setting to allow
582 configuring the naming of unified kernel images generated by mkosi.
583 .IP \(bu 2
584 The \f[B]versionlock\f[R] plugin is now enabled by default for dnf with
585 a noop configuration.
586 .IP \(bu 2
587 \f[B]Repositories=\f[R] is now implemented for zypper.
588 .IP \(bu 2
589 \f[B]KernelModulesInclude=\f[R] and
590 \f[B]KernelModulesInitrdInclude=\f[R] now take the special values
591 \f[B]host\f[R] and \f[B]default\f[R] to include the host\(cqs loaded
592 modules and the default kernel modules defined in
593 \f[B]mkosi\-initrd\f[R] respectively.
594 .IP \(bu 2
595 \f[B]KernelModulesIncludeHost=\f[R] and
596 \f[B]KernelModulesInitrdIncludeHost=\f[R] are now deprecated.
597 .IP \(bu 2
598 Added \f[B]mkosi dependencies\f[R] to output the list of packages
599 required by mkosi to build and boot images.
600 .SS v22
601 .IP \(bu 2
602 We\(cqll now try to delete btrfs subvolumes with \f[B]btrfs subvolume
603 delete\f[R] first before falling back to recursively deleting the
604 directory.
605 .IP \(bu 2
606 The invoking user is now always mapped to \f[B]root\f[R] when running
607 sync scripts.
608 This fixes an issue where we would fail when a package manager tree or
609 skeleton tree contained a \f[B]/usr\f[R] directory as we would not have
610 permissions to run mount in the sandbox.
611 .IP \(bu 2
612 We now use qemu\(cqs official firmware descriptions to find EDK2/OVMF
613 UEFI firmware.
614 Addititionally, \f[B]QemuFirmware=uefi\f[R] now boots without SecureBoot
615 support, and \f[B]QemuFirmware=uefi\-secure\-boot\f[R] was introduced to
616 boot with SecureBoot support.
617 By default we will still boot with SecureBoot support if
618 \f[B]QemuFirmware=auto\f[R].
619 .IP \(bu 2
620 Added support for \f[B]QemuFirmwareVariables=custom\f[R] and
621 \f[B]QemuFirmwareVariables=microsoft\f[R] to use OVMF/EDK2 variables
622 with either the user\(cqs custom keys enrolled or with the Microsoft
623 keys enrolled.
624 .IP \(bu 2
625 Added \f[B]UnifiedKernelImages=\f[R] to control whether we generate
626 unified kernel images or not.
627 .IP \(bu 2
628 \f[B]Bootloader=grub\f[R] will now generate a grub EFI image and install
629 it.
630 If \f[B]SecureBoot=\f[R] is enabled and \f[B]ShimBootloader=\f[R] is not
631 set to \f[B]signed\f[R], the grub EFI image will be signed for
632 SecureBoot.
633 .IP \(bu 2
634 \f[B]ShimBootloader=signed\f[R] will now also instruct mkosi to look for
635 and install already signed grub, systemd\-boot, kernel and UKI binaries.
636 .IP \(bu 2
637 We now build grub images with a fixed set of modules and don\(cqt copy
638 any grub modules to the ESP anymore.
639 .IP \(bu 2
640 The configuration is now made available as a JSON file to all mkosi
641 scripts via the \f[B]$MKOSI_CONFIG\f[R] environment variable.
642 .IP \(bu 2
643 \f[B]$PROFILE\f[R] is now set for all mkosi scripts containing the value
644 of \f[B]Profile=\f[R] if it is set.
645 .SS v21
646 .IP \(bu 2
647 We now handle unmerged\-usr systems correctly
648 .IP \(bu 2
649 Builtin configs (\f[B]mkosi\-initrd\f[R], \f[B]mkosi\-tools\f[R]) can
650 now be included using \f[B]Include=\f[R]
651 (e.g.\ \f[B]Include=mkosi\-initrd\f[R])
652 .IP \(bu 2
653 The kernel\-install plugin now uses the builtin \f[B]mkosi\-initrd\f[R]
654 config so there\(cqs no need anymore to copy the full
655 \f[B]mkosi\-initrd\f[R] config into \f[B]/usr/lib/mkosi\-initrd\f[R].
656 .IP \(bu 2
657 We don\(cqt require a build anymore for the \f[B]journalctl\f[R] and
658 \f[B]coredumpctl\f[R] verbs.
659 .IP \(bu 2
660 \f[B]mkosi ssh\f[R] works again when used with
661 \f[B]ToolsTree=default\f[R]
662 .IP \(bu 2
663 We now use \f[B].zst\f[R] instead of \f[B].zstd\f[R] for compressed
664 split artifacts produced by \f[B]systemd\-repart\f[R].
665 .IP \(bu 2
666 \f[B]systemd\-repart\f[R] uses a persistent temporary directory again
667 for assembling images instead of a tmpfs.
668 .IP \(bu 2
669 Added \f[B]MicrocodeHost=\f[R] setting to only include the CPU specific
670 microcode for the current host system.
671 .IP \(bu 2
672 The kernel\-install plugin now only includes the CPU specific microcode
673 .IP \(bu 2
674 Introduced \f[B]PackageCacheDirectory=\f[R] to set the directory for
675 package manager caches.
676 This setting defaults to a suitable location in the system or user
677 directory depending on how mkosi is invoked.
678 \f[B]CacheDirectory=\f[R] is only used for incremental cached images
679 now.
680 .IP \(bu 2
681 Repository metadata is now synced once at the start of each image build
682 and never during an image build.
683 Each image includes a snapshot of the repository metadata in the
684 canonical locations in \f[B]/var\f[R] so that incremental images and
685 extension images can reuse the same snapshot.
686 When building an image intended to be used with \f[B]BaseTrees=\f[R],
687 disable \f[B]CleanPackageMetadata=\f[R] to make sure the repository
688 metadata in \f[B]/var\f[R] is not cleaned up, otherwise any extension
689 images using this image as their base tree will not be able to install
690 additional packages.
691 .IP \(bu 2
692 Implemented \f[B]CacheOnly=metadata\f[R].
693 Note that in the JSON output, the value of \f[B]CacheOnly=\f[R] will now
694 be a string instead of a boolean.
695 .IP \(bu 2
696 Added \f[B]CompressLevel=\f[R] to set the compression level to use.
697 .IP \(bu 2
698 Dropped experimental Gentoo support.
699 .IP \(bu 2
700 Added \f[B]TriggerMatch=\f[R] to specify multiple match sections of
701 which only one should be satisfied.
702 .IP \(bu 2
703 Added \f[B]jq\f[R], \f[B]attr\f[R], \f[B]acl\f[R], \f[B]git\f[R],
704 \f[B]sed\f[R], \f[B]grep\f[R] and \f[B]findutils\f[R] to the default
705 tools tree.
706 .IP \(bu 2
707 Added \f[B]mkosi\-install\f[R], \f[B]mkosi\-upgrade\f[R],
708 \f[B]mkosi\-remove\f[R] and \f[B]mkosi\-reinstall\f[R] scripts which
709 allow writing scripts that are independent of the package manager being
710 used to build the image.
711 .IP \(bu 2
712 We now expand specifiers in \f[B]Match\f[R] section values
713 .IP \(bu 2
714 Made GPG key handling for Fedora rawhide more robust
715 .IP \(bu 2
716 If systemd\-repart 256 or newer is available, mkosi will instruct it to
717 generate \f[B]/etc/fstab\f[R] and \f[B]/etc/crypttab\f[R] for the image
718 if any partition definitions contain the corresponding settings
719 (\f[B]MountPoint=\f[R] and \f[B]EncryptedVolume=\f[R]).
720 .IP \(bu 2
721 \f[B]bash\f[R] is now started in the debug shell instead of
722 \f[B]sh\f[R].
723 .IP \(bu 2
724 The default release for Ubuntu is now \f[B]noble\f[R].
725 .IP \(bu 2
726 Ubuntu is now used as the default tools tree distribution for Ubuntu
727 instead of Debian.
728 .IP \(bu 2
729 Added \f[B]mkosi vmspawn\f[R] which boots the image with
730 \f[B]systemd\-vmspawn\f[R].
731 Note that \f[B]systemd\-vmspawn\f[R] is experimental and its interface
732 may still change.
733 As such \f[B]mkosi vmspawn\f[R] is also considered experimental.
734 Note that \f[B]systemd\-vmspawn\f[R] version \f[B]256\f[R] or newer is
735 required.
736 .IP \(bu 2
737 Added \f[B]SyncScripts=\f[R] which can be used to update various build
738 sources before starting the image build.
739 .IP \(bu 2
740 The \f[B]DISTRIBUTION=\f[R] and \f[B]RELEASE=\f[R] environment variables
741 are now set when running scripts.
742 .IP \(bu 2
743 Added \f[B]ToolsTreeRepositories=\f[R] and
744 \f[B]ToolsTreePackageManagerTrees=\f[R].
745 .IP \(bu 2
746 Added \f[B]RuntimeNetwork=\f[R] to configure the networking used when
747 booting the image.
748 .IP \(bu 2
749 Added \f[B]SecureBootKeySource=\f[R] and \f[B]VerityKeySource=\f[R] to
750 support signing images with OpenSSL engines.
751 Note that these settings require various systemd tools to be version
752 \f[B]256\f[R] or newer.
753 .IP \(bu 2
754 We don\(cqt clean up package manager metadata anymore unless explicitly
755 requested with \f[B]CleanPackageManagerMetadata=yes\f[R] when building
756 \f[B]directory\f[R] and \f[B]tar\f[R] images.
757 .SS v20.2
758 .IP \(bu 2
759 Fixed a bug in signing unsigned shim EFI binaries.
760 .IP \(bu 2
761 We now build an early microcode initrd in the mkosi kernel\-install
762 plugin.
763 .IP \(bu 2
764 Added \f[B]PackageDirectories=\f[R] to allow providing extra packages to
765 be made available during the build.
766 .IP \(bu 2
767 Fixed issue where \f[B]KernelModulesIncludeHost\f[R] was including
768 unnecessary modules
769 .IP \(bu 2
770 Fixed \f[B]\-\-mirror\f[R] specification for CentOS (and variants) and
771 Fedora.
772 Previously a subdirectory within the mirror had to be specified which
773 prevented using CentOS and EPEL repositories from the same mirror.
774 Now only the URL has be specified.
775 .IP \(bu 2
776 We now mount package manager cache directories when running scripts on
777 the host so that any packages installed in scripts are properly cached.
778 .IP \(bu 2
779 We don\(cqt download filelists on Fedora anymore
780 .IP \(bu 2
781 Nested build sources don\(cqt cause errors anymore when trying to
782 install packages.
783 .IP \(bu 2
784 We don\(cqt try to build the same tools tree more than once anymore when
785 building multiple images.
786 .IP \(bu 2
787 We now create the \f[B]/etc/mtab\f[R] compatibility symlink in
788 mkosi\(cqs sandbox.
789 .IP \(bu 2
790 We now always hash the root password ourselves instead of leaving it to
791 \f[B]systemd\-firstboot\f[R].
792 .IP \(bu 2
793 \f[B]/srv\f[R] and \f[B]/mnt\f[R] are not mounted read\-only anymore
794 during builds.
795 .IP \(bu 2
796 Fixed a crash when running mkosi in a directory with fewer than two
797 parent directories.
798 .IP \(bu 2
799 Implemented \f[B]RepositoryKeyCheck=\f[R] for apt\-based distributions.
800 .SS v20.1
801 .IP \(bu 2
802 \f[B]BuildSources=\f[R] are now mounted when we install packages so
803 local packages can be made available in the sandbox.
804 .IP \(bu 2
805 Fixed check to see if we\(cqre running as root which makes sure we
806 don\(cqt do shared mounts when running as root.
807 .IP \(bu 2
808 The extension release file is now actually written when building system
809 or configuration extensions.
810 .IP \(bu 2
811 The nspawn settings are copied to the output directory again.
812 .IP \(bu 2
813 Incremental caching is now skipped when \f[B]Overlay=\f[R] is enabled as
814 this combination isn\(cqt supported.
815 .IP \(bu 2
816 The SELinux relabel check is more granular and now checks for all
817 required files instead of just whether there\(cqs a policy configured.
818 .IP \(bu 2
819 \f[B]qemu\-system\-xxx\f[R] binaries are now preferred over the generic
820 \f[B]qemu\f[R] and \f[B]qemu\-kvm\f[R] binaries.
821 .IP \(bu 2
822 Grub tools from the tools tree are now used to install grub instead of
823 grub tools from the image itself.
824 The grub tools were added to the default tools trees as well.
825 .IP \(bu 2
826 The pacman keyring in tools trees is now only populated from the Arch
827 Linux keyring (and not the Debian/Ubuntu ones anymore).
828 .IP \(bu 2
829 \f[B]gpg\f[R] is allowed to access \f[B]/run/pscsd/pscsd.comm\f[R] on
830 the host if it exists to allow interaction with smartcards.
831 .SS v20
832 .IP \(bu 2
833 The current working directory is not mounted unconditionally to
834 \f[B]/work/src\f[R] anymore.
835 Instead, the default value for \f[B]BuildSources=\f[R] now mounts the
836 current working directory to \f[B]/work/src\f[R].
837 This means that the current working directory is no longer implicitly
838 included when \f[B]BuildSources=\f[R] is explicitly configured.
839 .IP \(bu 2
840 Assigning the empty string to a setting that takes a list of values now
841 overrides any configured default value as well.
842 .IP \(bu 2
843 The github action does not build and install systemd from source
844 anymore.
845 Instead, \f[B]ToolsTree=default\f[R] can be used to make sure a recent
846 version of systemd is used to do the image build.
847 .IP \(bu 2
848 Added \f[B]EnvironmentFiles=\f[R] to read environment variables from
849 environment files.
850 .IP \(bu 2
851 We drastically reduced how much of the host system we expose to scripts.
852 Aside from \f[B]/usr\f[R], a few directories in \f[B]/etc\f[R],
853 \f[B]/tmp\f[R], \f[B]/var/tmp\f[R] and various directories configured in
854 mkosi settings, all host directories are hidden from scripts, package
855 managers and other tools executed by mkosi.
856 .IP \(bu 2
857 Added \f[B]RuntimeScratch=\f[R] to automatically mount a directory with
858 extra scratch space into mkosi\-spawned containers and virtual machines.
859 .IP \(bu 2
860 Package manager trees can now be used to configure every tool invoked by
861 mkosi while building an image that reads config files from
862 \f[B]/etc\f[R] or \f[B]/usr\f[R].
863 .IP \(bu 2
864 Added \f[B]SELinuxRelabel=\f[R] to specify whether to relabel selinux
865 files or not.
866 .IP \(bu 2
867 Many fixes to tools trees were made and tools trees are now covered by
868 .RS 2
869 .IP "CI." 4
870 Some combinations aren\(cqt possible yet but we\(cqre actively working
871 to make these possible.
872 .RE
873 .IP \(bu 2
874 \f[B]mkosi qemu\f[R] now supports direct kernel boots of \f[B]s390x\f[R]
875 and \f[B]powerpc\f[R] images.
876 .IP \(bu 2
877 Added \f[B]HostArchitecture=\f[R] match to match against the host
878 architecture.
879 .IP \(bu 2
880 We don\(cqt use the user\(cqs SSH public/private keypair anymore for
881 \f[B]mkosi ssh\f[R] but instead use a separate key pair which can be
882 generated by \f[B]mkosi genkey\f[R].
883 Users using \f[B]mkosi ssh\f[R] will have to run \f[B]mkosi genkey\f[R]
884 once to generate the necessary files to keep \f[B]mkosi ssh\f[R]
885 working.
886 .IP \(bu 2
887 We don\(cqt automatically set \f[B]\-\-offline=no\f[R] anymore when we
888 detect the \f[B]Subvolumes=\f[R] setting is used in a
889 \f[B]systemd\-repart\f[R] partition definition file.
890 Instead, use the new \f[B]RepartOffline=\f[R] option to explicitly
891 disable running \f[B]systemd\-repart\f[R] in offline mode.
892 .IP \(bu 2
893 During the image build we now install UKIs/kernels/initrds to
894 \f[B]/boot\f[R] instead of \f[B]/efi\f[R].
895 While this will generally not be noticeable, users with custom
896 systemd\-repart ESP partition definitions will need to add
897 \f[B]CopyFiles=/boot:/\f[R] along with the usual
898 \f[B]CopyFiles=/efi:/\f[R] to their ESP partition definitions.
899 By installing UKIs/kernels/initrds to \f[B]/boot\f[R], it becomes
900 possible to use \f[B]/boot\f[R] to populate an XBOOTLDR partition which
901 wasn\(cqt possible before.
902 Note that this is also safe to do before \f[B]v20\f[R] so
903 \f[B]CopyFiles=/boot:/\f[R] can unconditionally be added to any ESP
904 partition definition files.
905 .IP \(bu 2
906 Added \f[B]QemuFirmwareVariables=\f[R] to allow specifying a custom OVMF
907 variables file to use.
908 .IP \(bu 2
909 Added \f[B]MinimumVersion=\f[R] to allow specifying the minimum required
910 mkosi version to build an image.
911 .IP \(bu 2
912 Added support for Arch Linux\(cqs debug repositories.
913 .IP \(bu 2
914 Merged the mkosi\-initrd project into mkosi itself.
915 mkosi\-initrd is now used to build the default initrd.
916 .IP \(bu 2
917 Implemented mkosi\-initrd for all supported distributions.
918 .IP \(bu 2
919 Added \f[B]ShimBootloader=\f[R] to support installing shim to the ESP.
920 .IP \(bu 2
921 Added sysext, confext and portable output formats.
922 These will produce signed disk images that can be used as sysexts,
923 confexts and portable services respectively.
924 .IP \(bu 2
925 Added \f[B]QemuVsockConnectionId=\f[R] to configure how to allocate the
926 vsock connection ID when \f[B]QemUVsock=\f[R] is enabled.
927 .IP \(bu 2
928 Added documentation on how to build sysexts with mkosi.
929 .IP \(bu 2
930 Global systemd user presets are now also configured.
931 .IP \(bu 2
932 Implemented \f[B]WithDocs=\f[R] for \f[B]apt\f[R].
933 .IP \(bu 2
934 On supported package managers, locale data for other locales is now
935 stripped if the local is explicitly configured using \f[B]Locale=\f[R].
936 .IP \(bu 2
937 All \f[B]rpm\f[R] plugins are now disabled when building images.
938 .IP \(bu 2
939 Added \f[B]KernelModulesIncludeHost=\f[R] and
940 \f[B]KernelModulesInitrdIncludeHost=\f[R] to only include modules loaded
941 on the host system in the image/initrd respectively.
942 .IP \(bu 2
943 Implemented \f[B]RemovePackages=\f[R] for Arch Linux.
944 .IP \(bu 2
945 Added \f[B]useradd\f[R] and \f[B]groupadd\f[R] scripts to configure
946 these binaries to operate on the image during builds instead on the
947 host.
948 .IP \(bu 2
949 Added microcode support.
950 If installed into the image, an early microcode initrd will
951 automatically be built and prepended to the initrd.
952 .IP \(bu 2
953 A passwordless root account may now be created by specifying
954 \f[B]hashed:\f[R].
955 .IP \(bu 2
956 The \f[B]Autologin=\f[R] feature was extended with support for
957 \f[B]arm64\f[R], \f[B]s390x\f[R] and \f[B]powerpc\f[R] architectures.
958 .IP \(bu 2
959 Added \f[B]SecureBootAutoEnroll=\f[R] to control automatic enrollment of
960 secureboot keys separately from signing \f[B]systemd\-boot\f[R] and
961 generated UKIs.
962 .IP \(bu 2
963 \f[B]ImageVersion=\f[R] is no longer automatically appended to the
964 output files, instead this is automatically appended to
965 \f[B]Output=\f[R] if not specified and results in the \f[B]%o\f[R]
966 specifier being equivalent to \f[B]%i\f[R] or \f[B]%i_%v\f[R] depending
967 on whether \f[B]ImageVersion=\f[R] is specified.
968 .SS v19
969 .IP \(bu 2
970 Support for RHEL was added!
971 .IP \(bu 2
972 Added \f[B]journalctl\f[R] and \f[B]coredumpctl\f[R] verbs for running
973 the respective tools on built directory or disk images.
974 .IP \(bu 2
975 Added a \f[B]burn\f[R] verb to write the output image to a block device.
976 .IP \(bu 2
977 Added a new \f[B]esp\f[R] output format, which is largely similar to the
978 existing \f[B]uki\f[R] output format but wraps it in a disk image with
979 only an ESP.
980 .IP \(bu 2
981 \f[B]Presets\f[R] were renamed to \f[B]Images\f[R].
982 \f[B]mkosi.images/\f[R] is now used instead of \f[B]mkosi.presets/\f[R],
983 the \f[B]Presets=\f[R] setting was renamed to \f[B]Images=\f[R] and the
984 \f[B]Presets\f[R] section was merged into the \f[B]Config\f[R] section.
985 The old names can still be used for backwards compatibility.
986 .IP \(bu 2
987 Added profiles to support building variants of the same image in one
988 repository.
989 Profiles can be defined in \f[B]mkosi.profiles/\f[R] and one can be
990 selected using the new \f[B]Profile=\f[R] setting.
991 .IP \(bu 2
992 mkosi will now parse \f[B]mkosi.local.conf\f[R] before any other config
993 files if that exists.
994 .IP \(bu 2
995 Added a kernel\-install plugin.
996 This is only shipped in source tree and not included in the Python
997 module.
998 .IP \(bu 2
999 Added a \f[B]\-\-json\f[R] option to get the output of \f[B]mkosi
1000 summary\f[R] as JSON.
1001 .IP \(bu 2
1002 Added shorthand \f[B]\-a\f[R] for \f[B]\-\-autologin\f[R].
1003 .IP \(bu 2
1004 Added a \f[B]\-\-debug\-workspace\f[R] option to not remove the
1005 workspace directory after a build.
1006 This is useful to inspect the workspace after failing builds.
1007 As a consequence the prefix for the default workspace directory prefix
1008 has been changed from \f[B].mkosi\-tmp\f[R] to
1009 \f[B]mkosi\-workspace\f[R].
1010 .IP \(bu 2
1011 Scripts with the \f[B].chroot\f[R] extension are now executed in the
1012 image automatically.
1013 .IP \(bu 2
1014 Added \f[B]rpm\f[R] helper script to have \f[B]rpm\f[R] automatically
1015 operate on the image when running scripts.
1016 .IP \(bu 2
1017 Added \f[B]mkosi\-as\-caller\f[R] helper script that can be used in
1018 scripts to run commands as the user invoking mkosi.
1019 .IP \(bu 2
1020 \f[B]mkosi\-chroot\f[R] will now start a shell if no arguments are
1021 specified.
1022 .IP \(bu 2
1023 Added \f[B]WithRecommends=\f[R] to configure whether to install
1024 recommended packages by default or not where this is supported.
1025 It is disabled by default.
1026 .IP \(bu 2
1027 Added \f[B]ToolsTreeMirror=\f[R] setting for configuring the mirror to
1028 use for the default tools tree.
1029 .IP \(bu 2
1030 \f[B]WithDocs=\f[R] is now enabled by default.
1031 .IP \(bu 2
1032 Added \f[B]BuildSourcesEphemeral=\f[R] to make source directories
1033 ephemeral when running scripts.
1034 This means any changes made to source directories while running scripts
1035 will be undone after the scripts have finished executing.
1036 .IP \(bu 2
1037 Added \f[B]QemuDrives=\f[R] to have mkosi create extra qemu drives and
1038 pass them to qemu when using the \f[B]qemu\f[R] verb.
1039 .IP \(bu 2
1040 Added \f[B]BuildSources=\f[R] match to match against configured build
1041 source targets.
1042 .IP \(bu 2
1043 \f[B]PackageManagerTrees=\f[R] was moved to the \f[B]Distribution\f[R]
1044 section.
1045 .IP \(bu 2
1046 We now automatically configure the qemu firmware, kernel cmdline and
1047 initrd based on what type of kernel is passed by the user via
1048 \f[B]\-kernel\f[R] or \f[B]QemuKernel=\f[R].
1049 .IP \(bu 2
1050 The mkosi repository itself now ships configuration to build basic
1051 bootable images that can be used to test mkosi.
1052 .IP \(bu 2
1053 Added support for enabling \f[B]updates\-testing\f[R] repositories for
1054 Fedora.
1055 .IP \(bu 2
1056 GPG keys for CentOS, Fedora, Alma and Rocky are now looked up locally
1057 first before fetching them remotely.
1058 .IP \(bu 2
1059 Signatures are not required for local packages on Arch anymore.
1060 .IP \(bu 2
1061 Packages on opensuse are now always downloaded in advance before
1062 installation when using zypper.
1063 .IP \(bu 2
1064 The tar output is now reproducible.
1065 .IP \(bu 2
1066 We now make sure \f[B]git\f[R] can be executed from mkosi scripts
1067 without running into permission errors.
1068 .IP \(bu 2
1069 We don\(cqt create subdirectories beneath the configured cache directory
1070 anymore.
1071 .IP \(bu 2
1072 Workspace directories are now created outside of any source directories.
1073 mkosi will either use \f[B]XDG_CACHE_HOME\f[R], \f[B]$HOME/.cache\f[R]
1074 or \f[B]/var/tmp\f[R] depending on the situation.
1075 .IP \(bu 2
1076 Added environment variable \f[B]MKOSI_DNF\f[R] to override which dnf to
1077 use for building images (\f[B]dnf\f[R] or \f[B]dnf5\f[R]).
1078 .IP \(bu 2
1079 The rootfs can now be modified when running build scripts (with all
1080 changes thrown away after the last build script has been executed).
1081 .IP \(bu 2
1082 mkosi now fails if configuration specified via the CLI does not apply to
1083 any image (because it is overridden).
1084 .IP \(bu 2
1085 Added a new doc on building rpms from source with mkosi
1086 (\f[B]docs/building\-rpms\-from\-source.md\f[R]).
1087 .IP \(bu 2
1088 \f[B]/etc/resolv.conf\f[R] will now only be mounted for scripts when
1089 they are run with network access.
1090 .SS v18
1091 .IP \(bu 2
1092 \f[B]$SCRIPT\f[R] was renamed to \f[B]$CHROOT_SCRIPT\f[R].
1093 \f[B]$SCRIPT\f[R] can still be used but is considered deprecated.
1094 .IP \(bu 2
1095 Added \f[B]RuntimeTrees=\f[R] setting to mount directories when booting
1096 images via \f[B]mkosi boot\f[R], \f[B]mkosi shell\f[R] or \f[B]mkosi
1097 qemu\f[R].
1098 The directories are mounted with a uid map that maps the user invoking
1099 mkosi to the root user so that all files in the directory appear as if
1100 owned by the root user in the container or virtual machine and any new
1101 files created in the directories are owned by the user invoking mkosi.
1102 To make this work in VMs, we use \f[B]VirtioFS\f[R] via
1103 \f[B]virtiofsd\f[R].
1104 Note that this requires systemd v254 or newer to be installed in the
1105 image.
1106 .IP \(bu 2
1107 Added support for booting directory images with \f[B]mkosi qemu\f[R] via
1108 \f[B]VirtioFS\f[R].
1109 When \f[B]CONFIG_VIRTIOFS\f[R] and \f[B]CONFIG_VIRTIO_PCI\f[R] are
1110 builtin modules, no initramfs is required to make this work.
1111 .IP \(bu 2
1112 Added \f[B]Include=\f[R] or \f[B]\-\-include\f[R] to include extra
1113 configuration files or directories.
1114 .IP \(bu 2
1115 Added support for specifiers to access the current value of certain
1116 settings during configuration file parsing.
1117 .IP \(bu 2
1118 \f[B]mkosi\f[R] will now exit with an error when no configuration was
1119 provided.
1120 .IP \(bu 2
1121 Multiple scripts of the same type are now supported.
1122 .IP \(bu 2
1123 Custom distributions are now supported via the new \f[B]custom\f[R]
1124 distribution.
1125 When using \f[B]custom\f[R] as the distribution, the rootfs must be
1126 provided via base trees, skeleton trees or prepare scripts.
1127 .IP \(bu 2
1128 We now use local GPG keys for rpm based distributions if the
1129 \f[B]distribution\-gpg\-keys\f[R] package is installed on the host.
1130 .IP \(bu 2
1131 Added \f[B]RuntimeSize=\f[R] to grow the image to a specific size before
1132 booting it when using \f[B]mkosi boot\f[R] or \f[B]mkosi qemu\f[R].
1133 .IP \(bu 2
1134 We now set \f[B]MKOSI_UID\f[R] and \f[B]MKOSI_GID\f[R] when running
1135 scripts which are set to the uid and gid of the user invoking mkosi
1136 respectively.
1137 These can be used to run commands as the user that invoked mkosi.
1138 .IP \(bu 2
1139 Added an \f[B]Architecture=\f[R] match
1140 .IP \(bu 2
1141 Initrds specified with \f[B]Initrds=\f[R] are now used for grub
1142 menuentries as well.
1143 .IP \(bu 2
1144 \f[B]ImageId=\f[R] and \f[B]ImageVersion=\f[R] are now written to
1145 os\-release as \f[B]IMAGE_ID\f[R] and \f[B]IMAGE_VERSION\f[R] if
1146 provided.
1147 .IP \(bu 2
1148 We pass command line arguments passed to the \f[B]build\f[R] verb to the
1149 build script again.
1150 .IP \(bu 2
1151 We added support for the \(lqRHEL Universal Base Image\(rq distribution.
1152 .SS v17.1
1153 .IP \(bu 2
1154 Fixed bug where \f[B]\-\-autologin\f[R] was broken when used in
1155 combination with a tools tree when using a packaged version of mkosi.
1156 .SS v17
1157 .IP \(bu 2
1158 Added \f[B]ToolsTreePackages=\f[R] to add extra packages to the default
1159 tools tree.
1160 .IP \(bu 2
1161 Added \f[B]SystemdVersion=\f[R] match to match on the host\(cqs systemd
1162 version
1163 .IP \(bu 2
1164 Added \f[B]Format=\f[R] match to match on the configured output format
1165 .IP \(bu 2
1166 \f[B]Presets=\f[R] can now be configured in global configuration files
1167 to select which presets to build
1168 .IP \(bu 2
1169 UKIs can now be booted using direct linux boot.
1170 .IP \(bu 2
1171 We don\(cqt try to make images UEFI bootable anymore on architectures
1172 that do not support UEFI
1173 .IP \(bu 2
1174 Fixed \f[B]\-\-help\f[R] to show all options again
1175 .IP \(bu 2
1176 We now warn when settings are configured in the wrong section
1177 .SS v16
1178 .IP \(bu 2
1179 \f[B]mkosi.version\f[R] is now picked up from preset and dropin
1180 directories as well following the usual config precedence logic
1181 .IP \(bu 2
1182 Removed the \(lqfirst assignment wins\(rq logic from configuration
1183 parsing.
1184 Settings parsed later will now override earlier values
1185 .IP \(bu 2
1186 Removed the \f[B]!\f[R] operator for lists.
1187 Instead, assign the empty string to the list to remove all previous
1188 values.
1189 .IP \(bu 2
1190 Added support for configuring custom default values for settings by
1191 prefixing their name in the configuration file with \f[B]\(at\f[R].
1192 .IP \(bu 2
1193 Added \f[B]QemuCdrom=\f[R] to attach the image to the virtual machine as
1194 a CD\-ROM instead of a block device.
1195 .IP \(bu 2
1196 Added \f[B]SectorSize=\f[R] to set the sector size of the disk images
1197 built by systemd\-repart.
1198 .IP \(bu 2
1199 Added back grub support (BIOS/UEFI).
1200 Note that we don\(cqt install grub on UEFI yet but we do add the
1201 necessary configuration and partitions.
1202 .IP \(bu 2
1203 Added \f[B]Bootloader=\f[R] option to configure which EFI bootloader to
1204 install.
1205 Added \f[B]uki\f[R] option to install just the UKI without systemd\-boot
1206 and \f[B]grub\f[R] to generate grub configuration to chainload into the
1207 built UKIs.
1208 .IP \(bu 2
1209 Added \f[B]BiosBootloader=\f[R] to configure whether grub for BIOS gets
1210 installed or not.
1211 .IP \(bu 2
1212 Added \f[B]QemuFirmware=\f[R] to select which qemu firmware to use
1213 (OVMF, Seabios or direct kernel boot).
1214 .IP \(bu 2
1215 Added \f[B]QemuKernel=\f[R] to specify the kernel that should be used
1216 with direct kernel boot.
1217 .IP \(bu 2
1218 \f[B]/var/lib/dbus/machine\-id\f[R] is now removed if it was added by a
1219 package manager postinstall script.
1220 .IP \(bu 2
1221 The manifest is not generated by default anymore.
1222 Use \f[B]ManifestFormat=json\f[R] to make sure the manifest is
1223 generated.
1224 .IP \(bu 2
1225 Added \f[B]SourceDateEpoch=\f[R] to enable more reproducible image
1226 builds.
1227 .IP \(bu 2
1228 Added \f[B]Seed=\f[R] to set the seed passed to systemd\-repart.
1229 .IP \(bu 2
1230 Updated the default Fedora release to Fedora 39.
1231 .IP \(bu 2
1232 If \f[B]ToolsTree=\f[R] is set to \f[B]default\f[R], mkosi will now
1233 build a default tools tree containing all the necessary tools to build
1234 images.
1235 The distribution and release to use can be configured with
1236 \f[B]ToolsTreeDistribution=\f[R] and \f[B]ToolsTreeRelease=\f[R] or are
1237 determined automatically based on the image being built.
1238 .IP \(bu 2
1239 Added \f[B]uki\f[R] output format.
1240 This is similar to \f[B]cpio\f[R], except the cpio is packaged up as a
1241 UKI with a kernel image and stub picked up from the rootfs.
1242 .SS v15.1
1243 .IP \(bu 2
1244 The man page can be generated from the markdown file via
1245 \f[B]tools/make\-man\-page.sh\f[R].
1246 .IP \(bu 2
1247 Fixed issue where not all packages and data files where included in the
1248 generated python package.
1249 .IP \(bu 2
1250 mkosi doesn\(cqt try to unshare the network namespace anymore when it
1251 doesn\(cqt have \f[B]CAP_NET_ADMIN\f[R].
1252 .IP \(bu 2
1253 Fixed issue when the workspace was located in \f[B]/tmp\f[R].
1254 .IP \(bu 2
1255 Don\(cqt try to run \f[B]timedatectl\f[R] or \f[B]ssh\-add\f[R] when
1256 they\(cqre not installed.
1257 .SS v15
1258 .IP \(bu 2
1259 Migrated to systemd\-repart.
1260 Many options are dropped in favor of specifying them directly in repart
1261 partition definition files:
1262 .RS 2
1263 .IP \(bu 2
1264 Format=gpt_xxx options are replaced with a single \(lqdisk\(rq options.
1265 Filesystem to use can now be specified with repart\(cqs Format= option
1266 .IP \(bu 2
1267 Format=plain_squashfs (Can be reproduced by a single repart squashfs
1268 root partition combined with SplitArtifacts=yes)
1269 .IP \(bu 2
1270 Verity= (Replaced by repart\(cqs Verity= options)
1271 .IP \(bu 2
1272 Encrypt= (Replaced by repart\(cqs Encrypt= option)
1273 .IP \(bu 2
1274 RootSize=, HomeSize=, VarSize=, TmpSize=, ESPSize=, SwapSize=, SrvSize=
1275 (Replaced by repart\(cqs size options)
1276 .IP \(bu 2
1277 UsrOnly= (replaced with \f[B]CopyFiles=/:/usr\f[R] in a usr partition
1278 definition)
1279 .IP \(bu 2
1280 OutputSplitRoot=, OutputSplitVerity=, (Replaced by repart\(cqs
1281 SplitName= option)
1282 .IP \(bu 2
1283 OutputSplitKernel= (UKI is now always written to its own output file)
1284 .IP \(bu 2
1285 GPTFirstLBA (Removed, no equivalent in repart)
1286 .IP \(bu 2
1287 ReadOnly= (Replaced by repart\(cqs ReadOnly= option per partition)
1288 .IP \(bu 2
1289 Minimize= (Replaced by repart\(cqs Minimize= option per partition)
1290 .IP \(bu 2
1291 CompressFs= (No equivalent in repart, can be replicated by replacing
1292 mkfs.
1293 in $PATH with a script that adds the necessary command line option)
1294 .IP \(bu 2
1295 MkSquashfs= (Can be replaced with a script in $PATH that invokes the
1296 correct binary)
1297 .PP
1298 We also remove the WithoutUnifiedKernelImages= switch as building
1299 unified kernel images is trivial and fast these days.
1300 .RE
1301 .IP \(bu 2
1302 Support for \(enqemu\-boot was dropped
1303 .IP \(bu 2
1304 Support for \(enuse\-host\-repositories was dropped, use
1305 \(enrepository\-directory instead
1306 .IP \(bu 2
1307 \f[B]RepositoryDirectory\f[R] was removed, use
1308 \f[B]PackageManagerTrees=\f[R] or \f[B]SkeletonTrees=\f[R] instead.
1309 .IP \(bu 2
1310 \f[B]\-\-repositories\f[R] is now only usable on Debian/RPM based
1311 distros and can only be used to enable additional repositories.
1312 Specifically, it cannot be used on Arch Linux anymore to add new
1313 repositories.
1314 .IP \(bu 2
1315 The \f[B]_epel\f[R] distributions were removed.
1316 Use \f[B]\-\-repositories=epel\f[R] instead to enable the EPEL
1317 repository.
1318 .IP \(bu 2
1319 Removed \f[B]\-stream\f[R] from CentOS release specifiers.
1320 Instead of specifying \f[B]8\-stream\f[R], you know just specify
1321 \f[B]8\f[R].
1322 .IP \(bu 2
1323 Removed default kernel command line arguments \f[B]rhgb\f[R],
1324 \f[B]selinux=0\f[R] and \f[B]audit=0\f[R].
1325 .IP \(bu 2
1326 Dropped \(enall and \(enall\-directory as this functionality is better
1327 implemented by using a build system.
1328 .IP \(bu 2
1329 mkosi now builds images without needing root privileges.
1330 .IP \(bu 2
1331 Removed \f[B]\-\-no\-chown\f[R], \f[B]\-\-idmap\f[R] and
1332 \f[B]\-\-nspawn\-keep\-unit\f[R] options as they were made obsolete by
1333 moving to rootless builds.
1334 .IP \(bu 2
1335 Removed \f[B]\-\-source\-file\-transfer\f[R],
1336 \f[B]\-\-source\-file\-transfer\-final\f[R],
1337 \f[B]\-\-source\-resolve\-symlinks\f[R] and
1338 \f[B]\-\-source\-resolve\-symlinks\-final\f[R] in favor of always
1339 mounting the source directory into the build image.
1340 \f[B]\-\-source\-file\-transfer\-final\f[R] might be reimplemented in
1341 the future using virtiofsd.
1342 .IP \(bu 2
1343 Dropped \f[B]\-\-include\-dir\f[R] option.
1344 Usage can be replaced by using \f[B]\-\-incremental\f[R] and reading
1345 includes from the cached build image tree.
1346 .IP \(bu 2
1347 Removed \f[B]\-\-machine\-id\f[R] in favor of shipping images without a
1348 machine ID at all.
1349 .IP \(bu 2
1350 Removed \f[B]\-\-skip\-final\-phase\f[R] as we only have a single phase
1351 now.
1352 .IP \(bu 2
1353 The post install script is only called for the final image now and not
1354 for the build image anymore.
1355 Use the prepare script instead.
1356 .IP \(bu 2
1357 \f[B]\-\-ssh\-key\f[R], \f[B]\-\-ssh\-agent\f[R],
1358 \f[B]\-\-ssh\-port\f[R] and \f[B]\-\-ssh\-timeout\f[R] options were
1359 dropped as the SSH support was reimplemented using VSock.
1360 \f[B]mkosi ssh\f[R] can only be used with images booted with \f[B]mkosi
1361 qemu\f[R].
1362 Use \f[B]machinectl\f[R] to access images booted with \f[B]mkosi
1363 boot\f[R].
1364 Use \(enextra\-tree or \(encredential with the
1365 \f[B].ssh.authorized_keys.root\f[R] credentials as alternatives for
1366 provisioning the public key inside the image.
1367 .IP \(bu 2
1368 Only configuration files matching \f[B]*.conf\f[R] are parsed in dropin
1369 directories now.
1370 .IP \(bu 2
1371 Removed \f[B]\-\-qemu\-headless\f[R], we now start qemu in the terminal
1372 by default and configure the serial console at runtime.
1373 Use the new \f[B]\-\-qemu\-gui\f[R] option to start qemu in its
1374 graphical interface.
1375 .IP \(bu 2
1376 Removed \f[B]\-\-netdev\f[R].
1377 Can be replaced by manually installing systemd\-networkd, putting a
1378 network file in the image and enabling systemd\-networkd.
1379 .IP \(bu 2
1380 If \f[B]mkosi.extra/\f[R] or \f[B]mkosi.skeleton/\f[R] exist, they are
1381 now always used instead of only when no explicit extra/skeleton trees
1382 are defined.
1383 .IP \(bu 2
1384 mkosi doesn\(cqt install any default packages anymore aside from
1385 packages required by the distro or the base filesystem layout package if
1386 there are no required packages.
1387 In practice, this means systemd and other basic tools have to be
1388 installed explicitly from now on.
1389 .IP \(bu 2
1390 Removed \f[B]\-\-base\-packages\f[R] as it\(cqs not needed anymore since
1391 we don\(cqt install any packages by default anymore aside from the base
1392 filesystem layout package.
1393 .IP \(bu 2
1394 Removed \f[B]\-\-qcow2\f[R] option in favor of supporting only raw disk
1395 images as the disk image output format.
1396 .IP \(bu 2
1397 Removed \f[B]\-\-bmap\f[R] option as it can be trivially added manually
1398 by utilizing a finalize script.
1399 .IP \(bu 2
1400 The \f[B]never\f[R] value for \f[B]\-\-with\-network\f[R] was spun of
1401 into its own custom option \f[B]\-\-cache\-only\f[R].
1402 .IP \(bu 2
1403 \f[B]\-\-bootable\f[R] now defaults to \f[B]auto\f[R].
1404 When set to \f[B]auto\f[R], mkosi will generate a bootable image only if
1405 all the necessary packages are installed.
1406 Documentation was added in docs/bootable.md on how a bootable image can
1407 be generated on mainstream distros.
1408 .IP \(bu 2
1409 The RPM db is no longer rebuilt in bdb format on CentOS Stream 8.
1410 To be able to install packages on a CentOS Stream 8 image with a RPM db
1411 in sqlite format, rewrite the db in bdb format using \f[B]rpm
1412 \-\-rebuilddb \-\-define _db_backend bdb\f[R].
1413 .IP \(bu 2
1414 Repositories are now only written to /etc/apt/sources.list if apt is
1415 installed in the image.
1416 .IP \(bu 2
1417 Removed the dependency on \f[B]debootstrap\f[R] to build Ubuntu or
1418 Debian images.
1419 .IP \(bu 2
1420 Apt now uses the keyring from the host instead of the keyring from the
1421 image.
1422 This means \f[B]debian\-archive\-keyring\f[R] or
1423 \f[B]ubuntu\-archive\-keyring\f[R] are now required to be installed to
1424 build Debian or Ubuntu images respectively.
1425 .IP \(bu 2
1426 \f[B]\-\-base\-image\f[R] is split into \f[B]\-\-base\-tree\f[R] and
1427 \f[B]\-\-overlay\f[R].
1428 .IP \(bu 2
1429 Removed \f[B]\-\-cache\-initrd\f[R], instead, use a prebuilt initrd with
1430 \f[B]Initrds=\f[R] to avoid rebuilding the initrd all the time.
1431 .IP \(bu 2
1432 Disk images are now resized to 8G when booted to give some disk space to
1433 play around with in the booted image.
1434 .IP \(bu 2
1435 Removed \f[B]\-\-install\-directory=\f[R] option.
1436 This was originally added for caching the installation results, but this
1437 doesn\(cqt work properly as it might result in leftover files in the
1438 install directory from a previous installation, so we have to empty the
1439 directory before reusing it, invalidating the caching, so the option was
1440 removed.
1441 .IP \(bu 2
1442 Build scripts are now executed on the host.
1443 See the \f[B]SCRIPTS\f[R] section in the manual for more information.
1444 Existing build scripts will need to be updated to make sure they keep
1445 working.
1446 Specifically, most paths in scripts will need to be prefixed with
1447 $BUILDROOT to have them operate on the image instead of on the host
1448 system.
1449 To ensure the host system cannot be modified when running a script, most
1450 host directories are mounted read\-only when running a script to ensure
1451 a script cannot modify the host in any way.
1452 Alternatively to making the script run on the host, the script can also
1453 still be executed in the image itself by putting the following snippet
1454 at the top of the script:
1455 .RS 2
1456 .IP
1457 .EX
1458 \f[B]if\f[R] [ \(dq$container\(dq != \(dqmkosi\(dq ]\f[B];\f[R] \f[B]then\f[R]
1459 exec mkosi\-chroot \(dq$SCRIPT\(dq \(dq$\(at\(dq
1460 \f[B]fi\f[R]
1461 .EE
1462 .RE
1463 .IP \(bu 2
1464 Removed \f[B]\-\-tar\-strip\-selinux\-context=\f[R] option.
1465 We now label all files properly if selinux is enabled and if users
1466 don\(cqt want the labels, they can simply exclude them when extracting
1467 the archive.
1468 .IP \(bu 2
1469 Gentoo is now marked as experimental and unsupported and there\(cqs no
1470 guarantee at all that it will work.
1471 Issues related to gentoo will generally not receive attention from core
1472 maintainers.
1473 All gentoo specific hacks outside of the gentoo implementation module
1474 have been removed.
1475 .IP \(bu 2
1476 A verb \f[B]documentation\f[R] has been added.
1477 Calling mkosi with this verb will show the documentation.
1478 This is useful when running mkosi during development to always have the
1479 documentation in the correct version available.
1480 By default it will try several ways to output the documentation, but a
1481 specific option can be chosen with the \f[B]\-\-doc\-format\f[R] option.
1482 Distro packagers are encouraged to add a file \f[B]mkosi.1\f[R] into the
1483 \f[B]mkosi/resources\f[R] directory of the Python package, if it is
1484 missing, as well es install it in the appropriate search path for man
1485 pages.
1486 The man page can be generated from the markdown file
1487 \f[B]mkosi/resources/mkosi.md\f[R] e.g via \f[B]pandoc \-t man \-s \-o
1488 mkosi.1 mkosi.md\f[R].
1489 .IP \(bu 2
1490 BuildSources= now takes source:target pairs which specify the source
1491 directory and where to mount it relative to the top level source
1492 directory when running scripts.
1493 (e.g.\ BuildSources=../my\-project:my\-project)
1494 .SS v14
1495 .IP \(bu 2
1496 Support for Clear Linux was dropped.
1497 See https://github.com/systemd/mkosi/pull/1037 for more information.
1498 .IP \(bu 2
1499 Support for Photon was dropped.
1500 See https://github.com/systemd/mkosi/pull/1048 for more information.
1501 .IP \(bu 2
1502 The Arch kernel/bootloader pacman hooks were removed.
1503 For anyone that still wants to use them, they can be found \c
1504 .UR https://github.com/systemd/mkosi/tree/v13/mkosi/resources/arch
1505 here
1506 .UE \c
1507 \&.
1508 .IP \(bu 2
1509 mkosi now creates \f[B]distro\(tirelease\f[R] subdirectories inside the
1510 build, cache and output directories for each \f[B]distro\(tirelease\f[R]
1511 combination that is built.
1512 This allows building for multiple distros without throwing away the
1513 results of a previous distro build every time.
1514 .IP \(bu 2
1515 The preferred names for mkosi configuration files and directories are
1516 now \f[B]mkosi.conf\f[R] and \f[B]mkosi.conf.d/\f[R] respectively.
1517 The old names (\f[B]mkosi.default\f[R] and \f[B]mkosi.default.d\f[R])
1518 have been removed from the docs but are still supported for backwards
1519 compatibility.
1520 .IP \(bu 2
1521 \f[B]plain_squashfs\f[R] type images will now also be named with a
1522 \f[B].raw\f[R] suffix.
1523 .IP \(bu 2
1524 \f[B]tar\f[R] type images will now respect the \f[B]\-\-compress\f[R]
1525 option.
1526 .IP \(bu 2
1527 Pacman\(cqs \f[B]SigLevel\f[R] option was changed to use the same
1528 default value as used on Arch which is \f[B]SigLevel = Required
1529 DatabaseOptional\f[R].
1530 If this results in keyring errors, you need to update the keyring by
1531 running \f[B]pacman\-key \-\-populate archlinux\f[R].
1532 .IP \(bu 2
1533 Support for CentOS 7 was dropped.
1534 If you still need to support CentOS 7, we recommend using any mkosi
1535 version up to 13.
1536 .IP \(bu 2
1537 Support for BIOS/grub was dropped.
1538 because EFI hardware is widely available and legacy BIOS systems do not
1539 support the feature set to fully verify a boot chain from firmware to
1540 userland and it has become bothersome to maintain for little use.
1541 .RS 2
1542 .PP
1543 To generate BIOS images you can use any version of mkosi up to mkosi 13
1544 or the new \f[B]\-\-bios\-size\f[R] option.
1545 This can be used to add a BIOS boot partition of the specified size on
1546 which \f[B]grub\f[R] (or any other bootloader) can be installed with the
1547 help of mkosi\(cqs script support (depending on your needs most likely
1548 \f[B]mkosi.postinst\f[R] or \f[B]mkosi.finalize\f[R]).
1549 This method can also be used for other EFI bootloaders that mkosi
1550 intentionally does not support.
1551 .RE
1552 .IP \(bu 2
1553 mkosi now unconditionally copies the kernel, initrd and kernel cmdline
1554 from the image that were previously only copied out for Qemu boot.
1555 .IP \(bu 2
1556 mkosi now runs apt and dpkg on the host.
1557 As such, we now require apt and dpkg to be installed on the host along
1558 with debootstrap in order to be able to build debian/ubuntu images.
1559 .IP \(bu 2
1560 Split dm\-verity artifacts default names have been changed to match what
1561 \f[B]systemd\f[R] and other tools expect: \f[B]image.root.raw\f[R],
1562 \f[B]image.root.verity\f[R], \f[B]image.root.roothash\f[R],
1563 \f[B]image.root.roothash.p7s\f[R] (same for \f[B]usr\f[R] variants).
1564 .IP \(bu 2
1565 \f[B]mkosi\f[R] will again default to the same OS release as the host
1566 system when the host system uses the same distribution as the image
1567 that\(cqs being built.
1568 .IP \(bu 2
1569 By default, \f[B]mkosi\f[R] will now change the owner of newly created
1570 directories to \f[B]SUDO_UID\f[R] or \f[B]PKEXEC_UID\f[R] if defined,
1571 unless \f[B]\-\-no\-chown\f[R] is used.
1572 .IP \(bu 2
1573 If \f[B]systemd\-nspawn\f[R] v252 or newer is used, bind\-mounted
1574 directories with \f[B]systemd\-nspawn\f[R] will use the new
1575 \f[B]rootidmap\f[R] option so files and directories created from within
1576 the container will be owned by the actual directory owner on the host.
1577 .SS v13
1578 .IP \(bu 2
1579 The \f[B]\-\-network\-veth\f[R] option has been renamed to
1580 \f[B]\-\-netdev\f[R].
1581 The old name made sense with virtual ethernet devices, but when booting
1582 images with qemu a TUN/TAP device is used instead.
1583 .IP \(bu 2
1584 The network config file installed by mkosi when the \f[B]\-\-netdev\f[R]
1585 (previously \f[B]\-\-network\-veth\f[R]) option is used (formerly
1586 \f[B]/etc/systemd/network/80\-mkosi\-network\-veth.network\f[R] in the
1587 image) now only matches network interfaces using the
1588 \f[B]virtio_net\f[R] driver.
1589 Please make sure you weren\(cqt relying on this file to configure any
1590 network interfaces other than the tun/tap virtio\-net interface created
1591 by mkosi when booting the image in QEMU with the \f[B]\-\-netdev\f[R]
1592 option.
1593 If you were relying on this config file when the host system uses the
1594 same distribution as the image that\(cqs being built.
1595 Instead, when no release is specified, mkosi will now always default to
1596 the default version embedded in mkosi itself.
1597 .IP \(bu 2
1598 \f[B]mkosi\f[R] will now use the \f[B]pacman\f[R] keyring from the host
1599 when building Arch images.
1600 This means that users will, on top of installing
1601 \f[B]archlinux\-keyring\f[R], also have to run \f[B]pacman\-key
1602 \-\-init\f[R] and \f[B]pacman\-key \-\-populate archlinux\f[R] on the
1603 host system to be able to build Arch images.
1604 Also, unless the package manager is configured to do it automatically,
1605 the host keyring will have to be updated after
1606 \f[B]archlinux\-keyring\f[R] updates by running \f[B]pacman\-key
1607 \-\-populate archlinux\f[R] and \f[B]pacman\-key \-\-updatedb\f[R].
1608 .IP \(bu 2
1609 Direct qemu linux boot is now supported with
1610 \f[B]BootProtocols=linux\f[R].
1611 When enabled, the kernel image, initrd, and cmdline will be extracted
1612 from the image and passed to \f[B]qemu\f[R] by \f[B]mkosi qemu\f[R] to
1613 directly boot into the kernel image without a bootloader.
1614 This can be used to boot for example s390x images in \f[B]qemu\f[R].
1615 .IP \(bu 2
1616 The initrd will now always be rebuilt after the extra trees and build
1617 artifacts have been installed into the image.
1618 .IP \(bu 2
1619 The github action has been migrated to Ubuntu Jammy.
1620 To migrate any jobs using the action, add \f[B]runs\-on:
1621 ubuntu\-22.04\f[R] to the job config.
1622 .IP \(bu 2
1623 All images are now configured by default with the \f[B]C.UTF\-8\f[R]
1624 locale.
1625 .IP \(bu 2
1626 New \f[B]\-\-repository\-directory\f[R] option can be used to configure
1627 a directory with extra repository files to be used by the package
1628 manager when building an image.
1629 Note that this option is currently only supported for \f[B]pacman\f[R]
1630 and \f[B]dnf\f[R]\-based distros.
1631 .IP \(bu 2
1632 Option \f[B]\-\-skeleton\-tree\f[R] is now supported on Debian\-based
1633 distros.
1634 .IP \(bu 2
1635 Removed \f[B]\-\-hostname\f[R] as its trivial to configure using
1636 systemd\-firstboot.
1637 .IP \(bu 2
1638 Removed default locale configuration as its trivial to configure using
1639 systemd\-firstboot and systemd writes a default locale well.
1640 .SS v12
1641 .IP \(bu 2
1642 Fix handling of baselayout in Gentoo installations.
1643 .SS v11
1644 .IP \(bu 2
1645 Support for Rocky Linux, Alma Linux, and Gentoo has been added!
1646 .IP \(bu 2
1647 A new \f[B]ManifestFormat=\f[R] option can be used to generate
1648 \(lqmanifest\(rq files that describe what packages were installed.
1649 With \f[B]json\f[R], a JSON file that shows the names and versions of
1650 all installed packages will be created.
1651 With \f[B]changelog\f[R], a longer human\-readable file that shows
1652 package descriptions and changelogs will be generated.
1653 This latter format should be considered experimental and likely to
1654 change in later versions.
1655 .IP \(bu 2
1656 A new \f[B]RemovePackages=\f[R] option can be used to uninstall packages
1657 after the build and finalize scripts have been done.
1658 This is useful for the case where packages are required by the build
1659 scripts, or pulled in as dependencies for scriptlets of other packages,
1660 but are not necessary in the final image.
1661 .IP \(bu 2
1662 A new \f[B]BaseImage=\f[R] option can be used to build \(lqsystem
1663 extensions\(rq a.k.a.
1664 \(lqsysexts\(rq \(em partial images which are mounted on top of an
1665 existing system to provide additional files under \f[B]/usr/\f[R].
1666 See the \c
1667 .UR https://www.freedesktop.org/software/systemd/man/systemd-sysext.html
1668 systemd\-sysext man page
1669 .UE \c
1670 \ for more information.
1671 .IP \(bu 2
1672 A new \f[B]CleanPackageMetadata=\f[R] option can be used to force or
1673 disable the removal of package manager files.
1674 When this option is not used, they are removed when the package manager
1675 is not installed in the final image.
1676 .IP \(bu 2
1677 A new \f[B]UseHostRepositories=\f[R] option instructs mkosi to use
1678 repository configuration from the host system, instead of the internal
1679 list.
1680 .IP \(bu 2
1681 A new \f[B]SshAgent=\f[R] option configures the path to the ssh agent.
1682 .IP \(bu 2
1683 A new \f[B]SshPort=\f[R] option overrides the port used for ssh.
1684 .IP \(bu 2
1685 The \f[B]Verity=\f[R] setting supports a new value \f[B]signed\f[R].
1686 When set, verity data will be signed and the result inserted as an
1687 additional partition in the image.
1688 See https://systemd.io/DISCOVERABLE_PARTITIONS for details about signed
1689 disk images.
1690 This information is used by \f[B]systemd\-nspawn\f[R],
1691 \f[B]systemd\-dissect\f[R], \f[B]systemd\-sysext\f[R],
1692 \f[B]systemd\-portabled\f[R] and \f[B]systemd\f[R]\(cqs
1693 \f[B]RootImage=\f[R] setting (among others) to cryptographically
1694 validate the image file systems before use.
1695 .IP \(bu 2
1696 The \f[B]\-\-build\-environment=\f[R] option was renamed to
1697 \f[B]\-\-environment=\f[R] and extended to cover \f[I]all\f[R] invoked
1698 scripts, not just the \f[B]mkosi.build\f[R].
1699 The old name is still understood.
1700 .IP \(bu 2
1701 With \f[B]\-\-with\-network=never\f[R], \f[B]dnf\f[R] is called with
1702 \f[B]\-\-cacheonly\f[R], so that the package lists are not refreshed.
1703 This gives a degree of reproducibility when doing repeated installs with
1704 the same package set (and also makes installs significantly faster).
1705 .IP \(bu 2
1706 The \f[B]\-\-debug=\f[R] option gained a new value \f[B]disk\f[R] to
1707 show information about disk sized and partition allocations.
1708 .IP \(bu 2
1709 Some sections and settings have been renamed for clarity: [Packages] is
1710 now [Content], \f[B]Password=\f[R], \f[B]PasswordIsHashed=\f[R], and
1711 \f[B]Autologin=\f[R] are now in [Content].
1712 The old names are still supported, but not documented.
1713 .IP \(bu 2
1714 When
1715 \f[B]\-\-prepare\-script=\f[R]/\f[B]\-\-build\-script=\f[R]/\f[B]\-\-finalize\-script=\f[R]
1716 is used with an empty argument, the corresponding script will not be
1717 called.
1718 .IP \(bu 2
1719 Python 3.7 is the minimal supported version.
1720 .IP \(bu 2
1721 Note to packagers: the Python \f[B]cryptography\f[R] module is needed
1722 for signing of verity data.
1723 .SS v10
1724 .IP \(bu 2
1725 Minimum supported Python version is now 3.7.
1726 .IP \(bu 2
1727 Automatic configuration of the network for Arch Linux was removed to
1728 bring different distros more in line with each other.
1729 To add it back, add a postinstall script to configure your network
1730 manager of choice.
1731 .IP \(bu 2
1732 The \f[B]\-\-default\f[R] option was changed to not affect the search
1733 location of \f[B]mkosi.default.d/\f[R].
1734 mkosi now always searches for \f[B]mkosi.default.d/\f[R] in the working
1735 directory.
1736 .IP \(bu 2
1737 \f[B]quiet\f[R] was dropped from the default kernel command line.
1738 .IP \(bu 2
1739 \f[B]\-\-source\-file\-transfer\f[R] and
1740 \f[B]\-\-source\-file\-transfer\-final\f[R] now accept an empty value as
1741 the argument which can be used to override a previous setting.
1742 .IP \(bu 2
1743 A new command \f[B]mkosi serve\f[R] can be used to serve build artifacts
1744 using a small embedded HTTP server.
1745 This is useful for \f[B]machinectl pull\-raw \&...\f[R] and
1746 \f[B]machinectl pull\-tar \&...\f[R].
1747 .IP \(bu 2
1748 A new command \f[B]mkosi genkey\f[R] can be used to generate secure boot
1749 keys for use with mkosi\(cqs \f[B]\-\-secure\-boot\f[R] options.
1750 The number of days the keys should remain valid can be specified via
1751 \f[B]\-\-secure\-boot\-valid\-days=\f[R] and their CN via
1752 \f[B]\-\-secure\-boot\-common\-name=\f[R].
1753 .IP \(bu 2
1754 When booting images with \f[B]qemu\f[R], firmware that supports Secure
1755 Boot will be used if available.
1756 .IP \(bu 2
1757 \f[B]\-\-source\-resolve\-symlinks\f[R] and
1758 \f[B]\-\-source\-resolve\-symlinks\-final\f[R] options are added to
1759 control how symlinks in the build sources are handled when
1760 \f[B]\-\-source\-file\-transfer[\-final]=copy\-all\f[R] is used.
1761 .IP \(bu 2
1762 \f[B]\-\-build\-environment=\f[R] option was added to set variables for
1763 the build script.
1764 .IP \(bu 2
1765 \f[B]\-\-usr\-only\f[R] option was added to build images that comprise
1766 only the \f[B]/usr/\f[R] directory, instead of the whole root file
1767 system.
1768 This is useful for stateless systems where \f[B]/etc/\f[R] and
1769 \f[B]/var/\f[R] are populated by
1770 \f[B]systemd\-tmpfiles\f[R]/\f[B]systemd\-sysusers\f[R] and related
1771 calls at boot, or systems that are originally shipped without a root
1772 file system, but where \f[B]systemd\-repart\f[R] adds one on the first
1773 boot.
1774 .IP \(bu 2
1775 Support for \(lqimage versions\(rq has been added.
1776 The version number can be set with \f[B]\-\-version\-number=\f[R].
1777 It is included in the default output filename and passed as
1778 \f[B]$IMAGE_VERSION\f[R] to the build script.
1779 In addition, \f[B]mkosi bump\f[R] can be used to increase the version
1780 number by one, and \f[B]\-\-auto\-bump\f[R] can be used to increase it
1781 automatically after successful builds.
1782 .IP \(bu 2
1783 Support for \(lqimage identifiers\(rq has been added.
1784 The id can be set with \f[B]\-\-image=id\f[R] and is passed to the build
1785 script as \f[B]$IMAGE_ID\f[R].
1786 .IP \(bu 2
1787 The list of packages to install can be configured with
1788 \f[B]\-\-base\-packages=\f[R].
1789 With \f[B]\-\-base\-packages=no\f[R], only packages specified with
1790 \f[B]\-\-packages=\f[R] will be installed.
1791 With \f[B]\-\-base\-packages=conditional\f[R], various packages will be
1792 installed \(lqconditionally\(rq, i.e.\ only if some other package is
1793 otherwise pulled in.
1794 For example, \f[B]systemd\-udev\f[R] may be installed only if
1795 \f[B]systemd\f[R] is listed in \f[B]\-\-packages=\f[R].
1796 .IP \(bu 2
1797 CPIO output format has been added.
1798 This is useful for kernel initramfs images.
1799 .IP \(bu 2
1800 Output compression can be configured with \f[B]\-\-compress\-fs=\f[R]
1801 and \f[B]\-\-compress\-output=\f[R], and support for \f[B]zstd\f[R] has
1802 been added.
1803 .IP \(bu 2
1804 \f[B]\-\-ssh\-key=\f[R] option was added to control the ssh key used to
1805 connect to the image.
1806 .IP \(bu 2
1807 \f[B]\-\-remove\-files=\f[R] option was added to remove file from the
1808 generated images.
1809 .IP \(bu 2
1810 Inline comments are now allowed in config files (anything from
1811 \f[B]#\f[R] until the end of the line will be ignored).
1812 .IP \(bu 2
1813 The development branch was renamed from \f[B]master\f[R] to
1814 \f[B]main\f[R].
1815 .SS v9
1816 .SS Highlighted Changes
1817 .IP \(bu 2
1818 The mkosi Github action now defaults to the current release of mkosi
1819 instead of the tip of the master branch.
1820 .IP \(bu 2
1821 Add a \f[B]ssh\f[R] verb and accompanying \f[B]\-\-ssh\f[R] option.
1822 The latter sets up SSH keys for direct SSH access into a booted image,
1823 whereas the former can be used to start an SSH connection to the image.
1824 .IP \(bu 2
1825 Allow for distribution specific \f[B]mkosi.*\f[R] files in
1826 subdirectories of \f[B]mkosi.default.d/\f[R].
1827 These files are only processed if a subdirectory named after the target
1828 distribution of the image is found in \f[B]mkosi.default.d/\f[R].
1829 .IP \(bu 2
1830 The summary of used options for the image is now only printed when
1831 building the image for the first time or when the \f[B]summary\f[R] verb
1832 is used.
1833 .IP \(bu 2
1834 All of mkosi\(cqs output, except for the build script, will now go to
1835 stderr.
1836 There was no clear policy on this before and this choice makes it easier
1837 to use images generated and booted via mkosi with language servers using
1838 stdin and stdout for communication.
1839 .IP \(bu 2
1840 \f[B]\-\-source\-file\-transfer\f[R] now defaults to
1841 \f[B]copy\-git\-others\f[R] to also include untracked files.
1842 .IP \(bu 2
1843 \c
1844 .UR https://github.com/psf/black
1845 black
1846 .UE \c
1847 \ is now used as a code style and conformance with it is checked in CI.
1848 .IP \(bu 2
1849 Add a new \f[B]\-\-ephemeral\f[R] option to boot into a temporary
1850 snapshot of the image that will be thrown away on shutdown.
1851 .IP \(bu 2
1852 Add a new option \f[B]\-\-network\-veth\f[R] to set up a virtual
1853 Ethernet link between the host and the image for usage with nspawn or
1854 QEMU
1855 .IP \(bu 2
1856 Add a new \f[B]\-\-autologin\f[R] option to automatically log into the
1857 root account upon boot of the image.
1858 This is useful when using mkosi for boot tests.
1859 .IP \(bu 2
1860 Add a new \f[B]\-\-hostonly\f[R] option to generate host specific
1861 initrds.
1862 This is useful when using mkosi for boot tests.
1863 .IP \(bu 2
1864 Add a new \f[B]\-\-install\-directory\f[R] option and special directory
1865 \f[B]mkosi.installdir/\f[R] that will be used as \f[B]$DESTDIR\f[R] for
1866 the build script, so that the contents of this directory can be shared
1867 between builds.
1868 .IP \(bu 2
1869 Add a new \f[B]\-\-include\-directory\f[R] option and special directory
1870 \f[B]mkosi.includedir/\f[R] that will be mounted at
1871 \f[B]/usr/include\f[R] during the build.
1872 This way headers files installed during the build can be made available
1873 to the host system, which is useful for usage with language servers.
1874 .IP \(bu 2
1875 Add a new \f[B]\-\-source\-file\-transfer\-final\f[R] option to
1876 complement \f[B]\-\-source\-file\-transfer\f[R].
1877 It does the same \f[B]\-\-source\-file\-transfer\f[R] does for the build
1878 image, but for the final one.
1879 .IP \(bu 2
1880 Add a new \f[B]\-\-tar\-strip\-selinux\-context\f[R] option to remove
1881 SELinux xattrs.
1882 This is useful when an image with a target distribution not using
1883 SELinux is generated on a host that is using it.
1884 .IP \(bu 2
1885 Document the \f[B]\-\-no\-chown\f[R] option.
1886 Using this option, artifacts generated by mkosi are not chowned to the
1887 user invoking mkosi when it is invoked via sudo.
1888 It has been with as for a while, but hasn\(cqt been documented until
1889 now.
1890 .SS Fixed Issues
1891 .IP \(bu 2
1892 \c
1893 .UR https://github.com/systemd/mkosi/issues/506
1894 #506
1895 .UE \c
1896 .IP \(bu 2
1897 \c
1898 .UR https://github.com/systemd/mkosi/issues/559
1899 #559
1900 .UE \c
1901 .IP \(bu 2
1902 \c
1903 .UR https://github.com/systemd/mkosi/issues/561
1904 #561
1905 .UE \c
1906 .IP \(bu 2
1907 \c
1908 .UR https://github.com/systemd/mkosi/issues/562
1909 #562
1910 .UE \c
1911 .IP \(bu 2
1912 \c
1913 .UR https://github.com/systemd/mkosi/issues/575
1914 #575
1915 .UE \c
1916 .IP \(bu 2
1917 \c
1918 .UR https://github.com/systemd/mkosi/issues/580
1919 #580
1920 .UE \c
1921 .IP \(bu 2
1922 \c
1923 .UR https://github.com/systemd/mkosi/issues/593
1924 #593
1925 .UE \c
1926 .SS Authors
1927 .IP \(bu 2
1928 Daan De Meyer
1929 .IP \(bu 2
1930 Joerg Behrmann
1931 .IP \(bu 2
1932 Luca Boccassi
1933 .IP \(bu 2
1934 Peter Hutterer
1935 .IP \(bu 2
1936 ValdikSS