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 mkosi [options...] ssh
22 mkosi [options...] serve
24 mkosi [options...] bump
26 mkosi [options...] genkey
28 mkosi [options...] help
30
32 mkosi is a tool for easily building customized OS images. It’s a fancy
33 wrapper around dnf --installroot, debootstrap, pacstrap and zypper that
34 may generate disk images with a number of bells and whistles.
35 Command Line Verbs
37 The following command line verbs are known:
38 build This builds the image, based on the settings passed in on the
40 command line or read from a mkosi.default file. This verb is
41 the default if no verb is explicitly specified. This command
42 must be executed as root. Any arguments passed after build are
43 passed as arguments to the build script (if there is one).
44 clean Remove build artifacts generated on a previous build. If com‐
46 bined with -f, also removes incremental build cache images. If
47 -f is specified twice, also removes any package cache.
48 summary
50 Outputs a human-readable summary of all options used for build‐
51 ing an image. This will parse the command line and mkosi.de‐
52 fault file as it would do on build, but only output what it is
53 configured for and not actually build anything.`
54 shell This builds the image if it is not built yet, and then invokes
56 systemd-nspawn to acquire an interactive shell prompt in it. If
57 this verb is used an optional command line may be specified
58 which is then invoked in place of the shell in the container.
59 Combine this with -f in order to rebuild the image uncondition‐
60 ally before acquiring the shell, see below. This command must
61 be executed as root.
62 boot Similar to shell but boots the image up using systemd-nspawn.
64 If this verb is used an optional command line may be specified
65 which is passed as “kernel command line” to the init system in
66 the image.
67 qemu Similar to boot but uses qemu to boot up the image, i.e. instead
69 of container virtualization VM virtualization is used. This
70 verb is only supported on images that contain a boot loader,
71 i.e. those built with Bootable=yes (see below). This command
72 must be executed as root unless the image already exists and -f
73 is not specified.
74 ssh When the image is built with the Ssh=yes option, this command
76 connects to a booted (boot, qemu verbs) container/VM via SSH.
77 Make sure to run mkosi ssh with the same config as mkosi build
78 was run with so that it has the necessary information available
79 to connect to the running container/VM via SSH.
80 serve This builds the image if it is not built yet, and then serves
82 the output directory (i.e. usually mkosi.output/, see below) via
83 a small embedded HTTP server, listening on port 8081. Combine
84 with -f in order to rebuild the image unconditionally before
85 serving it. This command is useful for testing network based
86 acquisition of OS images, for example via machinectl pull-raw
87 ... and machinectl pull-tar ....
88 bump Determines the current image version string (as configured with
90 ImageVersion=/--image-version=), increases its last dot-separat‐
91 ed component by one and writes the resulting version string to
92 mkosi.version. This is useful for implementing a simple ver‐
93 sioning scheme: each time this verb is called the version is
94 bumped in preparation for the subsequent build. Note that --au‐
95 to-bump/-B may be used to automatically bump the version after
96 each successful build.
97 genkey Generate a pair of SecureBoot keys for usage with the Secure‐
99 BootKey=/--secure-boot-key= and SecureBootCertificate=/--secure-
100 boot-certificate= options.
101 help This verb is equivalent to the --help switch documented below:
103 it shows a brief usage explanation.
104 Execution flow
106 Execution flow for mkosi build. Columns represent the execution con‐
107 text. Default values/calls are shown in parentheses. When building
108 with --incremental mkosi creates a cache of the distribution installa‐
109 tion for both images if not already existing and replaces the distribu‐
110 tion installation in consecutive runs with data from the cached one.
111 HOST . BUILD . FINAL
113 . IMAGE . IMAGE
114 . .
115 start . .
116 | . .
117 v . .
118 build script? -------exists-----> copy .
119 | . skeleton trees .
120 | . (mkosi.skeleton/) .
121 none . | .
122 | . v .
123 v . install .
124 skip . distribution, .
125 build image . packages and .
126 | . build packages, .
127 | . run .
128 | . prepare script .
129 | . (mkosi.prepare build) .
130 | . or if incremental .
131 | . use cached build image .
132 | . | .
133 | . v .
134 | . copy .
135 | . build sources .
136 | . (./) .
137 | . | .
138 | . v .
139 | . copy .
140 | . extra trees .
141 | . (mkosi.extra/) .
142 | . | .
143 | . v .
144 | . run .
145 | . postinstall script .
146 | . (mkosi.postinst build) .
147 | . | .
148 | .-------------------------' .
149 | | . .
150 | v . .
151 | run . .
152 | finalize script . .
153 |(mkosi.finalize build). .
154 | | . .
155 | '-------------------------. .
156 | . | .
157 | . v .
158 | . run .
159 | . build script .
160 | . (mkosi.build) .
161 | . | .
162 '-----------------------------------+------------------------.
163 . . |
164 . . v
165 . . copy
166 . . skeleton trees
167 . . (mkosi.skeleton/)
168 . . |
169 . . v
170 . . install
171 . . distribution
172 . . and packages,
173 . . run
174 . . prepare script
175 . . (mkosi.prepare final)
176 . . or if incremental
177 . . use cached final image
178 . . |
179 . . v
180 . . copy
181 . . build results
182 . . |
183 . . v
184 . . copy
185 . . extra trees
186 . . (mkosi.extra/)
187 . . |
188 . . v
189 . . run
190 . . postinstall script
191 . . (mkosi.postinst final)
192 . . |
193 . . v
194 . . |
195 . . perform cleanup
196 . . (remove files, packages,
197 . . package metadata)
198 . . |
199 .--------------------------------------------------'
200 | . .
201 v . .
202 run . .
203 finalize script . .
204 (mkosi.finalize final) . .
205 | . .
206 .---------' . .
207 | . .
208 v . .
209 end . .
210 . .
211 HOST . BUILD . FINAL
212 . IMAGE . IMAGE
213 . .
214 Supported output formats
216 The following output formats are supported:
217 • Raw GPT disk image, with ext4 as root (gpt_ext4)
219 • Raw GPT disk image, with xfs as root (gpt_xfs)
221 • Raw GPT disk image, with btrfs as root (gpt_btrfs)
223 • Raw GPT disk image, with squashfs as read-only root (gpt_squashfs)
225 • Plain squashfs image, without partition table, as read-only root
227 (plain_squashfs)
228 • Plain directory, containing the OS tree (directory)
230 • btrfs subvolume, with separate subvolumes for /var, /home, /srv,
232 /var/tmp (subvolume)
233 • Tar archive (tar)
235 • CPIO archive (cpio) in the format appropriate for a kernel initrd
237 When a GPT disk image is created, the following additional options are
239 available:
240 • A swap partition may be added in
242 • The image may be made bootable on EFI and BIOS systems
244 • Separate partitions for /srv and /home may be added in
246 • The root, /srv and /home partitions may optionally be encrypted with
248 LUKS.
249 • A dm-verity partition may be added in that adds runtime integrity da‐
251 ta for the root partition
252 Configuration Settings
254 The following settings can be set through configuration files (the syn‐
255 tax with SomeSetting=value) and on the command line (the syntax with
256 --some-setting=value). For some command line parameters, a single-let‐
257 ter shortcut is also allowed. In the configuration files, the setting
258 must be in the appropriate section, so the settings are grouped by sec‐
259 tion below.
260 Command line options that take no argument are shown without “=” in
262 their long version. In the config files, they should be specified with
263 a boolean argument: either “1”, “yes”, or “true” to enable, or “0”,
264 “no”, “false” to disable.
265 [Distribution] Section
267 Distribution=, --distribution=, -d
268 The distribution to install in the image. Takes one of the fol‐
269 lowing arguments: fedora, debian, ubuntu, arch, opensuse,
270 mageia, centos, centos_epel, clear, photon, openmandriva, rocky,
271 rocky_epel, alma, alma_epel. If not specified, defaults to the
272 distribution of the host.
273 Release=, --release=, -r
275 The release of the distribution to install in the image. The
276 precise syntax of the argument this takes depends on the distri‐
277 bution used, and is either a numeric string (in case of Fedora
278 Linux, CentOS, ..., e.g. 29), or a distribution version name (in
279 case of Debian, Ubuntu, ..., e.g. artful). If neither this op‐
280 tion, nor Distribution= is specified, defaults to the distribu‐
281 tion version of the host. If the distribution is specified, de‐
282 faults to a recent version of it.
283 Mirror=, --mirror=, -m
285 The mirror to use for downloading the distribution packages.
286 Expects a mirror URL as argument.
287 Repositories=, --repositories=
289 Additional package repositories to use during installation. Ex‐
290 pects one or more URLs as argument, separated by commas. This
291 option may be used multiple times, in which case the list of
292 repositories to use is combined. Use “!*” to remove all reposi‐
293 tories from to the list or use e.g. “!repo-url” to remove just
294 one specific repository. For Arch Linux, additional reposito‐
295 ries must be passed in the form <name>::<url> (e.g. myre‐
296 po::https://myrepo.net).
297 UseHostRepositories=, --use-host-repositories
299 This option is only applicable for RPM-based distributions: Cen‐
300 tOS, Fedora Linux, Mageia, Photon, Rocky Linux, Alma Linux and
301 OpenMandriva. Allows use of the host’s existing RPM reposito‐
302 ries. By default, a hardcoded set of default RPM repositories
303 is generated and used. Use --repositories= to identify a custom
304 set of repositories to be enabled and used for the build.
305 RepositoryDirectory, --repository-directory
307 This option can (for now) only be used with RPM-based istribu‐
308 tions and Arch Linux. It identifies a directory containing ex‐
309 tra repository definitions that will be used when installing
310 packages. The files are passed directly to the corresponding
311 package manager and should be written in the format expected by
312 the package manager of the image’s distro.
313 Architecture=, --architecture=
315 The architecture to build the image for. Note that this cur‐
316 rently only works for architectures compatible with the host’s
317 architecture.
318 [Output] Section
320 Format=, --format=, -t
321 The image format type to generate. One of directory (for gener‐
322 ating OS images inside a local directory), subvolume (similar,
323 but as a btrfs subvolume), tar (similar, but a tarball of the
324 image is generated), cpio (similar, but a cpio archive is gener‐
325 ated), gpt_ext4 (a block device image with an ext4 file system
326 inside a GPT partition table), gpt_xfs (similar, but with an xfs
327 file system), gpt_btrfs (similar, but with an btrfs file sys‐
328 tem), gpt_squashfs (similar, but with a squashfs file system),
329 plain_squashfs (a plain squashfs file system without a partition
330 table).
331 ManifestFormat=, --manifest-format=
333 The manifest format type or types to generate. A comma-delimit‐
334 ed list consisting of json (the standard JSON output format that
335 describes the packages installed), changelog (a human-readable
336 text format designed for diffing). Defaults to json.
337 Output=, --output=, -o
339 Path for the output image file to generate. Takes a relative or
340 absolute path where the generated image will be placed. If nei‐
341 ther this option nor OutputDirectory= is used, the image is gen‐
342 erated under the name image, but its name suffixed with an ap‐
343 propriate file suffix (e.g. image.raw.xz in case gpt_ext4 is
344 used in combination with xz compression). If the ImageId= op‐
345 tion is configured it is used instead of image in the default
346 output name. If an image version is specified via ImageVer‐
347 sion=, it is included in the default name, e.g. a specified im‐
348 age version of 7.8 might result in an image file name of im‐
349 age_7.8.raw.xz.
350 OutputSplitRoot=, --output-split-root=, OutputSplitVerify=, --output-
352 split-verity=, OutputSplitKernel=, --output-split-kernel=
353 Paths for the split-out output image files, when SplitArti‐
354 facts=yes is used. If unspecified, the relevant split artifact
355 files will be named like the main image, but with .root, .veri‐
356 ty, and .efi suffixes inserted (and in turn possibly suffixed by
357 compression suffix, if compression is enabled).
358 OutputDirectory=, --output-dir=, -O
360 Path to a directory where to place all generated artifacts
361 (i.e. the generated image when an output path is not given,
362 SHA256SUMS file, etc.). If this is not specified and the direc‐
363 tory mkosi.output/ exists in the local directory, it is automat‐
364 ically used for this purpose. If the setting is not used and
365 mkosi.output/ does not exist, all output artifacts are placed
366 adjacent to the output image file.
367 WorkspaceDirectory=, --workspace-dir=
369 Path to a directory where to store data required temporarily
370 while building the image. This directory should have enough
371 space to store the full OS image, though in most modes the actu‐
372 ally used disk space is smaller. If not specified, and
373 mkosi.workspace/ exists in the local directory, it is used for
374 this purpose. Otherwise, a subdirectory in the temporary stor‐
375 age area is used ($TMPDIR if set, /var/tmp/ otherwise). The da‐
376 ta in this directory is removed automatically after each build.
377 It’s safe to manually remove the contents of this directory
378 should an mkosi invocation be aborted abnormally (for example,
379 due to reboot/power failure). If the btrfs output modes are se‐
380 lected this directory must be backed by btrfs too.
381 Force=, --force, -f
383 Replace the output file if it already exists, when building an
384 image. By default when building an image and an output artifact
385 already exists mkosi will refuse operation. Specify this option
386 once to delete all build artifacts from a previous run before
387 re-building the image. If incremental builds are enabled, spec‐
388 ifying this option twice will ensure the intermediary cache
389 files are removed, too, before the re-build is initiated. If a
390 package cache is used (also see the “Files” section below),
391 specifying this option thrice will ensure the package cache is
392 removed too, before the re-build is initiated. For the clean
393 operation this option has a slightly different effect: by de‐
394 fault the verb will only remove build artifacts from a previous
395 run, when specified once the incremental cache files are deleted
396 too, and when specified twice the package cache is also removed.
397 GPTFirstLBA=, --gpt-first-lba=
399 Override the first usable LBA (Logical Block Address) within the
400 GPT header. This defaults to 2048, which is actually the de‐
401 sired value. However, some tools, e.g. the prl_disk_tool utili‐
402 ty from the Parallels virtualization suite require this to be
403 set to 34, otherwise they might fail to resize the disk image
404 and/or partitions inside it.
405 Bootable=, --bootable, -b
407 Generate a bootable image. By default this will generate an im‐
408 age bootable on UEFI systems. Use BootProtocols= to select sup‐
409 port for a different boot protocol.
410 BootProtocols=, --boot-protocols=
412 Pick one or more boot protocols to support when generating a
413 bootable image, as enabled with Bootable=. Takes a comma-sepa‐
414 rated list of uefi or bios. May be specified more than once in
415 which case the specified lists are merged. If uefi is specified
416 the sd-boot UEFI boot loader is used, if bios is specified the
417 GNU Grub boot loader is used. Use “!*” to remove all previously
418 added protocols or “!protocol” to remove one protocol.
419 KernelCommandLine=, --kernel-command-line=
421 Use the specified kernel command line when building bootable im‐
422 ages. By default command line arguments get appended. To re‐
423 move all arguments from the current list pass “!*”. To remove
424 specific arguments add a space separated list of “!” prefixed
425 arguments. For example adding “!* console=ttyS0 rw” to a
426 mkosi.default file or the command line arguments passes “con‐
427 sole=ttyS0 rw” to the kernel in any case. Just adding “con‐
428 sole=ttyS0 rw” would append these two arguments to the kernel
429 command line created by lower priority configuration files or
430 previous KernelCommandLine= command line arguments.
431 SecureBoot=, --secure-boot
433 Sign the resulting kernel/initrd image for UEFI SecureBoot.
434 SecureBootKey=, --secure-boot-key=
436 Path to the PEM file containing the secret key for signing the
437 UEFI kernel image, if SecureBoot= is used.
438 SecureBootCertificate=, --secure-boot-certificate=
440 Path to the X.509 file containing the certificate for the signed
441 UEFI kernel image, if SecureBoot= is used.
442 SecureBootCommonName=, --secure-boot-common-name=
444 Common name to be used when generating SecureBoot keys via
445 mkosi’s genkey command. Defaults to mkosi of %u, where %u ex‐
446 pands to the username of the user invoking mkosi.
447 SecureBootValidDays=, --secure-boot-valid-days=
449 Number of days that the keys should remain valid when generating
450 SecureBoot keys via mkosi’s genkey command. Defaults to two
451 years (730 days).
452 ReadOnly=, --read-only
454 Set the read-only flag on the root partition in the partition
455 table. Only applies to gpt_ext4, gpt_xfs, gpt_btrfs, subvolume
456 output formats, and is implied on gpt_squashfs and
457 plain_squashfs. The read-only flag is essentially a hint to
458 tools using the image (see https://systemd.io/DISCOVERABLE_PAR‐
459 TITIONS/). In particular, all systemd tools like systemd-nspawn
460 and systemd-gpt-auto-generator will mount such partitions read-
461 only, but tools from other project may ignore the flag.
462 Minimize=, --minimize
464 Attempt to make the resulting root file system as small as pos‐
465 sible by removing free space from the file system. Only sup‐
466 ported for gpt_ext4 and gpt_btrfs. For ext4 this relies on re‐
467 size2fs -M, which reduces the free disk space but is not perfect
468 and generally leaves some free space. For btrfs the results are
469 optimal and no free space is left.
470 Encrypt=, --encrypt
472 Encrypt all partitions in the file system or just the root file
473 system. Takes either all or data as argument. If all, the
474 root, /home and /srv file systems will be encrypted using dm-
475 crypt/LUKS (with its default settings). If data, the root file
476 system will be left unencrypted, but /home and /srv will be en‐
477 crypted. The passphrase to use is read from the
478 mkosi.passphrase file in the current working directory. Note
479 that the UEFI System Partition (ESP) containing the boot loader
480 and kernel to boot is never encrypted since it needs to be ac‐
481 cessible by the firmware.
482 Verity=, --verity
484 Add a “Verity” integrity partition to the image. Takes a bool‐
485 ean or the special value signed, and defaults to disabled. If
486 enabled, the root partition (or /usr/ partition, in case UsrOn‐
487 ly= is enabled) is protected with dm-verity against offline mod‐
488 ification, the verification data is placed in an additional GPT
489 partition. Implies ReadOnly=yes. If this is enabled, the Veri‐
490 ty root hash is written to an output file with .roothash or .us‐
491 rhash suffix. If set to signed, Verity is also enabled, but the
492 resulting root hash is then also signed (in PKCS#7 format) with
493 the signature key configured with SecureBootKey=. Or in other
494 words: the SecureBoot key pair is then used to both sign the
495 kernel, if that is enabled, and the root//usr/ file system.
496 This signature is then stored in an additional output file with
497 the .roothash.p7s or .usrhash.p7s suffix in DER format. It is
498 also written to an additional partition in the image. The lat‐
499 ter allows generating self-contained signed disk images, imple‐
500 menting the Verity provisions described in the Discoverable Par‐
501 titions Specification (https://systemd.io/DISCOVERABLE_PARTI‐
502 TIONS).
503 CompressFs=, --compress-fs=
505 Enable or disable internal compression in the file system. Only
506 applies to output formats with squashfs or btrfs. Takes one of
507 zlib, lzo, zstd, lz4, xz or a boolean value as argument. If the
508 latter is used compression is enabled/disabled and the default
509 algorithm is used. In case of the squashfs output formats com‐
510 pression is implied, but this option may be used to select the
511 algorithm.
512 CompressOutput=, --compress-output=
514 Configure compression for the resulting image or archive. The
515 argument can be either a boolean or a compression algorithm (xz,
516 zstd). xz compression is used by default. Note that when ap‐
517 plied to block device image types this means the image cannot be
518 started directly but needs to be decompressed first. This also
519 means that the shell, boot, qemu verbs are not available when
520 this option is used. Implied for tar and cpio.
521 Compress=, --compress=
523 Enable compression. Using this option is equivalent to either
524 CompressFs= or CompressOutput=; the appropriate type of compres‐
525 sion is selected automatically.
526 Mksquashfs=, --mksquashfs=
528 Set the path to the mksquashfs executable to use. This is use‐
529 ful in case the parameters for the tool shall be augmented, as
530 the tool may be replaced by a script invoking it with the right
531 parameters, this way.
532 QCow2=, --qcow2
534 Encode the resulting image as QEMU QCOW2 image. This only ap‐
535 plies to gpt_ext4, gpt_xfs, gpt_btrfs, gpt_squashfs. QCOW2 im‐
536 ages can be read natively by qemu, but not by the Linux kernel.
537 This means the shell and boot verbs are not available when this
538 option is used, however qemu will work.
539 Hostname=, --hostname=
541 Set the image’s hostname to the specified name.
542 ImageVersion=, --image-version=
544 Configure the image version. This accepts any string, but it is
545 recommended to specify a series of dot separated components.
546 The version may also be configured in a file mkosi.version in
547 which case it may be conveniently managed via the bump verb or
548 the --auto-bump switch. When specified the image version is in‐
549 cluded in the default output file name, i.e. instead of im‐
550 age.raw the default will be image_0.1.raw for version 0.1 of the
551 image, and similar. The version is also passed via the $IM‐
552 AGE_VERSION to any build scripts invoked (which may be useful to
553 patch it into /etc/os-release or similar, in particular the IM‐
554 AGE_VERSION= field of it).
555 ImageId=, --image-id=
557 Configure the image identifier. This accepts a freeform string
558 that shall be used to identify the image with. If set the de‐
559 fault output file will be named after it (possibly suffixed with
560 the version). If this option is used the root, /usr/ and Verity
561 partitions in the image will have their labels set to this (pos‐
562 sibly suffixed by the image version). The identifier is also
563 passed via the $IMAGE_ID to any build scripts invoked (which may
564 be useful to patch it into /etc/os-release or similar, in par‐
565 ticular the IMAGE_ID= field of it).
566 WithUnifiedKernelImages=, --without-unified-kernel-images
568 If specified, mkosi does not build unified kernel images and in‐
569 stead installs kernels with a separate initrd and boot loader
570 config to the efi or bootloader partition.
571 HostonlyInitrd=, --hostonly-initrd
573 If specified, mkosi will run the tool to create the initrd such
574 that a non-generic initrd is created that will only be able to
575 run on the system mkosi is run on. Currently mkosi uses dracut
576 for all supported distributions except Clear Linux and this op‐
577 tion translates to enabling dracut’s hostonly option.
578 UsrOnly=, --usr-only
580 If specified, mkosi will only add the /usr/ directory tree (in‐
581 stead of the whole root file system) to the image. This is use‐
582 ful for fully stateless systems that come up pristine on every
583 single boot, where /etc/ and /var/ are populated by systemd-tmp‐
584 files/systemd-sysusers and related calls, or systems that are
585 originally shipped without a root file system, but where sys‐
586 temd-repart adds one on the first boot.
587 SplitArtifacts=, --split-artifacts
589 If specified and building an image with a partition table, also
590 write out the root file system partition, its Verity partition
591 (if configured) and the generated unified kernel (if configured)
592 into separate output files. This is useful in A/B update sce‐
593 narios where an existing disk image shall be augmented with a
594 new version of a root or /usr partition along with its Verity
595 partition and unified kernel.
596 NoChown=, --no-chown
598 By default, if mkosi is run inside a sudo environment all gener‐
599 ated artifacts have their UNIX user/group ownership changed to
600 the user which invoked sudo. With this option this may be
601 turned off and all generated files are owned by root.
602 TarStripSELinuxContext=, --tar-strip-selinux-context
604 If running on a SELinux-enabled system (Fedora Linux, CentOS,
605 Rocky Linux, Alma Linux), files inside the container are tagged
606 with SELinux context extended attributes (xattrs), which may in‐
607 terfere with host SELinux rules in building or further container
608 import stages. This option strips SELinux context attributes
609 from the resulting tar archive.
610 MachineID=, --machine-id
612 Set the machine’s ID to the specified value. If unused, a ran‐
613 dom ID will be used while building the image and the final image
614 will be shipped without a machine ID.
615 [Content] Section
617 BasePackages=, --base-packages
618 Takes a boolean or the special value conditional. If true, au‐
619 tomatically install packages to ensure basic functionality, as
620 appropriate for the given image type. For example, systemd is
621 always included, systemd-udev and dracut if the image is
622 bootable, and so on. If false, only packages specified with
623 Packages= will be installed. If conditional, the list of pack‐
624 ages to install will be extended with boolean dependencies (c.f.
625 https://rpm.org/user_doc/boolean_dependencies.html), to install
626 specific packages when other packages are in the list. For ex‐
627 ample, systemd-udev may be automatically included if the image
628 is bootable and systemd is installed. With this, various “base”
629 packages still need to be specified if they should be included,
630 but the corresponding “extension” packages will be added auto‐
631 matically when appropriate. This feature depends on support in
632 the package manager, so it is not implemented for all distribu‐
633 tions.
634 Packages=, --package=, -p
636 Install the specified distribution packages (i.e. RPM, DEB, ...)
637 in the image. Takes a comma separated list of package specifi‐
638 cations. This option may be used multiple times in which case
639 the specified package lists are combined. Packages specified
640 this way will be installed both in the development and the final
641 image. Use BuildPackages= to specify packages that shall only
642 be used for the image generated in the build image, but that
643 shall not appear in the final image. The types and syntax of
644 “package specifications” that are allowed depend on the package
645 installer (e.g. dnf or yum for rpm-based distros or apt for deb-
646 based distros), but may include package names, package names
647 with version and/or architecture, package name globs, paths to
648 packages in the file system, package groups, and virtual pro‐
649 vides, including file paths. To remove a package e.g. added by
650 a mkosi.default configuration file prepend the package name with
651 !. For example -p “!apache2” would remove the apache2 package.
652 To replace the apache2 package by the httpd package just add -p
653 “!apache2,httpd” to the command line arguments. To remove all
654 packages use “!*”. Example: when using an distro that uses dnf,
655 Packages=meson libfdisk-devel.i686 git-* prebuilt/rpms/sys‐
656 temd-249-rc1.local.rpm /usr/bin/ld @development-tools
657 python3dist(mypy) would install the meson package (in the latest
658 version), the 32-bit version of the libfdisk-devel package, all
659 available packages that start with the git- prefix, a systemd
660 rpm from the local file system, one of the packages that pro‐
661 vides /usr/bin/ld, the packages in the “Development Tools”
662 group, and the package that contains the mypy python module.
663 WithDocs=, --with-docs
665 Include documentation in the image built. By default if the un‐
666 derlying distribution package manager supports it documentation
667 is not included in the image built. The $WITH_DOCS environment
668 variable passed to the mkosi.build script indicates whether this
669 option was used or not.
670 WithTests=, --without-tests, -T
672 If set to false (or when the command-line option is used), the
673 $WITH_TESTS environment variable is set to 0 when the
674 mkosi.build script is invoked. This is supposed to be used by
675 the build script to bypass any unit or integration tests that
676 are normally run during the source build process. Note that
677 this option has no effect unless the mkosi.build build script
678 honors it.
679 Cache=, --cache=
681 Takes a path to a directory to use as package cache for the dis‐
682 tribution package manager used. If this option is not used, but
683 a mkosi.cache/ directory is found in the local directory it is
684 automatically used for this purpose. The directory configured
685 this way is mounted into both the development and the final im‐
686 age while the package manager is running.
687 SkeletonTree=, --skeleton-tree=
689 Takes a path to a directory to copy into the OS tree before in‐
690 voking the package manager. Use this to insert files and direc‐
691 tories into the OS tree before the package manager installs any
692 packages. If this option is not used, but the mkosi.skeleton/
693 directory is found in the local directory it is automatically
694 used for this purpose (also see the “Files” section below). In‐
695 stead of a directory, a tar file may be provided. In this case
696 it is unpacked into the OS tree before the package manager is
697 invoked. This mode of operation allows setting permissions and
698 file ownership explicitly, in particular for projects stored in
699 a version control system such as git which retain full file own‐
700 ership and access mode metadata for committed files. If the tar
701 file mkosi.skeleton.tar is found in the local directory it will
702 be automatically used for this purpose.
703 ExtraTree=, --extra-tree=
705 Takes a path to a directory to copy on top of the OS tree the
706 package manager generated. Use this to override any default
707 configuration files shipped with the distribution. If this op‐
708 tion is not used, but the mkosi.extra/ directory is found in the
709 local directory it is automatically used for this purpose (also
710 see the “Files” section below). As with the skeleton tree logic
711 above, instead of a directory, a tar file may be provided too.
712 mkosi.skeleton.tar will be automatically used if found in the
713 local directory.
714 CleanPackageMetadata=, --clean-package-metadata=
716 Enable/disable removal of package manager databases, caches, and
717 logs at the end of installation. Can be specified as true,
718 false, or “auto” (the default). With “auto”, files will be re‐
719 moved if the respective package manager executable is not
720 present at the end of the installation.
721 RemoveFiles=, --remove-files=
723 Takes a comma-separated list of globs. Files in the image
724 matching the globs will be purged at the end.
725 RemovePackages=, --remove-package=
727 Takes a comma-separated list of package specifications for re‐
728 moval, in the same format as Packages=. The removal will be
729 performed as one of the last steps. This step is skipped if
730 CleanPackageMetadata=no is used. This option is currently only
731 implemented for distributions using dnf.
732 Environment=, --environment=
734 Adds variables to the environment that the build/prepare/postin‐
735 stall/finalize scripts are executed with. Takes a space-sepa‐
736 rated list of variable assignments or just variable names. In
737 the latter case, the values of those variables will be passed
738 through from the environment in which mkosi was invoked. This
739 option may be specified more than once, in which case all listed
740 variables will be set. If the same variable is set twice, the
741 later setting overrides the earlier one.
742 BuildSources=, --build-sources=
744 Takes a path to a source tree to copy into the development im‐
745 age, if the build script is used. This only applies if a build
746 script is used, and defaults to the local directory. Use
747 SourceFileTransfer= to configure how the files are transferred
748 from the host to the container image.
749 BuildDirectory=, --build-dir=
751 Takes a path of a directory to use as build directory for build
752 systems that support out-of-tree builds (such as Meson). The
753 directory used this way is shared between repeated builds, and
754 allows the build system to reuse artifacts (such as object
755 files, executable, ...) generated on previous invocations. This
756 directory is mounted into the development image when the build
757 script is invoked. The build script can find the path to this
758 directory in the $BUILDDIR environment variable. If this option
759 is not specified, but a directory mkosi.builddir/ exists in the
760 local directory it is automatically used for this purpose (also
761 see the “Files” section below).
762 IncludeDirectory=, --include-directory=
764 Takes a path of a directory to use as the include directory.
765 This directory is mounted at /usr/include when building the
766 build image and running the build script. This means all in‐
767 clude files installed to /usr/include will be stored in this di‐
768 rectory. This is useful to make include files available on the
769 host system for use by language servers to provide code comple‐
770 tion. If this option is not specified, but a directory
771 mkosi.includedir/ exists in the local directory, it is automati‐
772 cally used for this purpose (also see the “Files” section be‐
773 low).
774 InstallDirectory=, --install-directory=
776 Takes a path of a directory to use as the install directory.
777 The directory used this way is shared between builds and allows
778 the build system to not have to reinstall files that were al‐
779 ready installed by a previous build and didn’t change. The
780 build script can find the path to this directory in the $DESTDIR
781 environment variable. If this option is not specified, but a
782 directory mkosi.installdir exists in the local directory, it is
783 automatically used for this purpose (also see the “Files” sec‐
784 tion below).
785 BuildPackages=, --build-package=
787 Similar to Packages=, but configures packages to install only in
788 the first phase of the build, into the development image. This
789 option should be used to list packages containing header files,
790 compilers, build systems, linkers and other build tools the
791 mkosi.build script requires to operate. Note that packages
792 listed here are only included in the image created during the
793 first phase of the build, and are absent in the final image.
794 Use Packages= to list packages that shall be included in both.
795 Packages are appended to the list. Packages prefixed with “!”
796 are removed from the list. “!*” removes all packages from the
797 list.
798 Password=, --password=
800 Set the password of the root user. By default the root account
801 is locked. If this option is not used, but a file mkosi.rootpw
802 exists in the local directory, the root password is automatical‐
803 ly read from it.
804 PasswordIsHashed=, --password-is-hashed
806 Indicate that the password supplied for the root user has al‐
807 ready been hashed, so that the string supplied with Password= or
808 mkosi.rootpw will be written to /etc/shadow literally.
809 Autologin=, --autologin
811 Enable autologin for the root user on /dev/pts/0 (nspawn),
812 /dev/tty1 (QEMU) and /dev/ttyS0 (QEMU with QemuHeadless=yes) by
813 patching /etc/pam.d/login.
814 SkipFinalPhase=, --skip-final-phase=
816 Causes the (second) final image build stage to be skipped. This
817 is useful in combination with a build script, for when you care
818 about the artifacts that were created locally in $BUILDDIR, but
819 ultimately plan to discard the final image.
820 BuildScript=, --build-script=
822 Takes a path to an executable that is used as build script for
823 this image. If this option is used the build process will be
824 two-phased instead of single-phased. The specified script is
825 copied onto the development image and executed inside an sys‐
826 temd-nspawn container environment. If this option is not used,
827 but the mkosi.build file found in the local directory it is au‐
828 tomatically used for this purpose (also see the “Files” section
829 below). Specify an empty value to disable automatic detection.
830 PrepareScript=, --prepare-script=
832 Takes a path to an executable that is invoked inside the image
833 right after installing the software packages. It is the last
834 step before the image is cached (if incremental mode is en‐
835 abled). This script is invoked inside a systemd-nspawn contain‐
836 er environment, and thus does not have access to host resources.
837 If this option is not used, but an executable script mkosi.pre‐
838 pare is found in the local directory, it is automatically used
839 for this purpose. Specify an empty value to disable automatic
840 detection.
841 PostInstallationScript=, --postinst-script=
843 Takes a path to an executable that is invoked inside the final
844 image right after copying in the build artifacts generated in
845 the first phase of the build. This script is invoked inside a
846 systemd-nspawn container environment, and thus does not have ac‐
847 cess to host resources. If this option is not used, but an exe‐
848 cutable mkosi.postinst is found in the local directory, it is
849 automatically used for this purpose. Specify an empty value to
850 disable automatic detection.
851 FinalizeScript=, --finalize-script=
853 Takes a path to an executable that is invoked outside the final
854 image right after copying in the build artifacts generated in
855 the first phase of the build, and after having executed the
856 mkosi.postinst script (see PostInstallationScript=). This
857 script is invoked directly in the host environment, and hence
858 has full access to the host’s resources. If this option is not
859 used, but an executable mkosi.finalize is found in the local di‐
860 rectory, it is automatically used for this purpose. Specify an
861 empty value to disable automatic detection.
862 SourceFileTransfer=, --source-file-transfer=
864 Configures how the source file tree (as configured with Build‐
865 Sources=) is transferred into the container image during the
866 first phase of the build. Takes one of copy-all (to copy all
867 files from the source tree), copy-git-cached (to copy only those
868 files git ls-files --cached lists), copy-git-others (to copy on‐
869 ly those files git ls-files --others lists), mount to bind mount
870 the source tree directly. Defaults to copy-git-cached if a git
871 source tree is detected, otherwise copy-all. When you specify
872 copy-git-more, it is the same as copy-git-cached, except it also
873 includes the .git/ directory.
874 SourceFileTransferFinal=, --source-file-transfer-final=
876 Same as SourceFileTransfer=, but for the final image instead of
877 the build image. Takes the same values as SourceFileFransfer=
878 except mount. By default, sources are not copied into the final
879 image.
880 SourceResolveSymlinks=, --source-resolve-symlinks
882 If given, any symbolic links in the source file tree are re‐
883 solved and the file contents are copied to the build image. If
884 not given, they are left as symbolic links. This only applies
885 if SourceFileTransfer= is copy-all. Defaults to leaving them as
886 symbolic links.
887 SourceResolveSymlinksFinal=, --source-resolve-symlinks-final
889 Same as SourceResolveSymlinks=, but for the final image instead
890 of the build image.
891 WithNetwork=, --with-network
893 When true, enables network connectivity while the build script
894 mkosi.build is invoked. By default, the build script runs with
895 networking turned off. The $WITH_NETWORK environment variable
896 is passed to the mkosi.build build script indicating whether the
897 build is done with or without network. If specified as never,
898 the package manager is instructed not to contact the network for
899 updating package data. This provides a minimal level of repro‐
900 ducibility, as long as the package data cache is already fully
901 populated.
902 Settings=, --settings=
904 Specifies a .nspawn settings file for systemd-nspawn to use in
905 the boot and shell verbs, and to place next to the generated im‐
906 age file. This is useful to configure the systemd-nspawn envi‐
907 ronment when the image is run. If this setting is not used but
908 an mkosi.nspawn file found in the local directory it is automat‐
909 ically used for this purpose.
910 [Partitions] Section
912 BaseImage=, --base-image=
913 Use the specified directory or file system image as the base im‐
914 age, and create the output image that consists only of changes
915 from this base. The base image is attached as the lower file
916 system in an overlayfs structure, and the output filesystem be‐
917 comes the upper layer, initially empty. Thus files that are not
918 modified compared to the base image are not present in the out‐
919 put image. This option may be used to create systemd “system
920 extensions” or portable services. See https://systemd.io/PORTA‐
921 BLE_SERVICES/#extension-images for more information.
922 RootSize=, --root-size=
924 Takes a size in bytes for the root file system. The specified
925 numeric value may be suffixed with K, M, G to indicate kilo-,
926 mega- and gigabytes (all to the base of 1024). This applies to
927 output formats gpt_ext4, gpt_xfs, gpt_btrfs. Defaults to 3G.
928 ESPSize=, --esp-size=
930 Similar to RootSize=, configures the size of the UEFI System
931 Partition (ESP). This is only relevant if the Bootable= option
932 is used to generate a bootable image. Defaults to 256 MB.
933 SwapSize=, --swap-size=
935 Similar to RootSize=, configures the size of a swap partition on
936 the image. If omitted, no swap partition is created.
937 HomeSize=, --home-size=
939 Similar to RootSize=, configures the size of the /home parti‐
940 tion. If omitted, no separate /home partition is created.
941 SrvSize=, --srv-size=
943 Similar to RootSize=, configures the size of the /srv partition.
944 If omitted, no separate /srv partition is created.
945 [Validation] Section
947 Checksum=, --checksum
948 Generate a SHA256SUMS file of all generated artifacts after the
949 build is complete.
950 Sign=, --sign
952 Sign the generated SHA256SUMS using gpg after completion.
953 Key=, --key=
955 Select the gpg key to use for signing SHA256SUMS. This key must
956 be already present in the gpg keyring.
957 BMap=, --bmap
959 Generate a bmap file for usage with bmaptool from the generated
960 image file.
961 [Host] Section
963 ExtraSearchPaths=, --extra-search-paths=
964 List of colon-separated paths to look for tools in, before using
965 the regular $PATH search path.
966 QemuHeadless=, --qemu-headless=
968 When used with the build verb, this option adds console=ttyS0 to
969 the image’s kernel command line and sets the terminal type of
970 the serial console in the image to the terminal type of the host
971 (more specifically, the value of the $TERM environment variable
972 passed to mkosi). This makes sure that all terminal features
973 such as colors and shortcuts still work as expected when con‐
974 necting to the qemu VM over the serial console (for example via
975 -nographic). When used with the qemu verb, this option adds the
976 -nographic option to qemu’s command line so qemu starts a head‐
977 less vm and connects to its serial console from the current ter‐
978 minal instead of launching the VM in a separate window.
979 QemuSmp=, --qemu-smp=
981 When used with the qemu verb, this options sets qemu’s -smp ar‐
982 gument which controls the number of guest’s CPUs. Defaults to
983 2.
984 QemuMem=, --qemu-mem=
986 When used with the qemu verb, this options sets qemu’s -m argu‐
987 ment which controls the amount of guest’s RAM. Defaults to 1G.
988 QemuKvm=, --qemu-kvm=
990 When used with the qemu verb, this option specifies whether QEMU
991 should use KVM acceleration. Defaults to yes if the host ma‐
992 chine supports KVM acceleration, no otherwise.
993 NspawnKeepUnit=, --nspawn-keep-unit
995 When used, this option instructs underlying calls of systemd-
996 nspawn to use the current unit scope, instead of creating a ded‐
997 icated transcient scope unit for the containers. This option
998 should be used when mkosi is run by a service unit.
999 Netdev=, --netdev
1001 When used with the boot or qemu verbs, this option creates a
1002 virtual ethernet link between the host and the container/VM.
1003 The host interface is automatically picked up by systemd-net‐
1004 workd as documented in systemd-nspawn’s man page:
1005 https://www.freedesktop.org/software/systemd/man/systemd-
1006 nspawn.html#-n
1007 Ephemeral=, --ephemeral
1009 When used with the shell, boot, or qemu verbs, this option runs
1010 the specified verb on a temporary snapshot of the output image
1011 that is removed immediately when the container terminates. Tak‐
1012 ing the temporary snapshot is more efficient on file systems
1013 that support subvolume snapshots or `reflinks' natively (“btrfs”
1014 or new “xfs”) than on more traditional file systems that do not
1015 (“ext4”).
1016 Ssh=, --ssh
1018 If specified, installs and enables sshd in the final image and
1019 generates a SSH keypair and adds the public key to root’s autho‐
1020 rized_keys in the final image. The private key is stored in
1021 mkosi’s output directory. When building with this option and
1022 running the image using mkosi boot or mkosi qemu, the mkosi ssh
1023 command can be used to connect to the container/VM via SSH.
1024 SshKey=, --ssh-key=
1026 If specified, use the given private key when connecting to the
1027 guest machine via mkosi ssh. This requires the public key coun‐
1028 terpart to be present in the same location, suffixed with .pub
1029 (as done by ssh-keygen). If this option is not present, mkosi
1030 generates a new key pair automatically.
1031 SshAgent=, --ssh-agent=
1033 If specified as a path, use the given socket to connect to the
1034 ssh agent when building an image and when connecting via mkosi
1035 ssh instead of hard-coding a key. If specified as true,
1036 $SSH_AUTH_SOCK will be parsed instead (hint: use sudo with -E).
1037 The keys listed by ssh-add -L will be installed as authorized
1038 keys in the built image. The ssh invocation done by mkosi ssh
1039 will inherit $SSH_AUTH_SOCK for authentication purposes.
1040 SshPort=, --ssh-port=
1042 In the image, sshd will be configured to listen on this port.
1043 mkosi ssh will connect to this port.
1044 SshTimeout=, --ssh-timeout=
1046 When used with the ssh verb, mkosi will attempt to retry the SSH
1047 connection up to given timeout (in seconds) in case it fails.
1048 This option is useful mainly in scripted environments where the
1049 qemu and ssh verbs are used in a quick succession and the virtu‐
1050 al device might not get enough time to configure itself.
1051 Commandline-only Options
1053 Those settings cannot be configured in the configuration files.
1054 --directory=, -C
1056 Takes a path to a directory. mkosi switches to this directory
1057 before doing anything. Note that the various mkosi.* files are
1058 searched for only after changing to this directory, hence using
1059 this option is an effective way to build a project located in a
1060 specific directory.
1061 --default=
1063 Loads additional settings from the specified settings file.
1064 Most command line options may also be configured in a settings
1065 file. See the table below to see which command line options
1066 match which settings file option. If this option is not used,
1067 but a file mkosi.default is found in the local directory it is
1068 automatically used for this purpose. If a setting is configured
1069 both on the command line and in the settings file, the command
1070 line generally wins, except for options taking lists in which
1071 case both lists are combined.
1072 --all, -a
1074 Iterate through all files mkosi.* in the mkosi.files/ subdirec‐
1075 tory, and build each as if --default=mkosi.files/mkosi.... was
1076 invoked. This is a quick way to build a large number of images
1077 in one go. Any additional specified command line arguments
1078 override the relevant options in all files processed this way.
1079 --all-directory=
1081 If specified, overrides the directory the --all logic described
1082 above looks for settings files in. If unspecified, defaults to
1083 mkosi.files/ in the current working directory.
1084 --incremental, -i
1086 Enable incremental build mode. This only applies if the two-
1087 phase mkosi.build build script logic is used. In this mode, a
1088 copy of the OS image is created immediately after all OS pack‐
1089 ages are unpacked but before the mkosi.build script is invoked
1090 in the development container. Similarly, a copy of the final
1091 image is created immediately before the build artifacts from the
1092 mkosi.build script are copied in. On subsequent invocations of
1093 mkosi with the -i switch these cached images may be used to skip
1094 the OS package unpacking, thus drastically speeding up repeti‐
1095 tive build times. Note that when this is used and a pair of
1096 cached incremental images exists they are not automatically re‐
1097 generated, even if options such as Packages= are modified. In
1098 order to force rebuilding of these cached images, combine -i
1099 with -ff to ensure cached images are first removed and then re-
1100 created.
1101 --debug=
1103 Enable additional debugging output. Takes a comma-separated
1104 list of arguments specifying the area of interest. Pass any in‐
1105 valid value (e.g. empty) to list currently accepted values.
1106 --version
1108 Show package version.
1109 --help, -h
1111 Show brief usage information.
1112 --auto-bump, -B
1114 If specified, after each successful build the the version is
1115 bumped in a fashion equivalent to the bump verb, in preparation
1116 for the next build. This is useful for simple, linear version
1117 management: each build in a series will have a version number
1118 one higher then the previous one.
1119 Supported distributions
1121 Images may be created containing installations of the following operat‐
1122 ing systems:
1123 • Fedora Linux
1125 • Debian
1127 • Ubuntu
1129 • Arch Linux
1131 • openSUSE
1133 • Mageia
1135 • CentOS
1137 • Clear Linux
1139 • Photon
1141 • OpenMandriva
1143 • Rocky Linux
1145 • Alma Linux
1147 • Gentoo
1149 In theory, any distribution may be used on the host for building images
1151 containing any other distribution, as long as the necessary tools are
1152 available. Specifically, any distribution that packages debootstrap
1153 may be used to build Debian or Ubuntu images. Any distribution that
1154 packages dnf may be used to build Fedora Linux, Mageia or OpenMandriva
1155 images. Any distro that packages pacstrap may be used to build Arch
1156 Linux images. Any distribution that packages zypper may be used to
1157 build openSUSE images. Any distribution that packages yum (or the new‐
1158 er replacement dnf) may be used to build CentOS, Rocky Linux, or Alma
1159 Linux images. Any distribution that packages emerge may be used to
1160 build Gentoo images.
1161 Currently, Fedora Linux packages all relevant tools as of Fedora 28.
1163 Compatibility
1165 Legacy concepts are avoided: generated images use GPT disk labels (and
1166 no MBR labels), and only systemd-based images may be generated.
1167 All generated GPT disk images may be booted in a local container di‐
1169 rectly with:
1170 systemd-nspawn -bi image.raw
1172 Additionally, bootable GPT disk images (as created with the --bootable
1174 flag) work when booted directly by EFI and BIOS systems, for example in
1175 KVM via:
1176 qemu-kvm -m 512 -smp 2 -bios /usr/share/edk2/ovmf/OVMF_CODE.fd -drive format=raw,file=image.raw
1178 EFI bootable GPT images are larger than plain GPT images, as they addi‐
1180 tionally carry an EFI system partition containing a boot loader, as
1181 well as a kernel, kernel modules, udev and more.
1182 All directory or btrfs subvolume images may be booted directly with:
1184 systemd-nspawn -bD image
1186
1188 To make it easy to build images for development versions of your
1189 projects, mkosi can read configuration data from the local directory,
1190 under the assumption that it is invoked from a source tree. Specifi‐
1191 cally, the following files are used if they exist in the local directo‐
1192 ry:
1193 • The mkosi.default file provides the default configuration for the im‐
1195 age building process. For example, it may specify the distribution
1196 to use (fedora, ubuntu, debian, arch, opensuse, mageia, openmandriva,
1197 gentoo) for the image, or additional distribution packages to in‐
1198 stall. Note that all options encoded in this configuration file may
1199 also be set on the command line, and this file is hence little more
1200 than a way to make sure invoking mkosi without further parameters in
1201 your source tree is enough to get the right image of your choice set
1202 up.
1203 Additionally, if a mkosi.default.d/ directory exists, each file in it
1205 is loaded in the same manner adding/overriding the values specified
1206 in mkosi.default. If mkosi.default.d/ contains a directory named af‐
1207 ter the distribution being built, each file in that directory is also
1208 processed.
1209 The file format is inspired by Windows .ini files and supports multi-
1211 line assignments: any line with initial whitespace is considered a
1212 continuation line of the line before. Command-line arguments, as
1213 shown in the help description, have to be included in a configuration
1214 block (e.g. “[Content]”) corresponding to the argument group
1215 (e.g. “Content”), and the argument gets converted as follows:
1216 “--with-network” becomes “WithNetwork=yes”. For further details see
1217 the table above.
1218 • The mkosi.skeleton/ directory or mkosi.skeleton.tar archive may be
1220 used to insert files into the image. The files are copied before the
1221 distribution packages are installed into the image. This allows cre‐
1222 ation of files that need to be provided early, for example to config‐
1223 ure the package manager or set systemd presets.
1224 When using the directory, file ownership is not preserved: all files
1226 copied will be owned by root. To preserve ownership, use a tar ar‐
1227 chive.
1228 • The mkosi.extra/ directory or mkosi.extra.tar archive may be used to
1230 insert additional files into the image, on top of what the distribu‐
1231 tion includes in its packages. They are similar to mkosi.skeleton/
1232 and mkosi.skeleton.tar, but the files are copied into the directory
1233 tree of the image after the OS was installed.
1234 When using the directory, file ownership is not preserved: all files
1236 copied will be owned by root. To preserve ownership, use a tar ar‐
1237 chive.
1238 • mkosi.build may be an executable script. If it exists, the image
1240 will be built twice: the first iteration will be the development im‐
1241 age, the second iteration will be the final image. The development
1242 image is used to build the project in the current working directory
1243 (the source tree). For that the whole directory is copied into the
1244 image, along with the mkosi.build script. The script is then invoked
1245 inside the image (via systemd-nspawn), with $SRCDIR pointing to the
1246 source tree. $DESTDIR points to a directory where the script should
1247 place any files generated it would like to end up in the final image.
1248 Note that make/automake/meson based build systems generally honor
1249 $DESTDIR, thus making it very natural to build source trees from the
1250 build script. After the development image was built and the build
1251 script ran inside of it, it is removed again. After that the final
1252 image is built, without any source tree or build script copied in.
1253 However, this time the contents of $DESTDIR are added into the image.
1254 When the source tree is copied into the build image, all files are
1256 copied, except for mkosi.builddir/, mkosi.cache/ and mkosi.output/.
1257 That said, .gitignore is respected if the source tree is a git check‐
1258 out. If multiple different images shall be built from the same
1259 source tree it is essential to exclude their output files from this
1260 copy operation, as otherwise a version of an image built earlier
1261 might be included in a later build, which is usually not intended.
1262 An alternative to excluding these built images via .gitignore entries
1263 is to use the mkosi.output/ directory, which is an easy way to ex‐
1264 clude all build artifacts.
1265 The $MKOSI_DEFAULT environment variable will be set inside of this
1267 script so that you know which mkosi.default (if any) was passed in.
1268 • The mkosi.prepare script is invoked directly after the software pack‐
1270 ages are installed, from within the image context, if it exists. It
1271 is once called for the development image (if this is enabled, see
1272 above) with the “build” command line parameter, right before copying
1273 the extra tree. It is called a second time for the final image with
1274 the “final” command line parameter. This script has network access
1275 and may be used to install packages from other sources than the dis‐
1276 tro’s package manager (e.g. pip, npm, ...), after all software pack‐
1277 ages are installed but before the image is cached (if incremental
1278 mode is enabled). This script is executed within $SRCDIR. In con‐
1279 trast to a general purpose installation, it is safe to install pack‐
1280 ages to the system (pip install, npm install -g) instead of in $SR‐
1281 CDIR itself because the build image is only used for a single project
1282 and can easily be thrown away and rebuilt so there’s no risk of con‐
1283 flicting dependencies and no risk of polluting the host system.
1284 • The mkosi.postinst script is invoked as the penultimate step of pre‐
1286 paring an image, from within the image context, if it exists. It is
1287 called first for the development image (if this is enabled, see
1288 above) with the “build” command line parameter, right before invoking
1289 the build script. It is called a second time for the final image
1290 with the “final” command line parameter, right before the image is
1291 considered complete. This script may be used to alter the images
1292 without any restrictions, after all software packages and built
1293 sources have been installed. Note that this script is executed di‐
1294 rectly in the image context with the final root directory in place,
1295 without any $SRCDIR/$DESTDIR setup.
1296 • The mkosi.finalize script, if it exists, is invoked as last step of
1298 preparing an image, from the host system. It is once called for the
1299 development image (if this is enabled, see above) with the “build”
1300 command line parameter, as the last step before invoking the build
1301 script, after the mkosi.postinst script is invoked. It is called the
1302 second time with the “final” command line parameter as the last step
1303 before the image is considered complete. The environment variable
1304 $BUILDROOT points to the root directory of the installation image.
1305 Additional verbs may be added in the future, the script should be
1306 prepared for that. This script may be used to alter the images with‐
1307 out any restrictions, after all software packages and built sources
1308 have been installed. This script is more flexible than
1309 mkosi.postinst in two regards: it has access to the host file system
1310 so it’s easier to copy in additional files or to modify the image
1311 based on external configuration, and the script is run in the host,
1312 so it can be used even without emulation even if the image has a for‐
1313 eign architecture.
1314 • The mkosi.mksquashfs-tool script, if it exists, will be called wher‐
1316 ever mksquashfs would be called.
1317 • The mkosi.nspawn nspawn settings file will be copied into the same
1319 place as the output image file, if it exists. This is useful since
1320 nspawn looks for settings files next to image files it boots, for ad‐
1321 ditional container runtime settings.
1322 • The mkosi.cache/ directory, if it exists, is automatically used as
1324 package download cache, in order to speed repeated runs of the tool.
1325 • The mkosi.builddir/ directory, if it exists, is automatically used as
1327 out-of-tree build directory, if the build commands in the mkosi.build
1328 script support it. Specifically, this directory will be mounted into
1329 the build container, and the $BUILDDIR environment variable will be
1330 set to it when the build script is invoked. The build script may
1331 then use this directory as build directory, for automake-style or
1332 ninja-style out-of-tree builds. This speeds up builds considerably,
1333 in particular when mkosi is used in incremental mode (-i): not only
1334 the disk images, but also the build tree is reused between subsequent
1335 invocations. Note that if this directory does not exist the $BUILD‐
1336 DIR environment variable is not set, and it is up to build script to
1337 decide whether to do in in-tree or an out-of-tree build, and which
1338 build directory to use.
1339 • The mkosi.includedir/ directory, if it exists, is automatically used
1341 as an out-of-tree include directory for header files. Specifically,
1342 it will be mounted in the build container at /usr/include/ when
1343 building the build image and when running the build script. After
1344 building the (cached) build image, this directory will contain all
1345 the files installed to /usr/include. Language servers or other tools
1346 can use these files to provide a better editing experience for devel‐
1347 opers working on a project.
1348 • The mkosi.installdir/ directory, if it exists, is automatically used
1350 as the install directory. Specifically, this directory will be
1351 mounted into the container at /root/dest when running the build
1352 script. After running the build script, the contents of this direc‐
1353 tory are installed into the final image. This is useful to cache the
1354 install step of the build. If used, subsequent builds will only have
1355 to reinstall files that have changed since the previous build.
1356 • The mkosi.rootpw file can be used to provide the password or hashed
1358 password (if --password-is-hashed is set) for the root user of the
1359 image. The password may optionally be followed by a newline charac‐
1360 ter which is implicitly removed. The file must have an access mode
1361 of 0600 or less. If this file does not exist, the distribution’s de‐
1362 fault root password is set (which usually means access to the root
1363 user is blocked).
1364 • The mkosi.passphrase file provides the passphrase to use when LUKS
1366 encryption is selected. It should contain the passphrase literally,
1367 and not end in a newline character (i.e. in the same format as crypt‐
1368 setup and /etc/crypttab expect the passphrase files). The file must
1369 have an access mode of 0600 or less. If this file does not exist and
1370 encryption is requested, the user is queried instead.
1371 • The mkosi.secure-boot.crt and mkosi.secure-boot.key files contain an
1373 X.509 certificate and PEM private key to use when UEFI SecureBoot
1374 support is enabled. All EFI binaries included in the image’s ESP are
1375 signed with this key, as a late step in the build process.
1376 • The mkosi.output/ directory will be used for all build artifacts, if
1378 the image output path is not configured (i.e. no --output= setting
1379 specified), or configured to a filename (i.e. a path containing no /
1380 character). This includes the image itself, the root hash file in
1381 case Verity is used, the checksum and its signature if that’s en‐
1382 abled, and the nspawn settings file if there is any. Note that this
1383 directory is not used if the image output path contains at least one
1384 slash, and has no effect in that case. This setting is particularly
1385 useful if multiple different images shall be built from the same
1386 working directory, as otherwise the build result of a preceding run
1387 might be copied into a build image as part of the source tree (see
1388 above).
1389 • The mkosi.reposdir/ directory, if it exists, is automatically used as
1391 the repository directory for extra repository files. See the Reposi‐
1392 toryDirectory option for more information.
1393 All these files are optional.
1395 Note that the location of all these files may also be configured during
1397 invocation via command line switches, and as settings in mkosi.default,
1398 in case the default settings are not acceptable for a project.
1399
1401 If no build script mkosi.build (see above) is used the build consists
1402 of a single phase only: the final image is generated as the combination
1403 of mkosi.skeleton/ (see above), the unpacked distribution packages and
1404 mkosi.extra/.
1405 If a build script mkosi.build is used the build consists of two phases:
1407 in the the first development phase an image that includes necessary
1408 build tools (i.e. the combination of Packages= and BuildPackages= is
1409 installed) is generated (i.e. the combination of mkosi.skeleton/ and
1410 unpacked distribution packages). Into this image the source tree is
1411 copied and mkosi.build executed. The artifacts the mkosi.build gener‐
1412 ates are saved. Then, the second final phase starts: an image that ex‐
1413 cludes the build tools (i.e. only Packages= is installed, BuildPack‐
1414 ages= is not) is generated. This time the build artifacts saved from
1415 the first phase are copied in, and mkosi.extra copied on top, thus gen‐
1416 erating the final image.
1417 The two-phased approach ensures that source tree is executed in a clean
1419 and comprehensive environment, while at the same the final image re‐
1420 mains minimal and contains only those packages necessary at runtime,
1421 but avoiding those necessary at build-time.
1422 Note that only the package cache mkosi.cache/ is shared between the two
1424 phases. The distribution package manager is executed exactly once in
1425 each phase, always starting from a directory tree that is populated
1426 with mkosi.skeleton but nothing else.
1427
1429 mkosi supports three different caches for speeding up repetitive re-
1430 building of images. Specifically:
1431 1. The package cache of the distribution package manager may be cached
1433 between builds. This is configured with the --cache= option or the
1434 mkosi.cache/ directory. This form of caching relies on the distri‐
1435 bution’s package manager, and caches distribution packages (RPM,
1436 DEB, ...) after they are downloaded, but before they are unpacked.
1437 2. If an mkosi.build script is used, by enabling incremental build mode
1439 with --incremental, a cached copy of the development and final im‐
1440 ages can be made immediately before the build sources are copied in
1441 (for the development image) or the artifacts generated by
1442 mkosi.build are copied in (in case of the final image). This form
1443 of caching allows bypassing the time-consuming package unpacking
1444 step of the distribution package managers, but is only effective if
1445 the list of packages to use remains stable, but the build sources
1446 and its scripts change regularly. Note that this cache requires
1447 manual flushing: whenever the package list is modified the cached
1448 images need to be explicitly removed before the next re-build, using
1449 the -f switch.
1450 3. Finally, between multiple builds the build artifact directory may be
1452 shared, using the mkosi.builddir/ directory. This directory allows
1453 build systems such as Meson to reuse already compiled sources from a
1454 previous built, thus speeding up the build process of the
1455 mkosi.build build script.
1456 The package cache (i.e. the first item above) is unconditionally use‐
1458 ful. The latter two caches only apply to uses of mkosi with a source
1459 tree and build script. When all three are enabled together turn-around
1460 times for complete image builds are minimal, as only changed source
1461 files need to be recompiled: an OS image rebuilt will be almost as
1462 quick to build the source tree only.
1463
1465 The build script mkosi.build receives the following environment vari‐
1466 ables:
1467 • $SRCDIR contains the path to the sources to build.
1469 • $DESTDIR is a directory into which any artifacts generated by the
1471 build script shall be placed.
1472 • $BUILDDIR is only defined if mkosi.builddir and points to the build
1474 directory to use. This is useful for all build systems that support
1475 out-of-tree builds to reuse already built artifacts from previous
1476 runs.
1477 • $WITH_DOCS is either 0 or 1 depending on whether a build without or
1479 with installed documentation was requested (WithDocs=yes). The build
1480 script should suppress installation of any package documentation to
1481 $DESTDIR in case $WITH_DOCS is set to 0.
1482 • $WITH_TESTS is either 0or 1 depending on whether a build without or
1484 with running the test suite was requested (WithTests=no). The build
1485 script should avoid running any unit or integration tests in case
1486 $WITH_TESTS is 0.
1487 • $WITH_NETWORK is either 0or 1 depending on whether a build without or
1489 with networking is being executed (WithNetwork=no). The build script
1490 should avoid any network communication in case $WITH_NETWORK is 0.
1491
1493 Create and run a raw GPT image with ext4, as image.raw:
1494 # mkosi --bootable --incremental boot
1496 Create and run a bootable btrfs GPT image, as foobar.raw:
1498 # mkosi --format gpt_btrfs --bootable -o foobar.raw
1500 # mkosi --output foobar.raw boot
1501 # mkosi --output foobar.raw qemu
1502 Create and run a Fedora Linux image into a plain directory:
1504 # mkosi --distribution fedora --format directory boot
1506 Create a compressed image image.raw.xz and add a checksum file, and in‐
1508 stall SSH into it:
1509 # mkosi --distribution fedora --format gpt_squashfs --checksum --compress --package=openssh-clients
1511 Inside the source directory of an automake-based project, configure
1513 mkosi so that simply invoking mkosi without any parameters builds an OS
1514 image containing a built version of the project in its current state:
1515 # cat >mkosi.default <<EOF
1517 [Distribution]
1518 Distribution=fedora
1519 Release=24
1520 [Output]
1522 Format=gpt_btrfs
1523 Bootable=yes
1524 [Content]
1526 Packages=openssh-clients,httpd
1527 BuildPackages=make,gcc,libcurl-devel
1528 EOF
1529 # cat >mkosi.build <<EOF
1530 #!/bin/sh
1531 cd $SRCDIR
1532 ./autogen.sh
1533 ./configure --prefix=/usr
1534 make -j `nproc`
1535 make install
1536 EOF
1537 # chmod +x mkosi.build
1538 # mkosi --bootable --incremental boot
1539 # systemd-nspawn -bi image.raw
1540 To create a Fedora Linux image with hostname:
1542 # mkosi --distribution fedora --hostname image
1544 Also you could set hostname in configuration file:
1546 # cat mkosi.default
1548 ...
1549 [Output]
1550 Hostname=image
1551 ...
1552
1554 mkosi is packaged for various distributions: Debian, Ubuntu, Arch Lin‐
1555 ux, Fedora Linux, OpenMandriva, Gentoo. It is usually easiest to use
1556 the distribution package.
1557 The current version requires systemd 233 (or actually, systemd-nspawn
1559 of it).
1560 When not using distribution packages make sure to install the necessary
1562 dependencies. For example, on Fedora Linux you need:
1563 dnf install arch-install-scripts btrfs-progs debootstrap dosfstools edk2-ovmf e2fsprogs squashfs-tools gnupg python3 tar veritysetup xfsprogs xz zypper sbsigntools
1565 On Debian/Ubuntu it might be necessary to install the ubuntu-keyring,
1567 ubuntu-archive-keyring and/or debian-archive-keyring packages explicit‐
1568 ly, in addition to debootstrap, depending on what kind of distribution
1569 images you want to build. debootstrap on Debian only pulls in the De‐
1570 bian keyring on its own, and the version on Ubuntu only the one from
1571 Ubuntu.
1572 Note that the minimum required Python version is 3.7.
1574
1576 • Primary mkosi git repository on GitHub (https://github.com/sys‐
1577 temd/mkosi/)
1578 • mkosi — A Tool for Generating OS Images (http://0point‐
1580 er.net/blog/mkosi-a-tool-for-generating-os-images.html) introductory
1581 blog post by Lennart Poettering
1582 • The mkosi OS generation tool (https://lwn.net/Articles/726655/) story
1584 on LWN
1585
1587 systemd-nspawn(1), dnf(8), debootstrap(8)
1588
1590 The mkosi Authors.
1591 2016- mkosi(1)