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