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

NAME

6       mkosi - Build Legacy-Free 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

DESCRIPTION

22       mkosi is a tool for easily building legacy-free OS images.  It’s a fan‐
23       cy wrapper around dnf --installroot, debootstrap, pacstrap  and  zypper
24       that may generate disk images with a number of bells and whistles.
25
26   Supported output formats
27       The following output formats are supported:
28
29       · Raw GPT disk image, with ext4 as root (gpt_ext4)
30
31       · Raw GPT disk image, with xfs as root (gpt_xfs)
32
33       · Raw GPT disk image, with btrfs as root (gpt_btrfs)
34
35       · Raw GPT disk image, with squashfs as read-only root (gpt_squashfs)
36
37       · Plain  squashfs  image,  without  partition  table, as read-only root
38         (plain_squashfs)
39
40       · Plain directory, containing the OS tree (directory)
41
42       · btrfs subvolume, with separate  subvolumes  for  /var,  /home,  /srv,
43         /var/tmp (subvolume)
44
45       · Tarball (tar)
46
47       When  a GPT disk image is created, the following additional options are
48       available:
49
50       · A swap partition may be added in
51
52       · The image may be made bootable on EFI and BIOS systems
53
54       · Separate partitions for /srv and /home may be added in
55
56       · The root, /srv and /home partitions may optionally be encrypted  with
57         LUKS.
58
59       · A dm-verity partition may be added in that adds runtime integrity da‐
60         ta for the root partition
61
62   Other features
63       · Optionally, create an SHA256SUMS checksum file for the result, possi‐
64         bly even signed via gpg.
65
66       · Optionally, place a specific .nspawn settings file along with the re‐
67         sult.
68
69       · Optionally, build a local project’s source tree in the image and  add
70         the result to the generated image (see below).
71
72       · Optionally, share RPM/DEB package cache between multiple runs, in or‐
73         der to optimize build speeds.
74
75       · Optionally, the resulting image may be compressed with XZ.
76
77       · Optionally, the resulting image may be converted into  a  QCOW2  file
78         suitable for qemu storage.
79
80       · Optionally, btrfs’ read-only flag for the root subvolume may be set.
81
82       · Optionally, btrfs’ compression may be enabled for all created subvol‐
83         umes.
84
85       · By default images are created without all files marked as  documenta‐
86         tion in the packages, on distributions where the package manager sup‐
87         ports this.  Use the --with-docs flag to build  an  image  with  docs
88         added.
89
90   Command Line Verbs
91       The following command line verbs are known:
92
93       build  This  builds  the  image, based on the settings passed in on the
94              command line or read from a mkosi.default file, see below.  This
95              verb  is  the  default if no verb is explicitly specified.  This
96              command must be executed as root.
97
98       clean  Remove build artifacts generated on a previous build.   If  com‐
99              bined  with -f, also removes incremental build cache images.  If
100              -f is specified twice, also removes any package cache.
101
102       summary
103              Outputs a human-readable summary of all options used for  build‐
104              ing  an  image.   This will parse the command line and mkosi.de‐
105              fault file as it would do on build, but only output what  it  is
106              configured for and not actually build anything.`
107
108       shell  This  builds  the image if it is not build yet, and then invokes
109              systemd-nspawn to acquire an interactive shell prompt in it.  If
110              this  verb  is  used  an  optional command line may be specified
111              which is then invoked in place of the shell  in  the  container.
112              Combine  this with -f in order to rebuild the image uncondition‐
113              ally before acquiring the shell, see below.  This  command  must
114              be executed as root.
115
116       boot   Similar  to  shell  but boots the image up using systemd-nspawn.
117              If this verb is used an optional command line may  be  specified
118              which  is  passed as “kernel command line” to the init system in
119              the image.
120
121       qemu   Similar to boot but uses qemu to boot up the image, i.e. instead
122              of  container  virtualization  VM  virtualization is used.  This
123              verb is only supported on images that  contain  a  boot  loader,
124              i.e. those built with --bootable (see below).  This command must
125              be executed as root unless the image already exists  and  -f  is
126              not specified.
127
128       ssh    When the image is built with the --ssh option, this command con‐
129              nects to a booted (boot, qemu verbs) container/VM via SSH.  Make
130              sure  to  run  mkosi ssh with the same config as mkosi build was
131              run with so that it has the necessary information  available  to
132              connect to the running container/VM via SSH.
133
134       help   This  verb  is equivalent to the --help switch documented below:
135              it shows a brief usage explanation.
136
137   Command Line Parameters
138       The following command line parameters are understood.  Note  that  many
139       of  these parameters can also be set in the mkosi.default file, for de‐
140       tails see the table below.
141
142       --distribution=, -d
143              The distribution to install in the image.  Takes one of the fol‐
144              lowing   arguments:  fedora,  debian,  ubuntu,  arch,  opensuse,
145              mageia, centos, clear, photon, openmandriva.  If not  specified,
146              defaults to the distribution of the host.
147
148       --release=, -r
149              The  release  of  the distribution to install in the image.  The
150              precise syntax of the argument this takes depends on the distri‐
151              bution  used, and is either a numeric string (in case of Fedora,
152              CentOS, ..., e.g. 29), or a distribution version name  (in  case
153              of  Debian,  Ubuntu, ..., e.g. artful).  If neither this option,
154              not --distribution= is specified, defaults to  the  distribution
155              version of the host.  If the distribution is specified, defaults
156              to a recent version of it.
157
158       --mirror=, -m
159              The mirror to use for  downloading  the  distribution  packages.
160              Expects a mirror URL as argument.
161
162       --repositories=
163              Additional package repositories to use during installation.  Ex‐
164              pects one or more URLs as argument, separated by  commas.   This
165              option  may  be  used  multiple times, in which case the list of
166              repositories to use is combined.  Use “!*” to remove all reposi‐
167              tories  from  to the list or use e.g. “!repo-url” to remove just
168              one specific repository.  For Arch Linux,  additional  reposito‐
169              ries  must  be  passed  in  the  form  <name>::<url> (e.g. myre‐
170              po::https://myrepo.net).
171
172       --architecture=
173              The architecture to build the image for.  Note  that  this  cur‐
174              rently  only  works for architectures compatible with the host’s
175              architecture.
176
177       --format=, -t
178              The image format type to generate.  One of directory (for gener‐
179              ating  OS  images inside a local directory), subvolume (similar,
180              but as a btrfs subvolume), tar (similar, but a  tarball  of  the
181              image is generated), gpt_ext4 (a block device image with an ext4
182              file system inside a GPT partition table), gpt_xfs (similar, but
183              with  an xfs file system), gpt_btrfs (similar, but with an btrfs
184              file system), gpt_squashfs (similar, but with  a  squashfs  file
185              system),  plain_squashfs (a plain squashfs file system without a
186              partition table).
187
188       --output=, -o
189              Path for the output image file to generate.  Takes a relative or
190              absolute path where the generated image will be placed.  If nei‐
191              ther this option nor --output-dir= is used (see below), the  im‐
192              age  is  generated  under  the name image, but its name suffixed
193              with an  appropriate  file  suffix  (e.g. image.raw.xz  in  case
194              gpt_ext4 is used in combination with --xz).
195
196       --output-dir=, -O
197              Path  to  a  directory  where  to  place all generated artifacts
198              (i.e. the SHA256SUMS file and similar).  If this is  not  speci‐
199              fied and a directory mkosi.output/ exists in the local directory
200              it is automatically used for this purpose.  If this is not spec‐
201              ified  and such a directory does not exist, all output artifacts
202              are placed adjacent to the output image file.
203
204       --force, -f
205              Replace the output file if it already exists, when  building  an
206              image.  By default when building an image and an output artifact
207              already exists mkosi  will  refuse  operation.   Specify  -f  to
208              delete  all build artifacts from a previous run before re-build‐
209              ing the image.  If incremental builds are enabled  (see  below),
210              specifying  this option twice will ensure the intermediary cache
211              files are removed, too, before the re-build is initiated.  If  a
212              package cache is used (see below), specifying this option thrice
213              will ensure the package cache is removed  too,  before  the  re-
214              build  is  initiated.  For the clean operation -f has a slightly
215              different effect: by default the verb will only remove build ar‐
216              tifacts from a previous run, when specified once the incremental
217              cache files are deleted too, and when specified twice the  pack‐
218              age cache is also removed.
219
220       --gpt-first-lba
221              Override the first usable LBA (Logical Block Address) within the
222              GPT header.  This defaults to 2048 which is actually the desired
223              value.  However, some tools, e.g. the prl_disk_tool utility from
224              the Parallels virtualization suite require this to be set to 34,
225              otherwise they might fail to resize the disk image and/or parti‐
226              tions inside it.
227
228       --bootable, -b
229              Generate a bootable image.  By default this will generate an im‐
230              age  bootable  on UEFI systems.  Use --boot-protocols= to select
231              support for a different boot protocol.
232
233       --boot-protocols=
234              Pick one or more boot protocols to  support  when  generating  a
235              bootable  image, as enabled with --bootable above.  Takes a com‐
236              ma-separated list of uefi or bios.  May be specified  more  than
237              once  in  which case the specified lists are merged.  If uefi is
238              specified the sd-boot UEFI boot loader is used, if bios is spec‐
239              ified  the GNU Grub boot loader is used.  Use “!*” to remove all
240              previously added protocols or “!protocol” to remove  one  proto‐
241              col.
242
243       --kernel-command-line=
244              Use the specified kernel command line when building bootable im‐
245              ages.  By default command line arguments get appended.   To  re‐
246              move  all  arguments from the current list pass “!*”.  To remove
247              specific arguments add a space separated list of  “!”   prefixed
248              arguments.   For  example  adding  “!*  console=ttyS0  rw”  to a
249              mkosi.default file or the command line  arguments  passes  “con‐
250              sole=ttyS0  rw”  to  the  kernel in any case.  Just adding “con‐
251              sole=ttyS0 rw” would append these two arguments  to  the  kernel
252              command  line  created  by lower priority configuration files or
253              previous –kernel-command-line command line arguments.
254
255       --secure-boot
256              Sign the resulting kernel/initrd image for UEFI SecureBoot
257
258       --secure-boot-key=
259              Path to the PEM file containing the secret key for  signing  the
260              UEFI kernel image, if --secure-boot is used.
261
262       --secure-boot-certificate=
263              Path to the X.509 file containing the certificate for the signed
264              UEFI kernel image, if --secure-boot is used.
265
266       --read-only
267              Make root file system  read-only.   Only  applies  to  gpt_ext4,
268              gpt_xfs,  gpt_btrfs,  subvolume  output  formats, and implied on
269              gpt_squashfs and plain_squashfs.
270
271       --minimize
272              Attempt to make the resulting root file system as small as  pos‐
273              sible  by  removing  free space from the file system.  Only sup‐
274              ported for gpt_ext4 and gpt_btrfs.  For ext4 this relies on  re‐
275              size2fs -M, which reduces the free disk space but is not perfect
276              and generally leaves some free space.  For btrfs the results are
277              optimal and no free space is left.
278
279       --encrypt
280              Encrypt  all partitions in the file system or just the root file
281              system.  Takes either all or data as argument.  If all the root,
282              /home  and  /srv  file  systems  will  be  encrypted  using  dm-
283              crypt/LUKS (with its default settings).  If data the  root  file
284              system  will be left unencrypted, but /home and /srv will be en‐
285              crypted.    The   passphrase   to   use   is   read   from   the
286              mkosi.passphrase  file in the current working directory (see be‐
287              low).  Note that the UEFI System Partition (ESP) containing  the
288              boot loader and kernel to boot is never encrypted since it needs
289              to be accessible by the firmware.
290
291       --verity
292              Add an “Verity” integrity partition to the image.   If  enabled,
293              the  root partition is protected with dm-verity against off-line
294              modification, the verification data is placed in  an  additional
295              GPT partition.  Implies --read-only.
296
297       --compress=
298              Compress the generated file systems.  Only applies to gpt_btrfs,
299              subvolume, gpt_squashfs, plain_squashfs.   Takes  one  of  zlib,
300              lzo,  zstd, lz4, xz or a boolean value as argument.  If the lat‐
301              ter is used compression is enabled/disabled and the default  al‐
302              gorithm  is  used.   In case of the squashfs output formats com‐
303              pression is implied, however this option may be used  to  select
304              the algorithm.
305
306       --mksquashfs=
307              Set  the path to the mksquashfs executable to use.  This is use‐
308              ful in case the parameters for the tool shall be  augmented,  as
309              the  tool may be replaced by a script invoking it with the right
310              parameters, this way.
311
312       --xz   Compress the resulting image with  xz.   This  only  applies  to
313              gpt_ext4,  gpt_xfs,  gpt_btrfs,  gpt_squashfs and is implied for
314              tar.  Note that when applied to the  block  device  image  types
315              this  means the image cannot be started directly but needs to be
316              decompressed first.  This also means that the shell, boot,  qemu
317              verbs are not available when this option is used.
318
319       --qcow2
320              Encode  the  resulting image as QEMU QCOW2 image.  This only ap‐
321              plies to gpt_ext4, gpt_xfs, gpt_btrfs, gpt_squashfs.  QCOW2  im‐
322              ages  can be read natively by qemu, but not by the Linux kernel.
323              This means the shell and boot verbs are not available when  this
324              option is used, however qemu will work.
325
326       --hostname=
327              Set the image’s hostname to the specified name.
328
329       --without-unified-kernel-images
330              If specified, mkosi does not build unified kernel images and in‐
331              stead installs kernels with a separate initrd  and  boot  loader
332              config to the efi or bootloader partition.
333
334       --hostonly-initrd
335              If  specified, mkosi will run the tool to create the initrd such
336              that a non-generic initrd is created that will only be  able  to
337              run  on the system mkosi is run on.  Currently mkosi uses dracut
338              for all supported distributions except Clear Linux and this  op‐
339              tion translates to enabling dracut’s hostonly option.
340
341       --no-chown
342              By default, if mkosi is run inside a sudo environment all gener‐
343              ated artifacts have their UNIX user/group ownership  changed  to
344              the  user  which  invoked  sudo.   With  this option this may be
345              turned off and all generated files are owned by root.
346
347       --tar-strip-selinux-context
348              If running on a SELinux-enabled system (Fedora,  CentOS),  files
349              inside  the  container  are tagged with SELinux context extended
350              attributes (xattrs), which may interfere with host SELinux rules
351              in  building  or  further  container import stages.  This option
352              strips SELinux context attributes from  the  resulting  tar  ar‐
353              chive.
354
355       --incremental, -i
356              Enable  incremental  build  mode.  This only applies if the two-
357              phase mkosi.build build script logic is used.  In this  mode,  a
358              copy  of  the OS image is created immediately after all OS pack‐
359              ages are unpacked but before the mkosi.build script  is  invoked
360              in the development container.  Similar a copy of the final image
361              is created immediately  before  the  build  artifacts  from  the
362              mkosi.build  script are copied in.  On subsequent invocations of
363              mkosi with the -i switch these cached images may be used to skip
364              the  OS  package unpacking, thus drastically speeding up repeti‐
365              tive build times.  Note that when this is used  and  a  pair  of
366              cached  incremental images exists they are not automatically re‐
367              generated, even if options such as --packages= are modified.  In
368              order  to  force  rebuilding of these cached images, combined -i
369              with -ff, which ensures the cached images are removed first, and
370              then re-created.
371
372       --package=, -p
373              Install the specified distribution packages (i.e. RPM, DEB, ...)
374              in the image.  Takes a comma separated list of  packages.   This
375              option  may  be  used multiple times in which case the specified
376              package list is combined.  Packaged specified this way  will  be
377              installed  both  in the development and the final image (see be‐
378              low).  Use --build-package= (see below) to specify packages that
379              shall  only  be used for the image generated in the build image,
380              but that shall not appear in the final image.  To remove a pack‐
381              age e.g. added by a mkosi.default configuration file prepend the
382              package name with a ! letter.  For example -p  “!apache2”  would
383              remove  the  apache2 package.  To replace the apache2 package by
384              the httpd package just add -p “!apache2,httpd”  to  the  command
385              line arguments.  To remove all packages use “!*”.
386
387       --with-docs
388              Include documentation in the image built.  By default if the un‐
389              derlying distribution package manager supports it  documentation
390              is  not included in the image built.  The $WITH_DOCS environment
391              variable passed to the mkosi.build script indicates whether this
392              option was used or not, see below.
393
394       --without-tests, -T
395              If set the $WITH_TESTS environment variable is set to 0 when the
396              mkosi.build script is invoked.  This is supposed to be  used  by
397              the  build  script  to bypass any unit or integration tests that
398              are normally run during the source  build  process.   Note  that
399              this  option  has  no effect unless the mkosi.build build script
400              honors it.
401
402       --cache=
403              Takes a path to a directory to use as package cache for the dis‐
404              tribution package manager used.  If this option is not used, but
405              a mkosi.cache/ directory is found in the local directory  it  is
406              automatically  used  for this purpose (also see below).  The di‐
407              rectory configured this way is mounted into both the development
408              and the final image while the package manager is running.
409
410       --extra-tree=
411              Takes  a  path  to a directory to copy on top of the OS tree the
412              package manager generated.  Use this  to  override  any  default
413              configuration  files shipped with the distribution.  If this op‐
414              tion is not used, but the mkosi.extra/ directory is found in the
415              local  directory it is automatically used for this purpose (also
416              see below).  Instead of a directory a tar file may be  specified
417              too.   In  this  case it is unpacked into the OS tree before the
418              package manager is invoked.  This mode of operation allows  set‐
419              ting  permissions  and  file ownership explicitly, in particular
420              for projects stored in a version  control  system  such  as  git
421              which  does  retain full file ownership and access mode metadata
422              for committed files.  If a tar file mkosi.extra.tar is found  in
423              the local directory it automatically used for this purpose.
424
425       --skeleton-tree=
426              Takes  a path to a directory to copy into the OS tree before in‐
427              voking the package manager.  Use this to insert files and direc‐
428              tories  into the OS tree before the package manager installs any
429              packages.  If this option is not used, but  the  mkosi.skeleton/
430              directory  is  found  in the local directory it is automatically
431              used for this purpose (also see below).  As with the extra  tree
432              logic  above, instead of a directory a tar file may be used too,
433              and mkosi.skeleton.tar is automatically used.
434
435       --build-script=
436              Takes a path to an executable that is used as build  script  for
437              this  image.   If  this option is used the build process will be
438              two-phased instead of single-phased (see below).  The  specified
439              script  is copied onto the development image and executed inside
440              an systemd-nspawn container environment.  If this option is  not
441              used,  but  the mkosi.build file found in the local directory it
442              is automatically used for this purpose (also see below).
443
444       --build-sources=
445              Takes a path of a source tree to copy into the  development  im‐
446              age,  if  a  build script is used.  This only applies if a build
447              script is used,  and  defaults  to  the  local  directory.   Use
448              --source-file-transfer=  to  configure  how the files are trans‐
449              ferred from the host to the container image.
450
451       --build-dir=
452              Takes a path of a directory to use as build directory for  build
453              systems  that  support  out-of-tree builds (such as Meson).  The
454              directory used this way is shared between repeated  builds,  and
455              allows  the  build  system  to  reuse  artifacts (such as object
456              files, executable, ...) generated on previous invocations.  This
457              directory  is  mounted into the development image when the build
458              script is invoked.  The build script can find the path  to  this
459              directory in the $BUILDDIR environment variable.  If this option
460              is not specified, but a directory mkosi.builddir/ exists in  the
461              local  directory it is automatically used for this purpose (also
462              see below).
463
464       --include-directory
465              Takes a path of a directory to use  as  the  include  directory.
466              This  directory  is  mounted  at  /usr/include when building the
467              build image and when running the build script.  This  means  all
468              include  files  installed to /usr/include will be stored in this
469              directory.  This is useful to make include  files  available  on
470              the host system for use by language servers to provide code com‐
471              pletion.  If this option  is  not  specified,  but  a  directory
472              mkosi.includedir/ exists in the local directory, it is automati‐
473              cally used for this purpose (also see below).
474
475       --install-directory
476              Takes a path of a directory to use  as  the  install  directory.
477              The  directory used this way is shared between builds and allows
478              the build system to not have to reinstall files  that  were  al‐
479              ready  installed  by  a  previous  build and didn’t change.  The
480              build script can find the path to this directory in the $DESTDIR
481              environment  variable.   If  this option is not specified, but a
482              directory mkosi.installdir exists in the local directory, it  is
483              automatically used for this purpose (also see below).
484
485       --build-package=
486              Similar  to  --package=, but configures packages to install only
487              in the first phase of the build,  into  the  development  image.
488              This  option  should  be used to list packages containing header
489              files, compilers, build systems, linkers and other  build  tools
490              the  mkosi.build script requires to operate.  Note that packages
491              listed here are only included in the image  created  during  the
492              first  phase  of  the  build, and are absent in the final image.
493              use --package= to list packages that shall be included in  both.
494              Packages  are  appended to the list.  Packages prefixed with “!”
495              are removed from the list.  “!*” removes all packages  from  the
496              list.
497
498       --skip-final-phase=
499              Causes the (second) final image build stage to be skipped.  This
500              is useful in combination with a build script, for when you  care
501              about  the artifacts that were created locally in $BUILDDIR, but
502              ultimately plan to discard the final image.
503
504       --prepare-script=
505              Takes a path to an executable that is invoked inside  the  image
506              right  after  installing  the software packages.  It is the last
507              step before the image is cached  (if  incremental  mode  is  en‐
508              abled).  This script is invoked inside a systemd-nspawn contain‐
509              er environment, and thus does not have access to host resources.
510              If  this option is not used, but an executable script mkosi.pre‐
511              pare is found in the local directory, it is  automatically  used
512              for this purpose (also see below).
513
514       --postinst-script=
515              Takes  a  path to an executable that is invoked inside the final
516              image right after copying in the build  artifacts  generated  in
517              the  first  phase of the build.  This script is invoked inside a
518              systemd-nspawn container environment, and thus does not have ac‐
519              cess to host resources.  If this option is not used, but an exe‐
520              cutable mkosi.postinst is found in the local  directory,  it  is
521              automatically used for this purpose (also see below).
522
523       --finalize-script=
524              Takes  a path to an executable that is invoked outside the final
525              image right after copying in the build  artifacts  generated  in
526              the  first  phase  of  the  build, and after having executed the
527              mkosi.postinst script (see above).  This script is  invoked  di‐
528              rectly in the host environment, and hence has full access to the
529              host’s resources.  If this option is not used, but an executable
530              mkosi.finalize  is found in the local directory, it is automati‐
531              cally used for this purpose (also see below).
532
533       --source-file-transfer=
534              Configures how the source file tree (as configured with --build-
535              sources=)  is  transferred  into  the container image during the
536              first phase of the build.  Takes one of copy-all  (to  copy  all
537              files from the source tree), copy-git-cached (to copy only those
538              files git-ls-files --cached lists), copy-git-others (to copy on‐
539              ly those files git-ls-files --others lists), mount to bind mount
540              the source tree directly.  Defaults to copy-git-cached if a  git
541              source  tree  is detected, otherwise copy-all.  When you specify
542              copy-git-more, it is the same as copy-git-cached, except it also
543              includes the .git/ directory.
544
545       --source-file-transfer-final=
546              Same  as  --source-file-transfer but for the final image instead
547              of the build image.  Takes the  same  values  as  --source-file-
548              transfer  except mount.  By default, sources are not copied into
549              the final image.
550
551       --with-network
552              Enables network connectivity while the build script  mkosi.build
553              is  invoked.   By default, the build script runs with networking
554              turned off.  The $WITH_NETWORK environment variable is passed to
555              the  mkosi.build  build  script  indicating whether the build is
556              done with or without this option.  If specified  as  --with-net‐
557              work=never  the package manager is instructed not to contact the
558              network for updating package data.  This provides a minimal lev‐
559              el  of reproducibility, as long as the package data cache is al‐
560              ready fully populated.
561
562       --settings=
563              Specifies a .nspawn settings file for systemd-nspawn to  use  in
564              the boot and shell verbs, and to place next to the generated im‐
565              age file.  This is useful to configure the systemd-nspawn  envi‐
566              ronment  when the image is run.  If this setting is not used but
567              an mkosi.nspawn file found in the local directory it is automat‐
568              ically used for this purpose (also see below).
569
570       --root-size=
571              Takes  a  size in bytes for the root file system.  The specified
572              numeric value may be suffixed with K, M, G  to  indicate  kilo-,
573              mega-  and gigabytes (all to the base of 1024).  This applies to
574              output formats gpt_ext4, gpt_xfs, gpt_btrfs.   Defaults  to  1G,
575              except for gpt_xfs where it defaults to 1.3G.
576
577       --esp-size=
578              Similar,  and  configures  the size of the UEFI System Partition
579              (ESP).  This is only relevant if the --bootable option  is  used
580              to generate a bootable image.  Defaults to 256M.
581
582       --swap-size=
583              Similar,  and configures the size of a swap partition on the im‐
584              age.  If omitted no swap partition is created.
585
586       --home-size=
587              Similar, and configures the size of  the  /home  partition.   If
588              omitted no separate /home partition is created.
589
590       --srv-size=
591              Similar,  and  configures  the  size  of the /srv partition.  If
592              omitted no separate /srv partition is created.
593
594       --checksum
595              Generate a SHA256SUMS file of all generated artifacts after  the
596              build is complete.
597
598       --sign Sign the generated SHA256SUMS using gpg after completion.
599
600       --key= Select  the  gpg key to use for signing SHA256SUMS.  This key is
601              required to exist in the gpg keyring already.
602
603       --bmap Generate a bmap file for usage with bmaptool from the  generated
604              image file.
605
606       --password=
607              Set  the password of the root user.  By default the root account
608              is locked.  If this option is not used but a  file  mkosi.rootpw
609              exists in the local directory the root password is automatically
610              read from it.
611
612       --password-is-hashed
613              Indicate that the password supplied for the root  user  has  al‐
614              ready  been  hashed, so that the string supplied with --password
615              or mkosi.rootpw will be written to /etc/shadow literally.
616
617       --autologin
618              Enable autologin for the root user on pts/0 (nspawn), tty1  (QE‐
619              MU)   and   ttyS0   (QEMU   with   –qemu-headless)  by  patching
620              /etc/pam.d/login.
621
622       --extra-search-paths=
623              List of colon-separated paths to look for tools in, before using
624              the regular $PATH search path.
625
626       --directory=, -C
627              Takes  a  path to a directory.  mkosi switches to this directory
628              before doing anything.  Note that the various mkosi.* files  are
629              searched  for only after changing to this directory, hence using
630              this option is an effective way to build a project located in  a
631              specific directory.
632
633       --default=
634              Loads  additional  settings  from  the  specified settings file.
635              Most command line options may also be configured in  a  settings
636              file.   See  the  table  below to see which command line options
637              match which settings file option.  If this option is  not  used,
638              but  a  file mkosi.default is found in the local directory it is
639              automatically used for this purpose.  If a setting is configured
640              both  on  the command line and in the settings file, the command
641              line generally wins, except for options taking  lists  in  which
642              case both lists are combined.
643
644       --all, -a
645              Iterate  through all files mkosi.* in the mkosi.files/ subdirec‐
646              tory, and build each as if  --default=mkosi.files/mkosi....  was
647              invoked.   This is a quick way to build a large number of images
648              in one go.  Any  additional  specified  command  line  arguments
649              override the relevant options in all files processed this way.
650
651       --all-directory=
652              If  specified, overrides the directory the --all logic described
653              above looks for settings files in.  If unspecified, defaults  to
654              mkosi.files/ in the current working directory (see above).
655
656       --version
657              Show package version.
658
659       --help, -h
660              Show brief usage information.
661
662       --qemu-headless=
663              When used with the build verb, this option adds console=ttyS0 to
664              the image’s kernel command line and sets the  terminal  type  of
665              the serial console in the image to the terminal type of the host
666              (more specifically, the value of the TERM  environment  variable
667              passed  to  mkosi).   This makes sure that all terminal features
668              such as colors and shortcuts still work as  expected  when  con‐
669              necting  to the qemu VM over the serial console (for example via
670              -nographic).
671
672       When used with the qemu verb, this option adds the -nographic option to
673       qemu’s  command  line  so qemu starts a headless vm and connects to its
674       serial console from the current terminal instead of launching the VM in
675       a separate window.
676
677       --network-veth
678              When  used  with  the  boot or qemu verbs, this option creates a
679              virtual ethernet link between the  host  and  the  container/VM.
680              The  host  interface  is automatically picked up by systemd-net‐
681              workd   as   documented   in    systemd-nspawn’s    man    page:
682              https://www.freedesktop.org/software/systemd/man/systemd-
683              nspawn.html#-n
684
685       --ephemeral
686              When used with the shell, boot or qemu verbs, this  option  runs
687              the  specified  verb on a temporary snapshot of the output image
688              that is removed immediately when the container terminates.  Tak‐
689              ing  the  temporary  snapshot  is more efficient on file systems
690              that support subvolume snapshots or `reflinks' natively (“btrfs”
691              or  new “xfs”) than on more traditional file systems that do not
692              (“ext4”).
693
694       --ssh  If specified, installs and enables sshd in the final  image  and
695              generates a SSH keypair and adds the public key to root’s autho‐
696              rized keys in the final image.  The private  key  is  stored  in
697              mkosi’s  output  directory.   When building with this option and
698              running the image using mkosi boot or mkosi qemu, the mkosi  ssh
699              command can be used to connect to the container/VM via SSH.
700
701   Command Line Parameters and their Settings File Counterparts
702       Most  command  line  parameters  may also be placed in an mkosi.default
703       settings file (or any other file --default= is used on).  The following
704       table  shows  which command lines parameters correspond with which set‐
705       tings file options.
706
707       Command Line Param‐   mkosi.default  sec‐   mkosi.default  set‐
708       eter                  tion                  ting
709       ────────────────────────────────────────────────────────────────
710       --distribution=, -d   [Distribution]        Distribution=
711       --release=, -r        [Distribution]        Release=
712       --repositories=       [Distribution]        Repositories=
713       --mirror=, -m         [Distribution]        Mirror=
714       --architecture=       [Distribution]        Architecture=
715       --format=, -t         [Output]              Format=
716       --output=, -o         [Output]              Output=
717       --output-dir=, -O     [Output]              OutputDirectory=
718       --force, -f           [Output]              Force=
719       --bootable, -b        [Output]              Bootable=
720       --boot-protocols=     [Output]              BootProtocols=
721       --gpt-first-lba=      [Output]              GPTFirstLBA=
722       --kernel-command-     [Output]              KernelCommandLine=
723       line=
724       --secure-boot         [Output]              SecureBoot=
725       --secure-boot-key=    [Output]              SecureBootKey=
726       --secure-boot-cer‐    [Output]              SecureBootCertifi‐
727       tificate=                                   cate=
728       --read-only           [Output]              ReadOnly=
729       --encrypt=            [Output]              Encrypt=
730       --verity=             [Output]              Verity=
731       --compress=           [Output]              Compress=
732       --mksquashfs=         [Output]              Mksquashfs=
733       --xz                  [Output]              XZ=
734       --qcow2               [Output]              QCow2=
735       --no-chown            [Output]              NoChown=
736       --tar-strip-selin‐    [Output]              TarStripSELinuxCon‐
737       ux-context                                  text=
738       --hostname=           [Output]              Hostname=
739       --without-unified-    [Output]              WithUnifiedKerne‐
740       kernel-images                               lImages=
741       --hostonly-initrd     [Output]              HostonlyInitrd=
742       --package=            [Packages]            Packages=
743       --with-docs           [Packages]            WithDocs=
744       --without-tests, -T   [Packages]            WithTests=
745       --cache=              [Packages]            Cache=
746       --extra-tree=         [Packages]            ExtraTrees=
747       --skeleton-tree=      [Packages]            SkeletonTrees=
748       --build-script=       [Packages]            BuildScript=
749       --build-sources=      [Packages]            BuildSources=
750       --source-file-        [Packages]            SourceFileTransfer=
751       transfer=
752       --source-file-        [Packages]            SourceFileTransfer‐
753       transfer-final=                             Final=
754       --build-directory=    [Packages]            BuildDirectory=
755       --include-directo‐    [Packages]            IncludeDirectory=
756       ry=
757       --install-directo‐    [Packages]            InstallDirectory=
758       ry=
759       --build-packages=     [Packages]            BuildPackages=
760       --skip-final-phase=   [Packages]            SkipFinalPhase=
761       --postinst-script=    [Packages]            PostInstallation‐
762                                                   Script=
763       --finalize-script=    [Packages]            FinalizeScript=
764       --with-network        [Packages]            WithNetwork=
765       --settings=           [Packages]            NSpawnSettings=
766
767       --root-size=          [Partitions]          RootSize=
768       --esp-size=           [Partitions]          ESPSize=
769       --swap-size=          [Partitions]          SwapSize=
770       --home-size=          [Partitions]          HomeSize=
771       --srv-size=           [Partitions]          SrvSize=
772       --checksum            [Validation]          CheckSum=
773       --sign                [Validation]          Sign=
774       --key=                [Validation]          Key=
775       --bmap                [Validation]          BMap=
776       --password=           [Validation]          Password=
777       --password-is-        [Validation]          PasswordIsHashed=
778       hashed
779       --autologin           [Validation]          Autologin=
780       --extra-search-       [Host]                ExtraSearchPaths=
781       paths=
782       --qemu-headless       [Host]                QemuHeadless=
783       --network-veth        [Host]                NetworkVeth=
784       --ephemeral           [Host]                Ephemeral=
785       --ssh                 [Host]                Ssh=
786
787       Command line options that take no argument are not suffixed with a = in
788       their  long version in the table above.  In the mkosi.default file they
789       are modeled as boolean option that take either 1,  yes,  true  for  en‐
790       abling, and 0, no, false for disabling.
791
792   Supported distributions
793       Images may be created containing installations of the following OSes.
794
795       · Fedora
796
797       · Debian
798
799       · Ubuntu
800
801       · Arch Linux
802
803       · openSUSE
804
805       · Mageia
806
807       · CentOS
808
809       · Clear Linux
810
811       · Photon
812
813       · OpenMandriva
814
815       In theory, any distribution may be used on the host for building images
816       containing any other distribution, as long as the necessary  tools  are
817       available.   Specifically,  any  distribution that packages debootstrap
818       may be used to build Debian or Ubuntu images.   Any  distribution  that
819       packages  dnf  may  be used to build Fedora, Mageia or OpenMandriva im‐
820       ages.  Any distro that packages pacstrap may be used to build Arch Lin‐
821       ux  images.  Any distribution that packages zypper may be used to build
822       openSUSE images.  Any distribution that packages yum (or the newer  re‐
823       placement dnf) may be used to build CentOS images.
824
825       Currently, Fedora packages all relevant tools as of Fedora 28.
826
827   Compatibility
828       Generated images are legacy-free.  This means only GPT disk labels (and
829       no MBR disk labels) are supported, and only systemd based images may be
830       generated.
831
832       All  generated  GPT  disk images may be booted in a local container di‐
833       rectly with:
834
835              systemd-nspawn -bi image.raw
836
837       Additionally, bootable GPT disk images (as created with the  --bootable
838       flag) work when booted directly by EFI and BIOS systems, for example in
839       KVM via:
840
841              qemu-kvm -m 512 -smp 2 -bios /usr/share/edk2/ovmf/OVMF_CODE.fd -drive format=raw,file=image.raw
842
843       EFI bootable GPT images are larger than plain GPT images, as they addi‐
844       tionally  carry  an  EFI  system partition containing a boot loader, as
845       well as a kernel, kernel modules, udev and more.
846
847       All directory or btrfs subvolume images may be booted directly with:
848
849              systemd-nspawn -bD image
850

FILES

852       To make it easy to  build  images  for  development  versions  of  your
853       projects,  mkosi  can read configuration data from the local directory,
854       under the assumption that it is invoked from a source  tree.   Specifi‐
855       cally, the following files are used if they exist in the local directo‐
856       ry:
857
858       · mkosi.default  may  be  used  to  configure  mkosi’s  image  building
859         process.  For example, you may configure the distribution to use (fe‐
860         dora, ubuntu, debian, arch, opensuse, mageia, openmandriva)  for  the
861         image, or additional distribution packages to install.  Note that all
862         options encoded in this configuration file may also  be  set  on  the
863         command  line,  and this file is hence little more than a way to make
864         sure simply typing mkosi without further parameters  in  your  source
865         tree  is  enough to get the right image of your choice set up.  Addi‐
866         tionally if a mkosi.default.d directory exists, each file  in  it  is
867         loaded  in  the same manner adding/overriding the values specified in
868         mkosi.default.  If mkosi.default.d contains a directory  named  after
869         the  distribution  being  built,  each file in that directory is also
870         processed.  The file format is inspired by Windows.ini files and sup‐
871         ports  multi-line  assignments:  any  line with initial whitespace is
872         considered a continuation line of the line before.  Command-line  ar‐
873         guments,  as  shown in the help description, have to be included in a
874         configuration block (e.g. “[Packages]”) corresponding to the argument
875         group  (e.g. “Packages”), and the argument gets converted as follows:
876         “–with-network” becomes “WithNetwork=yes”.  For further  details  see
877         the table above.
878
879       · mkosi.extra/  or  mkosi.extra.tar  may be respectively a directory or
880         archive.  If any exist all files contained in it are copied over  the
881         directory  tree of the image after the OS was installed.  This may be
882         used to add in additional files to an image, on top of what the  dis‐
883         tribution includes in its packages.  When using a directory file own‐
884         ership is not preserved: all files copied will be owned by root.   To
885         preserve ownership use a tar archive.
886
887       · mkosi.skeleton/ or mkosi.skeleton.tar may be respectively a directory
888         or archive, and they work in the same way as mkosi.extra/mkosi.skele‐
889         ton.tar.   However  the  files  are copied before anything else so to
890         have a skeleton tree for the OS.  This allows to change  the  package
891         manager and create files that need to be there before anything is in‐
892         stalled.  When using a directory file ownership is not preserved: all
893         files  copied will be owned by root.  To preserve ownership use a tar
894         archive.
895
896       · mkosi.build may be an executable script.  If it exists the image will
897         be  built  twice:  the first iteration will be the development image,
898         the second iteration will be the final image.  The development  image
899         is  used  to  build the project in the current working directory (the
900         source tree).  For that the whole directory is copied into the image,
901         along  with the mkosi.build build script.  The script is then invoked
902         inside the image (via systemd-nspawn), with $SRCDIR pointing  to  the
903         source  tree.  $DESTDIR points to a directory where the script should
904         place any files generated it would like to end up in the final image.
905         Note  that  make/automake/meson  based  build systems generally honor
906         $DESTDIR, thus making it very natural to build source trees from  the
907         build  script.   After  the development image was built and the build
908         script ran inside of it, it is removed again.  After that  the  final
909         image  is  built,  without any source tree or build script copied in.
910         However, this time the contents of $DESTDIR are added into the image.
911
912         When the source tree is copied into the build image,  all  files  are
913         copied,  except  for mkosi.builddir/, mkosi.cache/ and mkosi.output/.
914         That said, .gitignore is respected if the source tree is a git check‐
915         out.   If  multiple  different  images  shall  be built from the same
916         source tree it’s essential to exclude their output  files  from  this
917         copy  operation,  as  otherwise  a  version of an image built earlier
918         might be included in a later build, which is  usually  not  intended.
919         An alternative to excluding these built images via .gitignore entries
920         is making use of the mkosi.output/ directory (see below), which is an
921         easy way to exclude all build artifacts.
922
923         The  MKOSI_DEFAULT  environment  variable  will be set inside of this
924         script so that you know which mkosi.default (if any) was passed in.
925
926       · mkosi.prepare may be an executable script.  If it exists  it  is  in‐
927         voked directly after the software packages are installed, from within
928         the image context.  It is once called for the development  image  (if
929         this  is enabled, see above) with the “build” command line parameter,
930         right before copying the extra tree.  It is called a second time  for
931         the final image with the “final” command line parameter.  This script
932         has network access and may be used to  install  packages  from  other
933         sources than the distro’s package manager (e.g. pip, npm, ...), after
934         all software packages are installed but before the  image  is  cached
935         (if  incremental  mode  is  enabled).  This script is executed within
936         $SRCDIR.  In contrast to a general purpose installation, it  is  safe
937         to  install  packages to the system (pip install, npm install -g) in‐
938         stead of in $SRCDIR itself because the build image is only used for a
939         single  project  and can easily be thrown away and rebuilt so there’s
940         no risk of conflicting dependencies and no risk of polluting the host
941         system.
942
943       · mkosi.postinst  may  be an executable script.  If it exists it is in‐
944         voked as the penultimate step of preparing an image, from within  the
945         image  context.  It is once called for the development image (if this
946         is enabled, see above) with the “build” command line parameter, right
947         before invoking the build script.  It is called a second time for the
948         final image with the “final” command line parameter, right before the
949         image  is  considered complete.  This script may be used to alter the
950         images without any restrictions,  after  all  software  packages  and
951         built sources have been installed.  Note that this script is executed
952         directly in the image context with the final root directory in place,
953         without any $SRCDIR/$DESTDIR setup.
954
955       · mkosi.finalize  may  be an executable script.  If it exists it is in‐
956         voked as last step of preparing an image, from the host  system.   It
957         is  once  called  for  the development image (if this is enabled, see
958         above) with the “build” command line parameter, as the last step  be‐
959         fore  invoking  the  build script, after the mkosi.postinst script is
960         invoked.  It is called the second time with the “final” command  line
961         parameter  as  the last step before the image is considered complete.
962         The environment variable $BUILDROOT points to the root  directory  of
963         the installation image.  Additional verbs may be added in the future,
964         the script should be prepared for that.  This script may be  used  to
965         alter  the  images without any restrictions, after all software pack‐
966         ages and built sources have been  installed.   This  script  is  more
967         flexible  than  mkosi.postinst  in  two regards: it has access to the
968         host file system so it’s easier to copy in  additional  files  or  to
969         modify  the  image based on external configuration, and the script is
970         run in the host, so it can be used even without emulation even if the
971         image has a foreign architecture.
972
973       · mkosi.mksquashfs-tool  may  be an executable script.  If it exists is
974         is called instead of mksquashfs.
975
976       · mkosi.nspawn may be an nspawn settings file.  If this exists it  will
977         be copied into the same place as the output image file.  This is use‐
978         ful since nspawn looks for settings files  next  to  image  files  it
979         boots, for additional container runtime settings.
980
981       · mkosi.cache/  may be a directory.  If so, it is automatically used as
982         package download cache, in order to speed repeated runs of the tool.
983
984       · mkosi.builddir/ may be a directory.  If so, it is automatically  used
985         as  out-of-tree  build  directory,  if  the  build  commands  in  the
986         mkosi.build script support it.  Specifically, this directory will  be
987         mounted into the build container, and the $BUILDDIR environment vari‐
988         able will be set to it when the build script is invoked.   The  build
989         script  may then use this directory as build directory, for automake-
990         style or ninja-style out-of-tree builds.  This speeds up builds  con‐
991         siderably, in particular when mkosi is used in incremental mode (-i):
992         not only the disk images but also the build tree  is  reused  between
993         subsequent  invocations.   Note that if this directory does not exist
994         the $BUILDDIR environment variable is not set, and it is up to  build
995         script  to  decide  whether to do in in-tree or an out-of-tree build,
996         and which build directory to use.
997
998       · mkosi.includedir/ may be a directory.  If  so,  it  is  automatically
999         used  as out-of-tree include directory.  Specifically, this directory
1000         will be mounted into the build container at /usr/include when  build‐
1001         ing  the build image and when running the build script.  After build‐
1002         ing the (cached) build image, this directory  will  contain  all  the
1003         files installed to /usr/include.  Language servers or other tools can
1004         use these files to provide a better editing experience for developers
1005         working on a project.
1006
1007       · mkosi.installdir/  may  be  a  directory.  If so, it is automatically
1008         used as the install directory.  Specifically, this directory will  be
1009         mounted  into  the  container  at  /root/dest  when running the build
1010         script.  After running the build script, the contents of this  direc‐
1011         tory are installed into the final image.  This is useful to cache the
1012         install step of the build.  If used, subsequent builds will only have
1013         to reinstall files that have changed since the previous build.
1014
1015       · mkosi.rootpw may be a file containing the password or hashed password
1016         (if --password-is-hashed is set) for the root user of  the  image  to
1017         set.   The password may optionally be followed by a newline character
1018         which is implicitly removed.  The file must have an  access  mode  of
1019         0600 or less.  If this file does not exist the distribution’s default
1020         root password is set (which usually means access to the root user  is
1021         blocked).
1022
1023       · mkosi.passphrase may be a passphrase file to use when LUKS encryption
1024         is selected.  It should contain the passphrase literally, and not end
1025         in  a  newline  character  (i.e. in the same format as cryptsetup and
1026         /etc/crypttab expect the passphrase files).  The file  must  have  an
1027         access mode of 0600 or less.  If this file does not exist and encryp‐
1028         tion is requested the user is queried instead.
1029
1030       · mkosi.secure-boot.crt and mkosi.secure-boot.key may contain an  X.509
1031         certificate  and  PEM private key to use when UEFI SecureBoot support
1032         is enabled.  All EFI binaries included in the image’s ESP are  signed
1033         with this key, as a late step in the build process.
1034
1035       · mkosi.output/ may be a directory.  If it exists, and the image output
1036         path is not configured (i.e. no --output= setting specified), or con‐
1037         figured  to  a  filename  (i.e. a path containing no / character) all
1038         build artifacts (that is: the image itself, the  root  hash  file  in
1039         case  Verity  is  used,  the checksum and its signature if that’s en‐
1040         abled, and the nspawn settings file if there is any)  are  placed  in
1041         this  directory.   Note  that this directory is not used if the image
1042         output path contains at least one slash, and has no  effect  in  that
1043         case.   This setting is particularly useful if multiple different im‐
1044         ages shall be built from the same working directory, as otherwise the
1045         build result of a preceding run might be copied into a build image as
1046         part of the source tree (see above).
1047
1048       All these files are optional.
1049
1050       Note that the location of all these files may also be configured during
1051       invocation via command line switches, and as settings in mkosi.default,
1052       in case the default settings are not acceptable for a project.
1053

BUILD PHASES

1055       If no build script mkosi.build (see above) is used the  build  consists
1056       of a single phase only: the final image is generated as the combination
1057       of mkosi.skeleton/ (see above), the unpacked distribution packages  and
1058       mkosi.extra/.
1059
1060       If a build script mkosi.build is used the build consists of two phases:
1061       in the the first development phase an  image  that  includes  necessary
1062       build  tools  (i.e. the  combination of Packages= and BuildPackages= is
1063       installed) is generated (i.e. the combination  of  mkosi.skeleton/  and
1064       unpacked  distribution  packages).   Into this image the source tree is
1065       copied and mkosi.build executed.  The artifacts the mkosi.build  gener‐
1066       ates are saved.  Then, the second final phase starts: an image that ex‐
1067       cludes the build tools (i.e. only Packages=  is  installed,  BuildPack‐
1068       ages=  is  not) is generated.  This time the build artifacts saved from
1069       the first phase are copied in, and mkosi.extra copied on top, thus gen‐
1070       erating the final image.
1071
1072       The two-phased approach ensures that source tree is executed in a clean
1073       and comprehensive environment, while at the same the  final  image  re‐
1074       mains  minimal  and  contains only those packages necessary at runtime,
1075       but avoiding those necessary at build-time.
1076
1077       Note that only the package cache mkosi.cache/ (see below) is shared be‐
1078       tween the two phases.  The distribution package manager is executed ex‐
1079       actly once in each phase, always starting from a directory tree that is
1080       populated with mkosi.skeleton but nothing else.
1081

CACHING

1083       mkosi  supports  three  different caches for speeding up repetitive re-
1084       building of images.  Specifically:
1085
1086       1. The package cache of the distribution package manager may be  cached
1087          between  builds.  This is configured with the --cache= option or the
1088          mkosi.cache/ directory.  This form of caching relies on the  distri‐
1089          bution’s  package  manager,  and  caches distribution packages (RPM,
1090          DEB, ...) after they are downloaded, but before they are unpacked.
1091
1092       2. If an mkosi.build script is used, by enabling incremental build mode
1093          with  --incremental (see above) a cached copy of the development and
1094          final images can be made immediately before the  build  sources  are
1095          copied  in (for the development image) or the artifacts generated by
1096          mkosi.build are copied in (in case of the final image).   This  form
1097          of  caching  allows  bypassing  the time-consuming package unpacking
1098          step of the distribution package managers, but is only effective  if
1099          the  list  of  packages to use remains stable, but the build sources
1100          and its scripts change regularly.  Note  that  this  cache  requires
1101          manual  flushing:  whenever  the package list is modified the cached
1102          images need to be explicitly removed before the next re-build, using
1103          the -f switch.
1104
1105       3. Finally, between multiple builds the build artifact directory may be
1106          shared, using the mkosi.builddir/ directory.  This directory  allows
1107          build systems such as Meson to reuse already compiled sources from a
1108          previous  built,  thus  speeding  up  the  build  process   of   the
1109          mkosi.build build script.
1110
1111       The  package  cache (i.e. the first item above) is unconditionally use‐
1112       ful.  The latter two caches only apply to uses of mkosi with  a  source
1113       tree and build script.  When all three are enabled together turn-around
1114       times for complete image builds are minimal,  as  only  changed  source
1115       files  need  to  be  recompiled:  an OS image rebuilt will be almost as
1116       quick to build the source tree only.
1117

ENVIRONMENT VARIABLES

1119       The build script mkosi.build receives the following  environment  vari‐
1120       ables:
1121
1122       · $SRCDIR contains the path to the sources to build.
1123
1124       · $DESTDIR  is  a  directory  into which any artifacts generated by the
1125         build script shall be placed.
1126
1127       · $BUILDDIR is only defined if mkosi.builddir and points to  the  build
1128         directory  to use.  This is useful for all build systems that support
1129         out-of-tree builds to reuse already  built  artifacts  from  previous
1130         runs.
1131
1132       · $WITH_DOCS  is  either 0 or 1 depending on whether a build without or
1133         with installed documentation was requested (see  --with-docs  above).
1134         The build script should suppress installation of any package documen‐
1135         tation to $DESTDIR in case $WITH_DOCS is set to 0.
1136
1137       · $WITH_TESTS is either 0or 1 depending on whether a build  without  or
1138         with  running  the  test  suite  was  requested  (see --without-tests
1139         above).  The build script should avoid running any unit  or  integra‐
1140         tion tests in case $WITH_TESTS is 0.
1141
1142       · $WITH_NETWORK is either 0or 1 depending on whether a build without or
1143         with networking is being executed (see  --with-network  above).   The
1144         build   script   should  avoid  any  network  communication  in  case
1145         $WITH_NETWORK is 0.
1146

EXAMPLES

1148       Create and run a raw GPT image with ext4, as image.raw:
1149
1150              # mkosi
1151              # systemd-nspawn -b -i image.raw
1152
1153       Create and run a bootable btrfs GPT image, as foobar.raw:
1154
1155              # mkosi -t gpt_btrfs --bootable -o foobar.raw
1156              # systemd-nspawn -b -i foobar.raw
1157              # qemu-kvm -m 512 -smp 2 -bios /usr/share/edk2/ovmf/OVMF_CODE.fd -drive format=raw,file=foobar.raw
1158
1159       Create and run a Fedora image into a plain directory:
1160
1161              # mkosi -d fedora -t directory -o quux
1162              # systemd-nspawn -b -D quux
1163
1164       Create a compressed image image.raw.xz and add a checksum file, and in‐
1165       stall SSH into it:
1166
1167              # mkosi -d fedora -t gpt_squashfs --checksum --xz --package=openssh-clients
1168
1169       Inside  the  source  directory  of an automake-based project, configure
1170       mkosi so that simply invoking mkosi without any parameters builds an OS
1171       image containing a built version of the project in its current state:
1172
1173              # cat > mkosi.default <<EOF
1174              [Distribution]
1175              Distribution=fedora
1176              Release=24
1177
1178              [Output]
1179              Format=gpt_btrfs
1180              Bootable=yes
1181
1182              [Packages]
1183              Packages=openssh-clients httpd
1184              BuildPackages=make gcc libcurl-devel
1185              EOF
1186              # cat > mkosi.build <<EOF
1187              #!/bin/sh
1188              cd $SRCDIR
1189              ./autogen.sh
1190              ./configure --prefix=/usr
1191              make -j `nproc`
1192              make install
1193              EOF
1194              # chmod +x mkosi.build
1195              # mkosi
1196              # systemd-nspawn -bi image.raw
1197
1198       To create a Fedora image with hostname:
1199
1200              # mkosi -d fedora --hostname image
1201
1202       Also you could set hostname in configuration file:
1203
1204              # cat mkosi.default
1205              ...
1206              [Output]
1207              Hostname=image
1208              ...
1209

REQUIREMENTS

1211       mkosi  is  packaged for various distributions: Debian, Ubuntu, Arch (in
1212       AUR), Fedora, OpenMandriva.  It is usually easiest to use the distribu‐
1213       tion package.
1214
1215       The  current  version requires systemd 233 (or actually, systemd-nspawn
1216       of it).
1217
1218       When not using distribution packages make sure to install the necessary
1219       dependencies.  For example, on Fedora you need:
1220
1221              dnf install arch-install-scripts btrfs-progs debootstrap dosfstools edk2-ovmf e2fsprogs squashfs-tools gnupg python3 tar veritysetup xfsprogs xz zypper sbsigntools
1222
1223       On  Debian/Ubuntu  it might be necessary to install the ubuntu-keyring,
1224       ubuntu-archive-keyring and/or debian-archive-keyring packages explicit‐
1225       ly,  in addition to debootstrap, depending on what kind of distribution
1226       images you want to build.  debootstrap on Debian only pulls in the  De‐
1227       bian  keyring  on  its own, and the version on Ubuntu only the one from
1228       Ubuntu.
1229
1230       Note that the minimum required Python version is 3.6.
1231

REFERENCES

1233       · Primary  mkosi  git  repository  on  GitHub  (https://github.com/sys
1234         temd/mkosi/)
1235
1236       · mkosi   —   A   Tool   for   Generating   OS  Images  (http://0point
1237         er.net/blog/mkosi-a-tool-for-generating-os-images.html)  introductory
1238         blog post by Lennart Poettering
1239
1240       · The mkosi OS generation tool (https://lwn.net/Articles/726655/) story
1241         on LWN
1242

SEE ALSO

1244       systemd-nspawn(1), dnf(8), debootstrap(8)
1245

AUTHORS

1247       The mkosi Authors.
1248
1249
1250
1251                                     2016-                            mkosi(1)
Impressum