1mkosi(1)                                                              mkosi(1)
2
3
4

NAME

6       mkosi — Build Bespoke OS Images
7

SYNOPSIS

9       mkosi [options...] build
10
11       mkosi [options...] clean
12
13       mkosi [options...] summary
14
15       mkosi [options...] shell [command line...]
16
17       mkosi [options...] boot [nspawn settings...]
18
19       mkosi [options...] qemu
20
21       mkosi [options...] ssh
22
23       mkosi [options...] serve
24
25       mkosi [options...] bump
26
27       mkosi [options...] genkey
28
29       mkosi [options...] help
30

DESCRIPTION

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
36   Command Line Verbs
37       The following command line verbs are known:
38
39       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
45       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
49       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
55       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
63       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
68       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
75       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
81       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
89       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
98       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
102       help   This  verb  is equivalent to the --help switch documented below:
103              it shows a brief usage explanation.
104
105   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
112                          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
215   Supported output formats
216       The following output formats are supported:
217
218       • Raw GPT disk image, with ext4 as root (gpt_ext4)
219
220       • Raw GPT disk image, with xfs as root (gpt_xfs)
221
222       • Raw GPT disk image, with btrfs as root (gpt_btrfs)
223
224       • Raw GPT disk image, with squashfs as read-only root (gpt_squashfs)
225
226       • Plain squashfs image, without  partition  table,  as  read-only  root
227         (plain_squashfs)
228
229       • Plain directory, containing the OS tree (directory)
230
231       • btrfs  subvolume,  with  separate  subvolumes  for /var, /home, /srv,
232         /var/tmp (subvolume)
233
234       • Tar archive (tar)
235
236       • CPIO archive (cpio) in the format appropriate for a kernel initrd
237
238       When a GPT disk image is created, the following additional options  are
239       available:
240
241       • A swap partition may be added in
242
243       • The image may be made bootable on EFI and BIOS systems
244
245       • Separate partitions for /srv and /home may be added in
246
247       • The  root, /srv and /home partitions may optionally be encrypted with
248         LUKS.
249
250       • A dm-verity partition may be added in that adds runtime integrity da‐
251         ta for the root partition
252
253   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
261       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
266   [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
274       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
284       Mirror=, --mirror=, -m
285              The mirror to use for  downloading  the  distribution  packages.
286              Expects a mirror URL as argument.
287
288       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
298       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
306       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
314       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
319   [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
332       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
338       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
351       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
359       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
368       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
382       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
398       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
406       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
411       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
420       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
432       SecureBoot=, --secure-boot
433              Sign the resulting kernel/initrd image for UEFI SecureBoot.
434
435       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
439       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
443       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
448       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
453       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
463       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
471       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
483       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
504       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
513       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
522       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
527       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
533       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
540       Hostname=, --hostname=
541              Set the image’s hostname to the specified name.
542
543       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
556       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
567       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
572       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
579       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
588       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
597       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
603       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
611       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
616   [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
635       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
664       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
671       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
680       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
688       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
704       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
715       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
722       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
726       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
733       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
743       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
750       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
763       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
775       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
786       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
799       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
805       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
810       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
815       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
821       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
831       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
842       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
852       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
863       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
875       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
881       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
888       SourceResolveSymlinksFinal=, --source-resolve-symlinks-final
889              Same  as SourceResolveSymlinks=, but for the final image instead
890              of the build image.
891
892       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
903       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
911   [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
923       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
929       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
934       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
938       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
942       SrvSize=, --srv-size=
943              Similar to RootSize=, configures the size of the /srv partition.
944              If omitted, no separate /srv partition is created.
945
946   [Validation] Section
947       Checksum=, --checksum
948              Generate  a SHA256SUMS file of all generated artifacts after the
949              build is complete.
950
951       Sign=, --sign
952              Sign the generated SHA256SUMS using gpg after completion.
953
954       Key=, --key=
955              Select the gpg key to use for signing SHA256SUMS.  This key must
956              be already present in the gpg keyring.
957
958       BMap=, --bmap
959              Generate  a bmap file for usage with bmaptool from the generated
960              image file.
961
962   [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
967       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
980       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
985       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
989       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
994       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
1000       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
1008       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
1017       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
1025       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
1032       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
1041       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
1045       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
1052   Commandline-only Options
1053       Those settings cannot be configured in the configuration files.
1054
1055       --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
1062       --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
1073       --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
1080       --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
1085       --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
1102       --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
1107       --version
1108              Show package version.
1109
1110       --help, -h
1111              Show brief usage information.
1112
1113       --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
1120   Supported distributions
1121       Images may be created containing installations of the following operat‐
1122       ing systems:
1123
1124Fedora Linux
1125
1126Debian
1127
1128Ubuntu
1129
1130Arch Linux
1131
1132openSUSE
1133
1134Mageia
1135
1136CentOS
1137
1138Clear Linux
1139
1140Photon
1141
1142OpenMandriva
1143
1144Rocky Linux
1145
1146Alma Linux
1147
1148Gentoo
1149
1150       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
1162       Currently, Fedora Linux packages all relevant tools as of Fedora 28.
1163
1164   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
1168       All generated GPT disk images may be booted in a  local  container  di‐
1169       rectly with:
1170
1171              systemd-nspawn -bi image.raw
1172
1173       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
1177              qemu-kvm -m 512 -smp 2 -bios /usr/share/edk2/ovmf/OVMF_CODE.fd -drive format=raw,file=image.raw
1178
1179       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
1183       All directory or btrfs subvolume images may be booted directly with:
1184
1185              systemd-nspawn -bD image
1186

Files

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
1194       • 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
1204         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
1210         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
1219       • 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
1225         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
1229       • 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
1235         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
1239mkosi.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
1255         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
1266         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
1269       • 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
1285       • 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
1297       • 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
1315       • The mkosi.mksquashfs-tool script, if it exists, will be called  wher‐
1316         ever mksquashfs would be called.
1317
1318       • 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
1323       • 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
1326       • 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
1340       • 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
1349       • 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
1357       • 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
1365       • 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
1372       • 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
1377       • 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
1390       • 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
1394       All these files are optional.
1395
1396       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

BUILD PHASES

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
1406       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
1418       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
1423       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

CACHING

1429       mkosi supports three different caches for speeding  up  repetitive  re-
1430       building of images.  Specifically:
1431
1432       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
1438       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
1451       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
1457       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

ENVIRONMENT VARIABLES

1465       The  build  script mkosi.build receives the following environment vari‐
1466       ables:
1467
1468       • $SRCDIR contains the path to the sources to build.
1469
1470       • $DESTDIR is a directory into which any  artifacts  generated  by  the
1471         build script shall be placed.
1472
1473       • $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
1478       • $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
1483       • $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
1488       • $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

EXAMPLES

1493       Create and run a raw GPT image with ext4, as image.raw:
1494
1495              # mkosi --bootable --incremental boot
1496
1497       Create and run a bootable btrfs GPT image, as foobar.raw:
1498
1499              # mkosi --format gpt_btrfs --bootable -o foobar.raw
1500              # mkosi --output foobar.raw boot
1501              # mkosi --output foobar.raw qemu
1502
1503       Create and run a Fedora Linux image into a plain directory:
1504
1505              # mkosi --distribution fedora --format directory boot
1506
1507       Create a compressed image image.raw.xz and add a checksum file, and in‐
1508       stall SSH into it:
1509
1510              # mkosi --distribution fedora --format gpt_squashfs --checksum --compress --package=openssh-clients
1511
1512       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
1516              # cat >mkosi.default <<EOF
1517              [Distribution]
1518              Distribution=fedora
1519              Release=24
1520
1521              [Output]
1522              Format=gpt_btrfs
1523              Bootable=yes
1524
1525              [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
1541       To create a Fedora Linux image with hostname:
1542
1543              # mkosi --distribution fedora --hostname image
1544
1545       Also you could set hostname in configuration file:
1546
1547              # cat mkosi.default
1548              ...
1549              [Output]
1550              Hostname=image
1551              ...
1552

REQUIREMENTS

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
1558       The  current  version requires systemd 233 (or actually, systemd-nspawn
1559       of it).
1560
1561       When not using distribution packages make sure to install the necessary
1562       dependencies.  For example, on Fedora Linux you need:
1563
1564              dnf install arch-install-scripts btrfs-progs debootstrap dosfstools edk2-ovmf e2fsprogs squashfs-tools gnupg python3 tar veritysetup xfsprogs xz zypper sbsigntools
1565
1566       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
1573       Note that the minimum required Python version is 3.7.
1574

REFERENCES

1576       • Primary  mkosi  git  repository  on  GitHub  (https://github.com/sys
1577         temd/mkosi/)
1578
1579       • 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
1583       • The mkosi OS generation tool (https://lwn.net/Articles/726655/) story
1584         on LWN
1585

SEE ALSO

1587       systemd-nspawn(1), dnf(8), debootstrap(8)
1588

AUTHORS

1590       The mkosi Authors.
1591
1592
1593
1594                                     2016-                            mkosi(1)
Impressum