1mkosi(1) mkosi(1)
2
3
4
6 mkosi - Build Legacy-Free OS Images
7
9 mkosi [options...] build
10
11 mkosi [options...] clean
12
13 mkosi [options...] summary
14
15 mkosi [options...] shell [command line...]
16
17 mkosi [options...] boot [nspawn settings...]
18
19 mkosi [options...] qemu
20
22 mkosi is a tool for easily building legacy-free OS images. It’s a fan‐
23 cy wrapper around dnf --installroot, debootstrap, pacstrap and zypper
24 that may generate disk images with a number of bells and whistles.
25
26 Supported output formats
27 The following output formats are supported:
28
29 · Raw GPT disk image, with ext4 as root (gpt_ext4)
30
31 · Raw GPT disk image, with xfs as root (gpt_xfs)
32
33 · Raw GPT disk image, with btrfs as root (gpt_btrfs)
34
35 · Raw GPT disk image, with squashfs as read-only root (gpt_squashfs)
36
37 · Plain squashfs image, without partition table, as read-only root
38 (plain_squashfs)
39
40 · Plain directory, containing the OS tree (directory)
41
42 · btrfs subvolume, with separate subvolumes for /var, /home, /srv,
43 /var/tmp (subvolume)
44
45 · Tarball (tar)
46
47 When a GPT disk image is created, the following additional options are
48 available:
49
50 · A swap partition may be added in
51
52 · The image may be made bootable on EFI and BIOS systems
53
54 · Separate partitions for /srv and /home may be added in
55
56 · The root, /srv and /home partitions may optionally be encrypted with
57 LUKS.
58
59 · A dm-verity partition may be added in that adds runtime integrity da‐
60 ta for the root partition
61
62 Other features
63 · Optionally, create an SHA256SUMS checksum file for the result, possi‐
64 bly even signed via gpg.
65
66 · Optionally, place a specific .nspawn settings file along with the re‐
67 sult.
68
69 · Optionally, build a local project’s source tree in the image and add
70 the result to the generated image (see below).
71
72 · Optionally, share RPM/DEB package cache between multiple runs, in or‐
73 der to optimize build speeds.
74
75 · Optionally, the resulting image may be compressed with XZ.
76
77 · Optionally, the resulting image may be converted into a QCOW2 file
78 suitable for qemu storage.
79
80 · Optionally, btrfs’ read-only flag for the root subvolume may be set.
81
82 · Optionally, btrfs’ compression may be enabled for all created subvol‐
83 umes.
84
85 · By default images are created without all files marked as documenta‐
86 tion in the packages, on distributions where the package manager sup‐
87 ports this. Use the --with-docs flag to build an image with docs
88 added.
89
90 Command Line Verbs
91 The following command line verbs are known:
92
93 build This builds the image, based on the settings passed in on the
94 command line or read from a mkosi.default file, see below. This
95 verb is the default if no verb is explicitly specified. This
96 command must be executed as root.
97
98 clean Remove build artifacts generated on a previous build. If com‐
99 bined with -f, also removes incremental build cache images. If
100 -f is specified twice, also removes any package cache.
101
102 summary
103 Outputs a human-readable summary of all options used for build‐
104 ing an image. This will parse the command line and mkosi.de‐
105 fault file as it would do on build, but only output what it is
106 configured for and not actually build anything.`
107
108 shell This builds the image if it is not build yet, and then invokes
109 systemd-nspawn to acquire an interactive shell prompt in it. If
110 this verb is used an optional command line may be specified
111 which is then invoked in place of the shell in the container.
112 Combine this with -f in order to rebuild the image uncondition‐
113 ally before acquiring the shell, see below. This command must
114 be executed as root.
115
116 boot Similar to shell but boots the image up using systemd-nspawn.
117 If this verb is used an optional command line may be specified
118 which is passed as “kernel command line” to the init system in
119 the image.
120
121 qemu Similar to boot but uses qemu to boot up the image, i.e. instead
122 of container virtualization VM virtualization is used. This
123 verb is only supported on images that contain a boot loader,
124 i.e. those built with --bootable (see below). This command must
125 be executed as root unless the image already exists and -f is
126 not specified.
127
128 ssh When the image is built with the --ssh option, this command con‐
129 nects to a booted (boot, qemu verbs) container/VM via SSH. Make
130 sure to run mkosi ssh with the same config as mkosi build was
131 run with so that it has the necessary information available to
132 connect to the running container/VM via SSH.
133
134 help This verb is equivalent to the --help switch documented below:
135 it shows a brief usage explanation.
136
137 Command Line Parameters
138 The following command line parameters are understood. Note that many
139 of these parameters can also be set in the mkosi.default file, for de‐
140 tails see the table below.
141
142 --distribution=, -d
143 The distribution to install in the image. Takes one of the fol‐
144 lowing arguments: fedora, debian, ubuntu, arch, opensuse,
145 mageia, centos, clear, photon, openmandriva. If not specified,
146 defaults to the distribution of the host.
147
148 --release=, -r
149 The release of the distribution to install in the image. The
150 precise syntax of the argument this takes depends on the distri‐
151 bution used, and is either a numeric string (in case of Fedora,
152 CentOS, ..., e.g. 29), or a distribution version name (in case
153 of Debian, Ubuntu, ..., e.g. artful). If neither this option,
154 not --distribution= is specified, defaults to the distribution
155 version of the host. If the distribution is specified, defaults
156 to a recent version of it.
157
158 --mirror=, -m
159 The mirror to use for downloading the distribution packages.
160 Expects a mirror URL as argument.
161
162 --repositories=
163 Additional package repositories to use during installation. Ex‐
164 pects one or more URLs as argument, separated by commas. This
165 option may be used multiple times, in which case the list of
166 repositories to use is combined. Use “!*” to remove all reposi‐
167 tories from to the list or use e.g. “!repo-url” to remove just
168 one specific repository. For Arch Linux, additional reposito‐
169 ries must be passed in the form <name>::<url> (e.g. myre‐
170 po::https://myrepo.net).
171
172 --architecture=
173 The architecture to build the image for. Note that this cur‐
174 rently only works for architectures compatible with the host’s
175 architecture.
176
177 --format=, -t
178 The image format type to generate. One of directory (for gener‐
179 ating OS images inside a local directory), subvolume (similar,
180 but as a btrfs subvolume), tar (similar, but a tarball of the
181 image is generated), gpt_ext4 (a block device image with an ext4
182 file system inside a GPT partition table), gpt_xfs (similar, but
183 with an xfs file system), gpt_btrfs (similar, but with an btrfs
184 file system), gpt_squashfs (similar, but with a squashfs file
185 system), plain_squashfs (a plain squashfs file system without a
186 partition table).
187
188 --output=, -o
189 Path for the output image file to generate. Takes a relative or
190 absolute path where the generated image will be placed. If nei‐
191 ther this option nor --output-dir= is used (see below), the im‐
192 age is generated under the name image, but its name suffixed
193 with an appropriate file suffix (e.g. image.raw.xz in case
194 gpt_ext4 is used in combination with --xz).
195
196 --output-dir=, -O
197 Path to a directory where to place all generated artifacts
198 (i.e. the SHA256SUMS file and similar). If this is not speci‐
199 fied and a directory mkosi.output/ exists in the local directory
200 it is automatically used for this purpose. If this is not spec‐
201 ified and such a directory does not exist, all output artifacts
202 are placed adjacent to the output image file.
203
204 --force, -f
205 Replace the output file if it already exists, when building an
206 image. By default when building an image and an output artifact
207 already exists mkosi will refuse operation. Specify -f to
208 delete all build artifacts from a previous run before re-build‐
209 ing the image. If incremental builds are enabled (see below),
210 specifying this option twice will ensure the intermediary cache
211 files are removed, too, before the re-build is initiated. If a
212 package cache is used (see below), specifying this option thrice
213 will ensure the package cache is removed too, before the re-
214 build is initiated. For the clean operation -f has a slightly
215 different effect: by default the verb will only remove build ar‐
216 tifacts from a previous run, when specified once the incremental
217 cache files are deleted too, and when specified twice the pack‐
218 age cache is also removed.
219
220 --gpt-first-lba
221 Override the first usable LBA (Logical Block Address) within the
222 GPT header. This defaults to 2048 which is actually the desired
223 value. However, some tools, e.g. the prl_disk_tool utility from
224 the Parallels virtualization suite require this to be set to 34,
225 otherwise they might fail to resize the disk image and/or parti‐
226 tions inside it.
227
228 --bootable, -b
229 Generate a bootable image. By default this will generate an im‐
230 age bootable on UEFI systems. Use --boot-protocols= to select
231 support for a different boot protocol.
232
233 --boot-protocols=
234 Pick one or more boot protocols to support when generating a
235 bootable image, as enabled with --bootable above. Takes a com‐
236 ma-separated list of uefi or bios. May be specified more than
237 once in which case the specified lists are merged. If uefi is
238 specified the sd-boot UEFI boot loader is used, if bios is spec‐
239 ified the GNU Grub boot loader is used. Use “!*” to remove all
240 previously added protocols or “!protocol” to remove one proto‐
241 col.
242
243 --kernel-command-line=
244 Use the specified kernel command line when building bootable im‐
245 ages. By default command line arguments get appended. To re‐
246 move all arguments from the current list pass “!*”. To remove
247 specific arguments add a space separated list of “!” prefixed
248 arguments. For example adding “!* console=ttyS0 rw” to a
249 mkosi.default file or the command line arguments passes “con‐
250 sole=ttyS0 rw” to the kernel in any case. Just adding “con‐
251 sole=ttyS0 rw” would append these two arguments to the kernel
252 command line created by lower priority configuration files or
253 previous –kernel-command-line command line arguments.
254
255 --secure-boot
256 Sign the resulting kernel/initrd image for UEFI SecureBoot
257
258 --secure-boot-key=
259 Path to the PEM file containing the secret key for signing the
260 UEFI kernel image, if --secure-boot is used.
261
262 --secure-boot-certificate=
263 Path to the X.509 file containing the certificate for the signed
264 UEFI kernel image, if --secure-boot is used.
265
266 --read-only
267 Make root file system read-only. Only applies to gpt_ext4,
268 gpt_xfs, gpt_btrfs, subvolume output formats, and implied on
269 gpt_squashfs and plain_squashfs.
270
271 --minimize
272 Attempt to make the resulting root file system as small as pos‐
273 sible by removing free space from the file system. Only sup‐
274 ported for gpt_ext4 and gpt_btrfs. For ext4 this relies on re‐
275 size2fs -M, which reduces the free disk space but is not perfect
276 and generally leaves some free space. For btrfs the results are
277 optimal and no free space is left.
278
279 --encrypt
280 Encrypt all partitions in the file system or just the root file
281 system. Takes either all or data as argument. If all the root,
282 /home and /srv file systems will be encrypted using dm-
283 crypt/LUKS (with its default settings). If data the root file
284 system will be left unencrypted, but /home and /srv will be en‐
285 crypted. The passphrase to use is read from the
286 mkosi.passphrase file in the current working directory (see be‐
287 low). Note that the UEFI System Partition (ESP) containing the
288 boot loader and kernel to boot is never encrypted since it needs
289 to be accessible by the firmware.
290
291 --verity
292 Add an “Verity” integrity partition to the image. If enabled,
293 the root partition is protected with dm-verity against off-line
294 modification, the verification data is placed in an additional
295 GPT partition. Implies --read-only.
296
297 --compress=
298 Compress the generated file systems. Only applies to gpt_btrfs,
299 subvolume, gpt_squashfs, plain_squashfs. Takes one of zlib,
300 lzo, zstd, lz4, xz or a boolean value as argument. If the lat‐
301 ter is used compression is enabled/disabled and the default al‐
302 gorithm is used. In case of the squashfs output formats com‐
303 pression is implied, however this option may be used to select
304 the algorithm.
305
306 --mksquashfs=
307 Set the path to the mksquashfs executable to use. This is use‐
308 ful in case the parameters for the tool shall be augmented, as
309 the tool may be replaced by a script invoking it with the right
310 parameters, this way.
311
312 --xz Compress the resulting image with xz. This only applies to
313 gpt_ext4, gpt_xfs, gpt_btrfs, gpt_squashfs and is implied for
314 tar. Note that when applied to the block device image types
315 this means the image cannot be started directly but needs to be
316 decompressed first. This also means that the shell, boot, qemu
317 verbs are not available when this option is used.
318
319 --qcow2
320 Encode the resulting image as QEMU QCOW2 image. This only ap‐
321 plies to gpt_ext4, gpt_xfs, gpt_btrfs, gpt_squashfs. QCOW2 im‐
322 ages can be read natively by qemu, but not by the Linux kernel.
323 This means the shell and boot verbs are not available when this
324 option is used, however qemu will work.
325
326 --hostname=
327 Set the image’s hostname to the specified name.
328
329 --without-unified-kernel-images
330 If specified, mkosi does not build unified kernel images and in‐
331 stead installs kernels with a separate initrd and boot loader
332 config to the efi or bootloader partition.
333
334 --hostonly-initrd
335 If specified, mkosi will run the tool to create the initrd such
336 that a non-generic initrd is created that will only be able to
337 run on the system mkosi is run on. Currently mkosi uses dracut
338 for all supported distributions except Clear Linux and this op‐
339 tion translates to enabling dracut’s hostonly option.
340
341 --no-chown
342 By default, if mkosi is run inside a sudo environment all gener‐
343 ated artifacts have their UNIX user/group ownership changed to
344 the user which invoked sudo. With this option this may be
345 turned off and all generated files are owned by root.
346
347 --tar-strip-selinux-context
348 If running on a SELinux-enabled system (Fedora, CentOS), files
349 inside the container are tagged with SELinux context extended
350 attributes (xattrs), which may interfere with host SELinux rules
351 in building or further container import stages. This option
352 strips SELinux context attributes from the resulting tar ar‐
353 chive.
354
355 --incremental, -i
356 Enable incremental build mode. This only applies if the two-
357 phase mkosi.build build script logic is used. In this mode, a
358 copy of the OS image is created immediately after all OS pack‐
359 ages are unpacked but before the mkosi.build script is invoked
360 in the development container. Similar a copy of the final image
361 is created immediately before the build artifacts from the
362 mkosi.build script are copied in. On subsequent invocations of
363 mkosi with the -i switch these cached images may be used to skip
364 the OS package unpacking, thus drastically speeding up repeti‐
365 tive build times. Note that when this is used and a pair of
366 cached incremental images exists they are not automatically re‐
367 generated, even if options such as --packages= are modified. In
368 order to force rebuilding of these cached images, combined -i
369 with -ff, which ensures the cached images are removed first, and
370 then re-created.
371
372 --package=, -p
373 Install the specified distribution packages (i.e. RPM, DEB, ...)
374 in the image. Takes a comma separated list of packages. This
375 option may be used multiple times in which case the specified
376 package list is combined. Packaged specified this way will be
377 installed both in the development and the final image (see be‐
378 low). Use --build-package= (see below) to specify packages that
379 shall only be used for the image generated in the build image,
380 but that shall not appear in the final image. To remove a pack‐
381 age e.g. added by a mkosi.default configuration file prepend the
382 package name with a ! letter. For example -p “!apache2” would
383 remove the apache2 package. To replace the apache2 package by
384 the httpd package just add -p “!apache2,httpd” to the command
385 line arguments. To remove all packages use “!*”.
386
387 --with-docs
388 Include documentation in the image built. By default if the un‐
389 derlying distribution package manager supports it documentation
390 is not included in the image built. The $WITH_DOCS environment
391 variable passed to the mkosi.build script indicates whether this
392 option was used or not, see below.
393
394 --without-tests, -T
395 If set the $WITH_TESTS environment variable is set to 0 when the
396 mkosi.build script is invoked. This is supposed to be used by
397 the build script to bypass any unit or integration tests that
398 are normally run during the source build process. Note that
399 this option has no effect unless the mkosi.build build script
400 honors it.
401
402 --cache=
403 Takes a path to a directory to use as package cache for the dis‐
404 tribution package manager used. If this option is not used, but
405 a mkosi.cache/ directory is found in the local directory it is
406 automatically used for this purpose (also see below). The di‐
407 rectory configured this way is mounted into both the development
408 and the final image while the package manager is running.
409
410 --extra-tree=
411 Takes a path to a directory to copy on top of the OS tree the
412 package manager generated. Use this to override any default
413 configuration files shipped with the distribution. If this op‐
414 tion is not used, but the mkosi.extra/ directory is found in the
415 local directory it is automatically used for this purpose (also
416 see below). Instead of a directory a tar file may be specified
417 too. In this case it is unpacked into the OS tree before the
418 package manager is invoked. This mode of operation allows set‐
419 ting permissions and file ownership explicitly, in particular
420 for projects stored in a version control system such as git
421 which does retain full file ownership and access mode metadata
422 for committed files. If a tar file mkosi.extra.tar is found in
423 the local directory it automatically used for this purpose.
424
425 --skeleton-tree=
426 Takes a path to a directory to copy into the OS tree before in‐
427 voking the package manager. Use this to insert files and direc‐
428 tories into the OS tree before the package manager installs any
429 packages. If this option is not used, but the mkosi.skeleton/
430 directory is found in the local directory it is automatically
431 used for this purpose (also see below). As with the extra tree
432 logic above, instead of a directory a tar file may be used too,
433 and mkosi.skeleton.tar is automatically used.
434
435 --build-script=
436 Takes a path to an executable that is used as build script for
437 this image. If this option is used the build process will be
438 two-phased instead of single-phased (see below). The specified
439 script is copied onto the development image and executed inside
440 an systemd-nspawn container environment. If this option is not
441 used, but the mkosi.build file found in the local directory it
442 is automatically used for this purpose (also see below).
443
444 --build-sources=
445 Takes a path of a source tree to copy into the development im‐
446 age, if a build script is used. This only applies if a build
447 script is used, and defaults to the local directory. Use
448 --source-file-transfer= to configure how the files are trans‐
449 ferred from the host to the container image.
450
451 --build-dir=
452 Takes a path of a directory to use as build directory for build
453 systems that support out-of-tree builds (such as Meson). The
454 directory used this way is shared between repeated builds, and
455 allows the build system to reuse artifacts (such as object
456 files, executable, ...) generated on previous invocations. This
457 directory is mounted into the development image when the build
458 script is invoked. The build script can find the path to this
459 directory in the $BUILDDIR environment variable. If this option
460 is not specified, but a directory mkosi.builddir/ exists in the
461 local directory it is automatically used for this purpose (also
462 see below).
463
464 --include-directory
465 Takes a path of a directory to use as the include directory.
466 This directory is mounted at /usr/include when building the
467 build image and when running the build script. This means all
468 include files installed to /usr/include will be stored in this
469 directory. This is useful to make include files available on
470 the host system for use by language servers to provide code com‐
471 pletion. If this option is not specified, but a directory
472 mkosi.includedir/ exists in the local directory, it is automati‐
473 cally used for this purpose (also see below).
474
475 --install-directory
476 Takes a path of a directory to use as the install directory.
477 The directory used this way is shared between builds and allows
478 the build system to not have to reinstall files that were al‐
479 ready installed by a previous build and didn’t change. The
480 build script can find the path to this directory in the $DESTDIR
481 environment variable. If this option is not specified, but a
482 directory mkosi.installdir exists in the local directory, it is
483 automatically used for this purpose (also see below).
484
485 --build-package=
486 Similar to --package=, but configures packages to install only
487 in the first phase of the build, into the development image.
488 This option should be used to list packages containing header
489 files, compilers, build systems, linkers and other build tools
490 the mkosi.build script requires to operate. Note that packages
491 listed here are only included in the image created during the
492 first phase of the build, and are absent in the final image.
493 use --package= to list packages that shall be included in both.
494 Packages are appended to the list. Packages prefixed with “!”
495 are removed from the list. “!*” removes all packages from the
496 list.
497
498 --skip-final-phase=
499 Causes the (second) final image build stage to be skipped. This
500 is useful in combination with a build script, for when you care
501 about the artifacts that were created locally in $BUILDDIR, but
502 ultimately plan to discard the final image.
503
504 --prepare-script=
505 Takes a path to an executable that is invoked inside the image
506 right after installing the software packages. It is the last
507 step before the image is cached (if incremental mode is en‐
508 abled). This script is invoked inside a systemd-nspawn contain‐
509 er environment, and thus does not have access to host resources.
510 If this option is not used, but an executable script mkosi.pre‐
511 pare is found in the local directory, it is automatically used
512 for this purpose (also see below).
513
514 --postinst-script=
515 Takes a path to an executable that is invoked inside the final
516 image right after copying in the build artifacts generated in
517 the first phase of the build. This script is invoked inside a
518 systemd-nspawn container environment, and thus does not have ac‐
519 cess to host resources. If this option is not used, but an exe‐
520 cutable mkosi.postinst is found in the local directory, it is
521 automatically used for this purpose (also see below).
522
523 --finalize-script=
524 Takes a path to an executable that is invoked outside the final
525 image right after copying in the build artifacts generated in
526 the first phase of the build, and after having executed the
527 mkosi.postinst script (see above). This script is invoked di‐
528 rectly in the host environment, and hence has full access to the
529 host’s resources. If this option is not used, but an executable
530 mkosi.finalize is found in the local directory, it is automati‐
531 cally used for this purpose (also see below).
532
533 --source-file-transfer=
534 Configures how the source file tree (as configured with --build-
535 sources=) is transferred into the container image during the
536 first phase of the build. Takes one of copy-all (to copy all
537 files from the source tree), copy-git-cached (to copy only those
538 files git-ls-files --cached lists), copy-git-others (to copy on‐
539 ly those files git-ls-files --others lists), mount to bind mount
540 the source tree directly. Defaults to copy-git-cached if a git
541 source tree is detected, otherwise copy-all. When you specify
542 copy-git-more, it is the same as copy-git-cached, except it also
543 includes the .git/ directory.
544
545 --source-file-transfer-final=
546 Same as --source-file-transfer but for the final image instead
547 of the build image. Takes the same values as --source-file-
548 transfer except mount. By default, sources are not copied into
549 the final image.
550
551 --with-network
552 Enables network connectivity while the build script mkosi.build
553 is invoked. By default, the build script runs with networking
554 turned off. The $WITH_NETWORK environment variable is passed to
555 the mkosi.build build script indicating whether the build is
556 done with or without this option. If specified as --with-net‐
557 work=never the package manager is instructed not to contact the
558 network for updating package data. This provides a minimal lev‐
559 el of reproducibility, as long as the package data cache is al‐
560 ready fully populated.
561
562 --settings=
563 Specifies a .nspawn settings file for systemd-nspawn to use in
564 the boot and shell verbs, and to place next to the generated im‐
565 age file. This is useful to configure the systemd-nspawn envi‐
566 ronment when the image is run. If this setting is not used but
567 an mkosi.nspawn file found in the local directory it is automat‐
568 ically used for this purpose (also see below).
569
570 --root-size=
571 Takes a size in bytes for the root file system. The specified
572 numeric value may be suffixed with K, M, G to indicate kilo-,
573 mega- and gigabytes (all to the base of 1024). This applies to
574 output formats gpt_ext4, gpt_xfs, gpt_btrfs. Defaults to 1G,
575 except for gpt_xfs where it defaults to 1.3G.
576
577 --esp-size=
578 Similar, and configures the size of the UEFI System Partition
579 (ESP). This is only relevant if the --bootable option is used
580 to generate a bootable image. Defaults to 256M.
581
582 --swap-size=
583 Similar, and configures the size of a swap partition on the im‐
584 age. If omitted no swap partition is created.
585
586 --home-size=
587 Similar, and configures the size of the /home partition. If
588 omitted no separate /home partition is created.
589
590 --srv-size=
591 Similar, and configures the size of the /srv partition. If
592 omitted no separate /srv partition is created.
593
594 --checksum
595 Generate a SHA256SUMS file of all generated artifacts after the
596 build is complete.
597
598 --sign Sign the generated SHA256SUMS using gpg after completion.
599
600 --key= Select the gpg key to use for signing SHA256SUMS. This key is
601 required to exist in the gpg keyring already.
602
603 --bmap Generate a bmap file for usage with bmaptool from the generated
604 image file.
605
606 --password=
607 Set the password of the root user. By default the root account
608 is locked. If this option is not used but a file mkosi.rootpw
609 exists in the local directory the root password is automatically
610 read from it.
611
612 --password-is-hashed
613 Indicate that the password supplied for the root user has al‐
614 ready been hashed, so that the string supplied with --password
615 or mkosi.rootpw will be written to /etc/shadow literally.
616
617 --autologin
618 Enable autologin for the root user on pts/0 (nspawn), tty1 (QE‐
619 MU) and ttyS0 (QEMU with –qemu-headless) by patching
620 /etc/pam.d/login.
621
622 --extra-search-paths=
623 List of colon-separated paths to look for tools in, before using
624 the regular $PATH search path.
625
626 --directory=, -C
627 Takes a path to a directory. mkosi switches to this directory
628 before doing anything. Note that the various mkosi.* files are
629 searched for only after changing to this directory, hence using
630 this option is an effective way to build a project located in a
631 specific directory.
632
633 --default=
634 Loads additional settings from the specified settings file.
635 Most command line options may also be configured in a settings
636 file. See the table below to see which command line options
637 match which settings file option. If this option is not used,
638 but a file mkosi.default is found in the local directory it is
639 automatically used for this purpose. If a setting is configured
640 both on the command line and in the settings file, the command
641 line generally wins, except for options taking lists in which
642 case both lists are combined.
643
644 --all, -a
645 Iterate through all files mkosi.* in the mkosi.files/ subdirec‐
646 tory, and build each as if --default=mkosi.files/mkosi.... was
647 invoked. This is a quick way to build a large number of images
648 in one go. Any additional specified command line arguments
649 override the relevant options in all files processed this way.
650
651 --all-directory=
652 If specified, overrides the directory the --all logic described
653 above looks for settings files in. If unspecified, defaults to
654 mkosi.files/ in the current working directory (see above).
655
656 --version
657 Show package version.
658
659 --help, -h
660 Show brief usage information.
661
662 --qemu-headless=
663 When used with the build verb, this option adds console=ttyS0 to
664 the image’s kernel command line and sets the terminal type of
665 the serial console in the image to the terminal type of the host
666 (more specifically, the value of the TERM environment variable
667 passed to mkosi). This makes sure that all terminal features
668 such as colors and shortcuts still work as expected when con‐
669 necting to the qemu VM over the serial console (for example via
670 -nographic).
671
672 When used with the qemu verb, this option adds the -nographic option to
673 qemu’s command line so qemu starts a headless vm and connects to its
674 serial console from the current terminal instead of launching the VM in
675 a separate window.
676
677 --network-veth
678 When used with the boot or qemu verbs, this option creates a
679 virtual ethernet link between the host and the container/VM.
680 The host interface is automatically picked up by systemd-net‐
681 workd as documented in systemd-nspawn’s man page:
682 https://www.freedesktop.org/software/systemd/man/systemd-
683 nspawn.html#-n
684
685 --ephemeral
686 When used with the shell, boot or qemu verbs, this option runs
687 the specified verb on a temporary snapshot of the output image
688 that is removed immediately when the container terminates. Tak‐
689 ing the temporary snapshot is more efficient on file systems
690 that support subvolume snapshots or `reflinks' natively (“btrfs”
691 or new “xfs”) than on more traditional file systems that do not
692 (“ext4”).
693
694 --ssh If specified, installs and enables sshd in the final image and
695 generates a SSH keypair and adds the public key to root’s autho‐
696 rized keys in the final image. The private key is stored in
697 mkosi’s output directory. When building with this option and
698 running the image using mkosi boot or mkosi qemu, the mkosi ssh
699 command can be used to connect to the container/VM via SSH.
700
701 Command Line Parameters and their Settings File Counterparts
702 Most command line parameters may also be placed in an mkosi.default
703 settings file (or any other file --default= is used on). The following
704 table shows which command lines parameters correspond with which set‐
705 tings file options.
706
707 Command Line Param‐ mkosi.default sec‐ mkosi.default set‐
708 eter tion ting
709 ────────────────────────────────────────────────────────────────
710 --distribution=, -d [Distribution] Distribution=
711 --release=, -r [Distribution] Release=
712 --repositories= [Distribution] Repositories=
713 --mirror=, -m [Distribution] Mirror=
714 --architecture= [Distribution] Architecture=
715 --format=, -t [Output] Format=
716 --output=, -o [Output] Output=
717 --output-dir=, -O [Output] OutputDirectory=
718 --force, -f [Output] Force=
719 --bootable, -b [Output] Bootable=
720 --boot-protocols= [Output] BootProtocols=
721 --gpt-first-lba= [Output] GPTFirstLBA=
722 --kernel-command- [Output] KernelCommandLine=
723 line=
724 --secure-boot [Output] SecureBoot=
725 --secure-boot-key= [Output] SecureBootKey=
726 --secure-boot-cer‐ [Output] SecureBootCertifi‐
727 tificate= cate=
728 --read-only [Output] ReadOnly=
729 --encrypt= [Output] Encrypt=
730 --verity= [Output] Verity=
731 --compress= [Output] Compress=
732 --mksquashfs= [Output] Mksquashfs=
733 --xz [Output] XZ=
734 --qcow2 [Output] QCow2=
735 --no-chown [Output] NoChown=
736 --tar-strip-selin‐ [Output] TarStripSELinuxCon‐
737 ux-context text=
738 --hostname= [Output] Hostname=
739 --without-unified- [Output] WithUnifiedKerne‐
740 kernel-images lImages=
741 --hostonly-initrd [Output] HostonlyInitrd=
742 --package= [Packages] Packages=
743 --with-docs [Packages] WithDocs=
744 --without-tests, -T [Packages] WithTests=
745 --cache= [Packages] Cache=
746 --extra-tree= [Packages] ExtraTrees=
747 --skeleton-tree= [Packages] SkeletonTrees=
748 --build-script= [Packages] BuildScript=
749 --build-sources= [Packages] BuildSources=
750 --source-file- [Packages] SourceFileTransfer=
751 transfer=
752 --source-file- [Packages] SourceFileTransfer‐
753 transfer-final= Final=
754 --build-directory= [Packages] BuildDirectory=
755 --include-directo‐ [Packages] IncludeDirectory=
756 ry=
757 --install-directo‐ [Packages] InstallDirectory=
758 ry=
759 --build-packages= [Packages] BuildPackages=
760 --skip-final-phase= [Packages] SkipFinalPhase=
761 --postinst-script= [Packages] PostInstallation‐
762 Script=
763 --finalize-script= [Packages] FinalizeScript=
764 --with-network [Packages] WithNetwork=
765 --settings= [Packages] NSpawnSettings=
766
767 --root-size= [Partitions] RootSize=
768 --esp-size= [Partitions] ESPSize=
769 --swap-size= [Partitions] SwapSize=
770 --home-size= [Partitions] HomeSize=
771 --srv-size= [Partitions] SrvSize=
772 --checksum [Validation] CheckSum=
773 --sign [Validation] Sign=
774 --key= [Validation] Key=
775 --bmap [Validation] BMap=
776 --password= [Validation] Password=
777 --password-is- [Validation] PasswordIsHashed=
778 hashed
779 --autologin [Validation] Autologin=
780 --extra-search- [Host] ExtraSearchPaths=
781 paths=
782 --qemu-headless [Host] QemuHeadless=
783 --network-veth [Host] NetworkVeth=
784 --ephemeral [Host] Ephemeral=
785 --ssh [Host] Ssh=
786
787 Command line options that take no argument are not suffixed with a = in
788 their long version in the table above. In the mkosi.default file they
789 are modeled as boolean option that take either 1, yes, true for en‐
790 abling, and 0, no, false for disabling.
791
792 Supported distributions
793 Images may be created containing installations of the following OSes.
794
795 · Fedora
796
797 · Debian
798
799 · Ubuntu
800
801 · Arch Linux
802
803 · openSUSE
804
805 · Mageia
806
807 · CentOS
808
809 · Clear Linux
810
811 · Photon
812
813 · OpenMandriva
814
815 In theory, any distribution may be used on the host for building images
816 containing any other distribution, as long as the necessary tools are
817 available. Specifically, any distribution that packages debootstrap
818 may be used to build Debian or Ubuntu images. Any distribution that
819 packages dnf may be used to build Fedora, Mageia or OpenMandriva im‐
820 ages. Any distro that packages pacstrap may be used to build Arch Lin‐
821 ux images. Any distribution that packages zypper may be used to build
822 openSUSE images. Any distribution that packages yum (or the newer re‐
823 placement dnf) may be used to build CentOS images.
824
825 Currently, Fedora packages all relevant tools as of Fedora 28.
826
827 Compatibility
828 Generated images are legacy-free. This means only GPT disk labels (and
829 no MBR disk labels) are supported, and only systemd based images may be
830 generated.
831
832 All generated GPT disk images may be booted in a local container di‐
833 rectly with:
834
835 systemd-nspawn -bi image.raw
836
837 Additionally, bootable GPT disk images (as created with the --bootable
838 flag) work when booted directly by EFI and BIOS systems, for example in
839 KVM via:
840
841 qemu-kvm -m 512 -smp 2 -bios /usr/share/edk2/ovmf/OVMF_CODE.fd -drive format=raw,file=image.raw
842
843 EFI bootable GPT images are larger than plain GPT images, as they addi‐
844 tionally carry an EFI system partition containing a boot loader, as
845 well as a kernel, kernel modules, udev and more.
846
847 All directory or btrfs subvolume images may be booted directly with:
848
849 systemd-nspawn -bD image
850
852 To make it easy to build images for development versions of your
853 projects, mkosi can read configuration data from the local directory,
854 under the assumption that it is invoked from a source tree. Specifi‐
855 cally, the following files are used if they exist in the local directo‐
856 ry:
857
858 · mkosi.default may be used to configure mkosi’s image building
859 process. For example, you may configure the distribution to use (fe‐
860 dora, ubuntu, debian, arch, opensuse, mageia, openmandriva) for the
861 image, or additional distribution packages to install. Note that all
862 options encoded in this configuration file may also be set on the
863 command line, and this file is hence little more than a way to make
864 sure simply typing mkosi without further parameters in your source
865 tree is enough to get the right image of your choice set up. Addi‐
866 tionally if a mkosi.default.d directory exists, each file in it is
867 loaded in the same manner adding/overriding the values specified in
868 mkosi.default. If mkosi.default.d contains a directory named after
869 the distribution being built, each file in that directory is also
870 processed. The file format is inspired by Windows.ini files and sup‐
871 ports multi-line assignments: any line with initial whitespace is
872 considered a continuation line of the line before. Command-line ar‐
873 guments, as shown in the help description, have to be included in a
874 configuration block (e.g. “[Packages]”) corresponding to the argument
875 group (e.g. “Packages”), and the argument gets converted as follows:
876 “–with-network” becomes “WithNetwork=yes”. For further details see
877 the table above.
878
879 · mkosi.extra/ or mkosi.extra.tar may be respectively a directory or
880 archive. If any exist all files contained in it are copied over the
881 directory tree of the image after the OS was installed. This may be
882 used to add in additional files to an image, on top of what the dis‐
883 tribution includes in its packages. When using a directory file own‐
884 ership is not preserved: all files copied will be owned by root. To
885 preserve ownership use a tar archive.
886
887 · mkosi.skeleton/ or mkosi.skeleton.tar may be respectively a directory
888 or archive, and they work in the same way as mkosi.extra/mkosi.skele‐
889 ton.tar. However the files are copied before anything else so to
890 have a skeleton tree for the OS. This allows to change the package
891 manager and create files that need to be there before anything is in‐
892 stalled. When using a directory file ownership is not preserved: all
893 files copied will be owned by root. To preserve ownership use a tar
894 archive.
895
896 · mkosi.build may be an executable script. If it exists the image will
897 be built twice: the first iteration will be the development image,
898 the second iteration will be the final image. The development image
899 is used to build the project in the current working directory (the
900 source tree). For that the whole directory is copied into the image,
901 along with the mkosi.build build script. The script is then invoked
902 inside the image (via systemd-nspawn), with $SRCDIR pointing to the
903 source tree. $DESTDIR points to a directory where the script should
904 place any files generated it would like to end up in the final image.
905 Note that make/automake/meson based build systems generally honor
906 $DESTDIR, thus making it very natural to build source trees from the
907 build script. After the development image was built and the build
908 script ran inside of it, it is removed again. After that the final
909 image is built, without any source tree or build script copied in.
910 However, this time the contents of $DESTDIR are added into the image.
911
912 When the source tree is copied into the build image, all files are
913 copied, except for mkosi.builddir/, mkosi.cache/ and mkosi.output/.
914 That said, .gitignore is respected if the source tree is a git check‐
915 out. If multiple different images shall be built from the same
916 source tree it’s essential to exclude their output files from this
917 copy operation, as otherwise a version of an image built earlier
918 might be included in a later build, which is usually not intended.
919 An alternative to excluding these built images via .gitignore entries
920 is making use of the mkosi.output/ directory (see below), which is an
921 easy way to exclude all build artifacts.
922
923 The MKOSI_DEFAULT environment variable will be set inside of this
924 script so that you know which mkosi.default (if any) was passed in.
925
926 · mkosi.prepare may be an executable script. If it exists it is in‐
927 voked directly after the software packages are installed, from within
928 the image context. It is once called for the development image (if
929 this is enabled, see above) with the “build” command line parameter,
930 right before copying the extra tree. It is called a second time for
931 the final image with the “final” command line parameter. This script
932 has network access and may be used to install packages from other
933 sources than the distro’s package manager (e.g. pip, npm, ...), after
934 all software packages are installed but before the image is cached
935 (if incremental mode is enabled). This script is executed within
936 $SRCDIR. In contrast to a general purpose installation, it is safe
937 to install packages to the system (pip install, npm install -g) in‐
938 stead of in $SRCDIR itself because the build image is only used for a
939 single project and can easily be thrown away and rebuilt so there’s
940 no risk of conflicting dependencies and no risk of polluting the host
941 system.
942
943 · mkosi.postinst may be an executable script. If it exists it is in‐
944 voked as the penultimate step of preparing an image, from within the
945 image context. It is once called for the development image (if this
946 is enabled, see above) with the “build” command line parameter, right
947 before invoking the build script. It is called a second time for the
948 final image with the “final” command line parameter, right before the
949 image is considered complete. This script may be used to alter the
950 images without any restrictions, after all software packages and
951 built sources have been installed. Note that this script is executed
952 directly in the image context with the final root directory in place,
953 without any $SRCDIR/$DESTDIR setup.
954
955 · mkosi.finalize may be an executable script. If it exists it is in‐
956 voked as last step of preparing an image, from the host system. It
957 is once called for the development image (if this is enabled, see
958 above) with the “build” command line parameter, as the last step be‐
959 fore invoking the build script, after the mkosi.postinst script is
960 invoked. It is called the second time with the “final” command line
961 parameter as the last step before the image is considered complete.
962 The environment variable $BUILDROOT points to the root directory of
963 the installation image. Additional verbs may be added in the future,
964 the script should be prepared for that. This script may be used to
965 alter the images without any restrictions, after all software pack‐
966 ages and built sources have been installed. This script is more
967 flexible than mkosi.postinst in two regards: it has access to the
968 host file system so it’s easier to copy in additional files or to
969 modify the image based on external configuration, and the script is
970 run in the host, so it can be used even without emulation even if the
971 image has a foreign architecture.
972
973 · mkosi.mksquashfs-tool may be an executable script. If it exists is
974 is called instead of mksquashfs.
975
976 · mkosi.nspawn may be an nspawn settings file. If this exists it will
977 be copied into the same place as the output image file. This is use‐
978 ful since nspawn looks for settings files next to image files it
979 boots, for additional container runtime settings.
980
981 · mkosi.cache/ may be a directory. If so, it is automatically used as
982 package download cache, in order to speed repeated runs of the tool.
983
984 · mkosi.builddir/ may be a directory. If so, it is automatically used
985 as out-of-tree build directory, if the build commands in the
986 mkosi.build script support it. Specifically, this directory will be
987 mounted into the build container, and the $BUILDDIR environment vari‐
988 able will be set to it when the build script is invoked. The build
989 script may then use this directory as build directory, for automake-
990 style or ninja-style out-of-tree builds. This speeds up builds con‐
991 siderably, in particular when mkosi is used in incremental mode (-i):
992 not only the disk images but also the build tree is reused between
993 subsequent invocations. Note that if this directory does not exist
994 the $BUILDDIR environment variable is not set, and it is up to build
995 script to decide whether to do in in-tree or an out-of-tree build,
996 and which build directory to use.
997
998 · mkosi.includedir/ may be a directory. If so, it is automatically
999 used as out-of-tree include directory. Specifically, this directory
1000 will be mounted into the build container at /usr/include when build‐
1001 ing the build image and when running the build script. After build‐
1002 ing the (cached) build image, this directory will contain all the
1003 files installed to /usr/include. Language servers or other tools can
1004 use these files to provide a better editing experience for developers
1005 working on a project.
1006
1007 · mkosi.installdir/ may be a directory. If so, it is automatically
1008 used as the install directory. Specifically, this directory will be
1009 mounted into the container at /root/dest when running the build
1010 script. After running the build script, the contents of this direc‐
1011 tory are installed into the final image. This is useful to cache the
1012 install step of the build. If used, subsequent builds will only have
1013 to reinstall files that have changed since the previous build.
1014
1015 · mkosi.rootpw may be a file containing the password or hashed password
1016 (if --password-is-hashed is set) for the root user of the image to
1017 set. The password may optionally be followed by a newline character
1018 which is implicitly removed. The file must have an access mode of
1019 0600 or less. If this file does not exist the distribution’s default
1020 root password is set (which usually means access to the root user is
1021 blocked).
1022
1023 · mkosi.passphrase may be a passphrase file to use when LUKS encryption
1024 is selected. It should contain the passphrase literally, and not end
1025 in a newline character (i.e. in the same format as cryptsetup and
1026 /etc/crypttab expect the passphrase files). The file must have an
1027 access mode of 0600 or less. If this file does not exist and encryp‐
1028 tion is requested the user is queried instead.
1029
1030 · mkosi.secure-boot.crt and mkosi.secure-boot.key may contain an X.509
1031 certificate and PEM private key to use when UEFI SecureBoot support
1032 is enabled. All EFI binaries included in the image’s ESP are signed
1033 with this key, as a late step in the build process.
1034
1035 · mkosi.output/ may be a directory. If it exists, and the image output
1036 path is not configured (i.e. no --output= setting specified), or con‐
1037 figured to a filename (i.e. a path containing no / character) all
1038 build artifacts (that is: the image itself, the root hash file in
1039 case Verity is used, the checksum and its signature if that’s en‐
1040 abled, and the nspawn settings file if there is any) are placed in
1041 this directory. Note that this directory is not used if the image
1042 output path contains at least one slash, and has no effect in that
1043 case. This setting is particularly useful if multiple different im‐
1044 ages shall be built from the same working directory, as otherwise the
1045 build result of a preceding run might be copied into a build image as
1046 part of the source tree (see above).
1047
1048 All these files are optional.
1049
1050 Note that the location of all these files may also be configured during
1051 invocation via command line switches, and as settings in mkosi.default,
1052 in case the default settings are not acceptable for a project.
1053
1055 If no build script mkosi.build (see above) is used the build consists
1056 of a single phase only: the final image is generated as the combination
1057 of mkosi.skeleton/ (see above), the unpacked distribution packages and
1058 mkosi.extra/.
1059
1060 If a build script mkosi.build is used the build consists of two phases:
1061 in the the first development phase an image that includes necessary
1062 build tools (i.e. the combination of Packages= and BuildPackages= is
1063 installed) is generated (i.e. the combination of mkosi.skeleton/ and
1064 unpacked distribution packages). Into this image the source tree is
1065 copied and mkosi.build executed. The artifacts the mkosi.build gener‐
1066 ates are saved. Then, the second final phase starts: an image that ex‐
1067 cludes the build tools (i.e. only Packages= is installed, BuildPack‐
1068 ages= is not) is generated. This time the build artifacts saved from
1069 the first phase are copied in, and mkosi.extra copied on top, thus gen‐
1070 erating the final image.
1071
1072 The two-phased approach ensures that source tree is executed in a clean
1073 and comprehensive environment, while at the same the final image re‐
1074 mains minimal and contains only those packages necessary at runtime,
1075 but avoiding those necessary at build-time.
1076
1077 Note that only the package cache mkosi.cache/ (see below) is shared be‐
1078 tween the two phases. The distribution package manager is executed ex‐
1079 actly once in each phase, always starting from a directory tree that is
1080 populated with mkosi.skeleton but nothing else.
1081
1083 mkosi supports three different caches for speeding up repetitive re-
1084 building of images. Specifically:
1085
1086 1. The package cache of the distribution package manager may be cached
1087 between builds. This is configured with the --cache= option or the
1088 mkosi.cache/ directory. This form of caching relies on the distri‐
1089 bution’s package manager, and caches distribution packages (RPM,
1090 DEB, ...) after they are downloaded, but before they are unpacked.
1091
1092 2. If an mkosi.build script is used, by enabling incremental build mode
1093 with --incremental (see above) a cached copy of the development and
1094 final images can be made immediately before the build sources are
1095 copied in (for the development image) or the artifacts generated by
1096 mkosi.build are copied in (in case of the final image). This form
1097 of caching allows bypassing the time-consuming package unpacking
1098 step of the distribution package managers, but is only effective if
1099 the list of packages to use remains stable, but the build sources
1100 and its scripts change regularly. Note that this cache requires
1101 manual flushing: whenever the package list is modified the cached
1102 images need to be explicitly removed before the next re-build, using
1103 the -f switch.
1104
1105 3. Finally, between multiple builds the build artifact directory may be
1106 shared, using the mkosi.builddir/ directory. This directory allows
1107 build systems such as Meson to reuse already compiled sources from a
1108 previous built, thus speeding up the build process of the
1109 mkosi.build build script.
1110
1111 The package cache (i.e. the first item above) is unconditionally use‐
1112 ful. The latter two caches only apply to uses of mkosi with a source
1113 tree and build script. When all three are enabled together turn-around
1114 times for complete image builds are minimal, as only changed source
1115 files need to be recompiled: an OS image rebuilt will be almost as
1116 quick to build the source tree only.
1117
1119 The build script mkosi.build receives the following environment vari‐
1120 ables:
1121
1122 · $SRCDIR contains the path to the sources to build.
1123
1124 · $DESTDIR is a directory into which any artifacts generated by the
1125 build script shall be placed.
1126
1127 · $BUILDDIR is only defined if mkosi.builddir and points to the build
1128 directory to use. This is useful for all build systems that support
1129 out-of-tree builds to reuse already built artifacts from previous
1130 runs.
1131
1132 · $WITH_DOCS is either 0 or 1 depending on whether a build without or
1133 with installed documentation was requested (see --with-docs above).
1134 The build script should suppress installation of any package documen‐
1135 tation to $DESTDIR in case $WITH_DOCS is set to 0.
1136
1137 · $WITH_TESTS is either 0or 1 depending on whether a build without or
1138 with running the test suite was requested (see --without-tests
1139 above). The build script should avoid running any unit or integra‐
1140 tion tests in case $WITH_TESTS is 0.
1141
1142 · $WITH_NETWORK is either 0or 1 depending on whether a build without or
1143 with networking is being executed (see --with-network above). The
1144 build script should avoid any network communication in case
1145 $WITH_NETWORK is 0.
1146
1148 Create and run a raw GPT image with ext4, as image.raw:
1149
1150 # mkosi
1151 # systemd-nspawn -b -i image.raw
1152
1153 Create and run a bootable btrfs GPT image, as foobar.raw:
1154
1155 # mkosi -t gpt_btrfs --bootable -o foobar.raw
1156 # systemd-nspawn -b -i foobar.raw
1157 # qemu-kvm -m 512 -smp 2 -bios /usr/share/edk2/ovmf/OVMF_CODE.fd -drive format=raw,file=foobar.raw
1158
1159 Create and run a Fedora image into a plain directory:
1160
1161 # mkosi -d fedora -t directory -o quux
1162 # systemd-nspawn -b -D quux
1163
1164 Create a compressed image image.raw.xz and add a checksum file, and in‐
1165 stall SSH into it:
1166
1167 # mkosi -d fedora -t gpt_squashfs --checksum --xz --package=openssh-clients
1168
1169 Inside the source directory of an automake-based project, configure
1170 mkosi so that simply invoking mkosi without any parameters builds an OS
1171 image containing a built version of the project in its current state:
1172
1173 # cat > mkosi.default <<EOF
1174 [Distribution]
1175 Distribution=fedora
1176 Release=24
1177
1178 [Output]
1179 Format=gpt_btrfs
1180 Bootable=yes
1181
1182 [Packages]
1183 Packages=openssh-clients httpd
1184 BuildPackages=make gcc libcurl-devel
1185 EOF
1186 # cat > mkosi.build <<EOF
1187 #!/bin/sh
1188 cd $SRCDIR
1189 ./autogen.sh
1190 ./configure --prefix=/usr
1191 make -j `nproc`
1192 make install
1193 EOF
1194 # chmod +x mkosi.build
1195 # mkosi
1196 # systemd-nspawn -bi image.raw
1197
1198 To create a Fedora image with hostname:
1199
1200 # mkosi -d fedora --hostname image
1201
1202 Also you could set hostname in configuration file:
1203
1204 # cat mkosi.default
1205 ...
1206 [Output]
1207 Hostname=image
1208 ...
1209
1211 mkosi is packaged for various distributions: Debian, Ubuntu, Arch (in
1212 AUR), Fedora, OpenMandriva. It is usually easiest to use the distribu‐
1213 tion package.
1214
1215 The current version requires systemd 233 (or actually, systemd-nspawn
1216 of it).
1217
1218 When not using distribution packages make sure to install the necessary
1219 dependencies. For example, on Fedora you need:
1220
1221 dnf install arch-install-scripts btrfs-progs debootstrap dosfstools edk2-ovmf e2fsprogs squashfs-tools gnupg python3 tar veritysetup xfsprogs xz zypper sbsigntools
1222
1223 On Debian/Ubuntu it might be necessary to install the ubuntu-keyring,
1224 ubuntu-archive-keyring and/or debian-archive-keyring packages explicit‐
1225 ly, in addition to debootstrap, depending on what kind of distribution
1226 images you want to build. debootstrap on Debian only pulls in the De‐
1227 bian keyring on its own, and the version on Ubuntu only the one from
1228 Ubuntu.
1229
1230 Note that the minimum required Python version is 3.6.
1231
1233 · Primary mkosi git repository on GitHub (https://github.com/sys‐
1234 temd/mkosi/)
1235
1236 · mkosi — A Tool for Generating OS Images (http://0point‐
1237 er.net/blog/mkosi-a-tool-for-generating-os-images.html) introductory
1238 blog post by Lennart Poettering
1239
1240 · The mkosi OS generation tool (https://lwn.net/Articles/726655/) story
1241 on LWN
1242
1244 systemd-nspawn(1), dnf(8), debootstrap(8)
1245
1247 The mkosi Authors.
1248
1249
1250
1251 2016- mkosi(1)