Debian Codegraph @

upstream/fedora-44/man1/mkosi.1

raw
1 '\" t
2 .\" Automatically generated by Pandoc 3.6.4
3 .\"
4 .TH "mkosi" "1" "" ""
5 .SH NAME
6 mkosi \[em] Build Bespoke OS Images
7 .SH SYNOPSIS
8 \f[B]mkosi [options\&...]
9 init\f[R]
10 .PP
11 \f[B]mkosi [options\&...]
12 summary\f[R]
13 .PP
14 \f[B]mkosi [options\&...]
15 cat\-config\f[R]
16 .PP
17 \f[B]mkosi [options\&...]
18 build [\-\- command line\&...]\f[R]
19 .PP
20 \f[B]mkosi [options\&...]
21 shell [\-\- command line\&...]\f[R]
22 .PP
23 \f[B]mkosi [options\&...]
24 boot [\-\- nspawn settings\&...]\f[R]
25 .PP
26 \f[B]mkosi [options\&...]
27 vm [\-\- vmm parameters\&...]\f[R]
28 .PP
29 \f[B]mkosi [options\&...]
30 ssh [\-\- command line\&...]\f[R]
31 .PP
32 \f[B]mkosi [options\&...]
33 journalctl [\-\- command line\&...]\f[R]
34 .PP
35 \f[B]mkosi [options\&...]
36 coredumpctl [\-\- command line\&...]\f[R]
37 .PP
38 \f[B]mkosi [options\&...]
39 sysupdate [\-\- sysupdate settings\&...]\f[R]
40 .PP
41 \f[B]mkosi [options\&...]
42 box [\-\- command line\&...]\f[R]
43 .PP
44 \f[B]mkosi [options\&...]
45 dependencies [\-\- options\&...]\f[R]
46 .PP
47 \f[B]mkosi [options\&...]
48 clean\f[R]
49 .PP
50 \f[B]mkosi [options\&...]
51 serve\f[R]
52 .PP
53 \f[B]mkosi [options\&...]
54 burn <device>\f[R]
55 .PP
56 \f[B]mkosi [options\&...]
57 bump\f[R]
58 .PP
59 \f[B]mkosi [options\&...]
60 genkey\f[R]
61 .PP
62 \f[B]mkosi [options\&...]
63 documentation [manual]\f[R]
64 .PP
65 \f[B]mkosi [options\&...]
66 completion [shell]\f[R]
67 .PP
68 \f[B]mkosi [options\&...]
69 latest\-snapshot\f[R]
70 .PP
71 \f[B]mkosi [options\&...]
72 help\f[R]
73 .SH DESCRIPTION
74 \f[B]mkosi\f[R] is a tool for easily building customized OS images.
75 It\[cq]s a fancy wrapper around \f[B]dnf\f[R], \f[B]apt\f[R],
76 \f[B]pacman\f[R] and \f[B]zypper\f[R] that may generate disk images with
77 a number of bells and whistles.
78 .SS Command Line Verbs
79 The following command line verbs are known:
80 .TP
81 \f[B]init\f[R]
82 Initialize \f[B]mkosi\f[R].
83 This is a one time operation that sets up various config files required
84 for an optimal experience.
85 Currently this only initialized a \f[B]tmpfiles.d\f[R] dropin for the
86 mkosi package cache directory to make sure old, unused files are cleaned
87 up automatically.
88 .TP
89 \f[B]summary\f[R]
90 Show a human\-readable summary of all options used for building the
91 images.
92 This will parse the command line and configuration files, but only print
93 what it is configured for and not actually build or run anything.
94 .TP
95 \f[B]cat\-config\f[R]
96 Output the names and contents of all loaded configuration files.
97 \f[B]mkosi\f[R] loads a bunch of files from different locations and this
98 command makes it easier to figure out what is configured where.
99 .TP
100 \f[B]build\f[R]
101 Build the image\-based on the settings passed on the command line and in
102 the configuration files.
103 This command is the default if no verb is specified.
104 Arguments may be passed to the build scripts, if some are defined.
105 To pass options to the build scripts, separate them from regular mkosi
106 options with \f[B]\-\-\f[R].
107 .TP
108 \f[B]shell\f[R]
109 This builds the image if it is not built yet, and then invokes
110 \f[B]systemd\-nspawn\f[R] to run an interactive shell in the image.
111 This doesn\[cq]t require booting the system, it\[cq]s like a better
112 chroot.
113 An optional command line may be specified after the \f[B]shell\f[R]
114 verb, to be invoked in place of the shell in the container.
115 To pass extra options to nspawn, separate them from regular options with
116 \f[B]\-\-\f[R].
117 .TP
118 \f[B]boot\f[R]
119 Similar to \f[B]shell\f[R], but instead of spawning a shell, it boots
120 systemd in the image using \f[B]systemd\-nspawn\f[R].
121 Extra arguments may be specified after the \f[B]boot\f[R] verb, which
122 are passed as the \f[I]kernel command line\f[R] to the init system in
123 the image.
124 To pass extra options to nspawn, separate them from regular options with
125 \f[B]\-\-\f[R].
126 .TP
127 \f[B]vm\f[R]
128 Similar to \f[B]boot\f[R], but uses the configured virtual machine
129 monitor (by default \f[B]qemu\f[R]) to boot up the image, i.e.\ instead
130 of container virtualization, virtual machine virtualization is used.
131 How extra command line arguments are interpreted depends on the
132 configured virtual machine monitor.
133 See \f[B]VirtualMachineMonitor=\f[R] for more information.
134 To pass extra options to the configured virtual machine monitor,
135 separate them from regular options with \f[B]\-\-\f[R].
136 .TP
137 \f[B]ssh\f[R]
138 When the image is built with the \f[B]Ssh=always\f[R] option or if
139 systemd\[cq]s \f[B]sshd\-vsock\f[R] service is running in the VM
140 (systemd v256+), this command connects to a booted virtual machine via
141 SSH.
142 Make sure to run \f[B]mkosi ssh\f[R] with the same config as \f[B]mkosi
143 build\f[R] so that it has the necessary information available to connect
144 to the running virtual machine via SSH.
145 Specifically, the SSH private key from the \f[B]SshKey=\f[R] setting is
146 used to connect to the virtual machine.
147 Use \f[B]mkosi genkey\f[R] to automatically generate a key and
148 certificate that will be picked up by \f[B]mkosi\f[R].
149 Any arguments passed after the \f[B]ssh\f[R] verb are passed as
150 arguments to the \f[B]ssh\f[R] invocation.
151 To pass extra options, separate them from regular options with
152 \f[B]\-\-\f[R].To connect to a container, use \f[B]machinectl login\f[R]
153 or \f[B]machinectl shell\f[R].
154 .RS
155 .PP
156 The \f[B]Machine=\f[R] option can be used to give the machine a custom
157 hostname when booting it which can later be used to \f[B]ssh\f[R] into
158 the image (e.g.\ \f[B]mkosi \-\-machine=mymachine vm\f[R] followed by
159 \f[B]mkosi \-\-machine=mymachine ssh\f[R]).
160 .RE
161 .TP
162 \f[B]journalctl\f[R]
163 Uses \f[B]journalctl\f[R] to inspect the journal inside the image.
164 All arguments specified after the \f[B]journalctl\f[R] verb and
165 separated by \f[B]\-\-\f[R] from the regular options are appended to the
166 \f[B]journalctl\f[R] invocation.
167 .TP
168 \f[B]coredumpctl\f[R]
169 Uses \f[B]coredumpctl\f[R] to look for coredumps inside the image.
170 All arguments specified after the \f[B]coredumpctl\f[R] verb and
171 separated by \f[B]\-\-\f[R] from the regular options are appended to the
172 \f[B]coredumpctl\f[R] invocation.
173 .TP
174 \f[B]sysupdate\f[R]
175 Invokes \f[B]systemd\-sysupdate\f[R] with the
176 \f[B]\-\-transfer\-source=\f[R] option set to the output directory and
177 the \f[B]\-\-definitions=\f[R] option set to the directory configured
178 with \f[B]SysupdateDirectory=\f[R].
179 All arguments specified after the \f[B]sysupdate\f[R] verb and separated
180 from the regular options with \f[B]\-\-\f[R] are passed directly to
181 \f[B]systemd\-sysupdate\f[R].
182 .TP
183 \f[B]box\f[R]
184 Run arbitrary commands inside of the same environment used to execute
185 other verbs such as \f[B]boot\f[R], \f[B]shell\f[R], \f[B]vm\f[R] and
186 more.
187 This means \f[B]/usr\f[R] will be replaced by \f[B]/usr\f[R] from the
188 tools tree if one is used while everything else will remain in place.
189 If no command is provided, \f[B]$SHELL\f[R] will be executed or
190 \f[B]bash\f[R] if \f[B]$SHELL\f[R] is not set.
191 To pass extra options to the given command, separate them from regular
192 options with \f[B]\-\-\f[R].
193 .TP
194 \f[B]clean\f[R]
195 Remove build artifacts generated on a previous build.
196 If combined with \f[B]\-f\f[R], also removes incremental build cache
197 images and the tools tree.
198 If \f[B]\-f\f[R] is specified twice, also removes any package cache.
199 .TP
200 \f[B]serve\f[R]
201 This builds the image if it is not built yet, and then serves the output
202 directory (i.e.\ usually \f[B]mkosi.output/\f[R], see below) via a small
203 embedded HTTP server, listening on port 8081.
204 Combine with \f[B]\-f\f[R] in order to rebuild the image unconditionally
205 before serving it.
206 This command is useful for testing network\-based acquisition of OS
207 images, for example via \f[B]machinectl pull\-raw \&...\f[R] and
208 \f[B]machinectl pull\-tar \&...\f[R].
209 .TP
210 \f[B]burn <device>\f[R]
211 This builds the image if it is not built yet, and then writes it to the
212 specified block device.
213 The partition contents are written as\-is, but the GPT partition table
214 is corrected to match sector and disk size of the specified medium.
215 .TP
216 \f[B]bump\f[R]
217 Bumps the image version from \f[B]mkosi.version\f[R] and writes the
218 resulting version string to \f[B]mkosi.version\f[R].
219 This is useful for implementing a simple versioning scheme: each time
220 this verb is called the version is bumped in preparation for the
221 subsequent build.
222 Note that \f[B]\-\-auto\-bump\f[R]/\f[B]\-B\f[R] may be used to
223 automatically bump the version as part of a build.
224 The new version is only written to \f[B]mkosi.version\f[R] if the build
225 succeeds in that case.
226 .RS
227 .PP
228 If \f[B]mkosi.bump\f[R] exists, it is invoked to generate the new
229 version to be used instead of using mkosi\[cq]s own logic.
230 .RE
231 .TP
232 \f[B]genkey\f[R]
233 Generate a pair of SecureBoot keys for usage with the
234 \f[B]SecureBootKey=\f[R]/\f[B]\-\-secure\-boot\-key=\f[R] and
235 \f[B]SecureBootCertificate=\f[R]/\f[B]\-\-secure\-boot\-certificate=\f[R]
236 options.
237 .TP
238 \f[B]documentation\f[R]
239 Show \f[B]mkosi\f[R]\[cq]s documentation.
240 If no argument is given, the \f[B]mkosi\f[R] man page is shown, but the
241 arguments \f[B]mkosi\f[R], \f[B]mkosi\-initrd\f[R], \f[B]initrd\f[R],
242 \f[B]mkosi\-sandbox\f[R], \f[B]sandbox\f[R], \f[B]mkosi.news\f[R] and
243 \f[B]news\f[R] are supported and respectively show the man pages for
244 \f[B]mkosi\f[R], \f[B]mkosi\-initrd\f[R], \f[B]mkosi\-sandbox\f[R] and
245 \f[B]mkosi\f[R]\[cq]s NEWS file.
246 .RS
247 .PP
248 By default this verb will try several ways to output the documentation,
249 but a specific option can be chosen with the \f[B]\-\-doc\-format\f[R]
250 option.
251 Distro packagers are encouraged to add a file \f[B]mkosi.1\f[R] into the
252 \f[B]mkosi/resources\f[R] directory of the Python package, if it is
253 missing, as well as to install it in the appropriate search path for man
254 pages.
255 The man page can be generated from the markdown file
256 \f[B]mkosi/resources/man/mkosi.1.md\f[R] e.g via \f[B]pandoc \-t man \-s
257 \-o mkosi.1 mkosi.1.md\f[R].
258 .RE
259 .TP
260 \f[B]completion\f[R]
261 Generate shell completion for the shell given as argument and print it
262 to stdout.
263 The arguments \f[B]bash\f[R], \f[B]fish\f[R], and \f[B]zsh\f[R] are
264 understood.
265 .TP
266 \f[B]dependencies\f[R]
267 Output the list of packages required by \f[B]mkosi\f[R] to build and
268 boot images.
269 .RS
270 .PP
271 This list can be piped directly to a package manager to install the
272 packages.
273 For example, if the host system uses the \f[B]dnf\f[R] package manager,
274 the packages could be installed as follows:
275 .IP
276 .EX
277 mkosi dependencies \f[B]|\f[R] xargs \-d \[aq]\[rs]n\[aq] dnf install
278 .EE
279 .PP
280 By default, only the dependencies required to build images with mkosi
281 are shown.
282 Extra tools tree profiles can be enabled to also output the packages
283 belonging to those profiles.
284 For example, running \f[B]mkosi dependencies \-\- \-\-profile
285 runtime\f[R] will also output the packages in the runtime profile on top
286 of the regular packages.
287 See the documentation for \f[B]ToolsTreeProfiles=\f[R] for a list of
288 available profiles.
289 .RE
290 .TP
291 \f[B]latest\-snapshot\f[R]
292 Output the latest available snapshot in the configured mirror.
293 .RS
294 .PP
295 This verb is useful to automatically bump snapshots every so often.
296 Note that this verb only outputs the latest snapshot.
297 It\[cq]s up to the caller to ensure that the snapshot is written to the
298 intended configuration file.
299 .RE
300 .TP
301 \f[B]help\f[R]
302 This verb is equivalent to the \f[B]\-\-help\f[R] switch documented
303 below: it shows a brief usage explanation.
304 .SS Command\-Line\-Only Options
305 Those settings cannot be configured in the configuration files.
306 .TP
307 \f[B]\-\-force\f[R], \f[B]\-f\f[R]
308 Replace the output file if it already exists, when building an image.
309 By default when building an image and an output artifact already exists
310 \f[B]mkosi\f[R] will refuse operation.
311 Specify this option once to delete all build artifacts from a previous
312 run before re\-building the image.
313 If incremental builds are enabled, specifying this option twice will
314 ensure the intermediary cache files are removed, too, before the
315 re\-build is initiated.
316 If a package cache is used (also see the \f[B]FILES\f[R] section below),
317 specifying this option thrice will ensure the package cache is removed
318 too, before the re\-build is initiated.
319 For the \f[B]clean\f[R] operation this option has a slightly different
320 effect: by default the verb will only remove build artifacts from a
321 previous run, when specified once the incremental cache files and the
322 tools tree are deleted too, and when specified twice the package cache
323 is also removed.
324 .TP
325 \f[B]\-\-directory=\f[R], \f[B]\-C\f[R]
326 Takes a path to a directory.
327 \f[B]mkosi\f[R] switches to this directory before doing anything.
328 Note that the various configuration files are searched for in this
329 directory, hence using this option is an effective way to build a
330 project located in a specific directory.
331 Defaults to the current working directory.
332 If the empty string is specified, all configuration in the current
333 working directory will be ignored.
334 .TP
335 \f[B]\-\-debug\f[R]
336 Enable additional debugging output.
337 .TP
338 \f[B]\-\-debug\-shell\f[R]
339 When executing a command in the image fails, \f[B]mkosi\f[R] will start
340 an interactive shell in the image allowing further debugging.
341 .TP
342 \f[B]\-\-debug\-workspace\f[R]
343 When specified, the workspace directory will not be deleted and its
344 location will be logged when \f[B]mkosi\f[R] exits.
345 .TP
346 \f[B]\-\-debug\-sandbox\f[R]
347 Run \f[B]mkosi\-sandbox\f[R] with \f[B]strace\f[R].
348 .TP
349 \f[B]\-\-version\f[R]
350 Show package version.
351 .TP
352 \f[B]\-\-help\f[R], \f[B]\-h\f[R]
353 Show brief usage information.
354 .TP
355 \f[B]\-\-genkey\-common\-name=\f[R]
356 Common name to be used when generating keys via \f[B]mkosi\f[R]\[cq]s
357 \f[B]genkey\f[R] command.
358 Defaults to \f[B]mkosi of %u\f[R], where \f[B]%u\f[R] expands to the
359 username of the user invoking \f[B]mkosi\f[R].
360 .TP
361 \f[B]\-\-genkey\-valid\-days=\f[R]
362 Number of days that the keys should remain valid when generating keys
363 via \f[B]mkosi\f[R]\[cq]s \f[B]genkey\f[R] command.
364 Defaults to two years (730 days).
365 .TP
366 \f[B]\-\-auto\-bump=\f[R], \f[B]\-B\f[R]
367 If specified, the version is bumped and if the build succeeds, the
368 version is written to \f[B]mkosi.version\f[R] in a fashion equivalent to
369 the \f[B]bump\f[R] verb.
370 This is useful for simple, linear version management: each build in a
371 series will have a version number one higher then the previous one.
372 .RS
373 .PP
374 If \f[B]mkosi.bump\f[R] exists, it is invoked to generate the new
375 version to be used instead of using mkosi\[cq]s own logic.
376 .RE
377 .TP
378 \f[B]\-\-doc\-format\f[R]
379 The format to show the documentation in.
380 Supports the values \f[B]markdown\f[R], \f[B]man\f[R], \f[B]pandoc\f[R],
381 \f[B]system\f[R] and \f[B]auto\f[R].
382 In the case of \f[B]markdown\f[R] the documentation is shown in the
383 original Markdown format.
384 \f[B]man\f[R] shows the documentation in man page format, if it is
385 available.
386 \f[B]pandoc\f[R] will generate the man page format on the fly, if
387 \f[B]pandoc\f[R] is available.
388 \f[B]system\f[R] will show the system\-wide man page for
389 \f[B]mkosi\f[R], which may or may not correspond to the version you are
390 using, depending on how you installed \f[B]mkosi\f[R].
391 \f[B]auto\f[R], which is the default, will try all methods in the order
392 \f[B]man\f[R], \f[B]pandoc\f[R], \f[B]markdown\f[R], \f[B]system\f[R].
393 .TP
394 \f[B]\-\-json\f[R]
395 Show the summary output as JSON\-SEQ.
396 .TP
397 \f[B]\-\-wipe\-build\-dir\f[R], \f[B]\-w\f[R]
398 Wipe the build directory if one is configured before building the image.
399 .TP
400 \f[B]\-\-rerun\-build\-scripts\f[R], \f[B]\-R\f[R]
401 Rerun build scripts.
402 Requires the \f[B]Incremental=\f[R] option to be enabled and the image
403 to have been built once already.
404 If \f[B]History=\f[R] is enabled, the history from the previous build
405 will be reused and no new history will be written.
406 .SS Supported output formats
407 The following output formats are supported:
408 .IP \[bu] 2
409 Raw \f[I]GPT\f[R] disk image, created using \f[B]systemd\-repart\f[R]
410 (\f[I]disk\f[R])
411 .IP \[bu] 2
412 Plain directory, containing the OS tree (\f[I]directory\f[R])
413 .IP \[bu] 2
414 Tar archive (\f[I]tar\f[R])
415 .IP \[bu] 2
416 CPIO archive (\f[I]cpio\f[R])
417 .IP \[bu] 2
418 Unified Kernel Image (\f[I]UKI\f[R])
419 .IP \[bu] 2
420 \&...
421 and much more.
422 See \f[B]Format=\f[R] documentation below.
423 .PP
424 The output format may also be set to \f[I]none\f[R] to have
425 \f[B]mkosi\f[R] produce no image at all.
426 This can be useful if you only want to use the image to produce another
427 output in the build scripts (e.g.\ build an RPM).
428 .PP
429 When a \f[I]GPT\f[R] disk image is created, repart partition definition
430 files may be placed in \f[B]mkosi.repart/\f[R] to configure the
431 generated disk image.
432 .PP
433 It is highly recommended to run \f[B]mkosi\f[R] on a file system that
434 supports reflinks such as XFS and btrfs and to keep all related
435 directories on the same file system.
436 This allows \f[B]mkosi\f[R] to create images very quickly by using
437 reflinks to perform copying via copy\-on\-write operations.
438 .SS Configuration Settings
439 The following settings can be set through configuration files (the
440 syntax with \f[B]SomeSetting=value\f[R]) and on the command line (the
441 syntax with \f[B]\-\-some\-setting=value\f[R]).
442 For some command line parameters, a single\-letter shortcut is also
443 allowed.
444 In the configuration files, the setting must be in the appropriate
445 section, so the settings are grouped by section below.
446 .PP
447 Configuration is parsed in the following order:
448 .IP \[bu] 2
449 The command line arguments are parsed.
450 .IP \[bu] 2
451 \f[B]mkosi.local.conf\f[R] and \f[B]mkosi.local/\f[R] are parsed if they
452 exists (in that order).
453 This file and directory should be in \f[B].gitignore\f[R] (or
454 equivalent) and are intended for local configuration.
455 .IP \[bu] 2
456 If an option has a corresponding default path, it is parsed if the
457 corresponding default path exists.
458 .IP \[bu] 2
459 \f[B]mkosi.conf\f[R] is parsed if it exists in the directory configured
460 with \f[B]\-\-directory=\f[R] or the current working directory if
461 \f[B]\-\-directory=\f[R] is not used.
462 If the specified directory does not contain a \f[B]mkosi.conf\f[R] or
463 \f[B]mkosi.tools.conf\f[R] and a \f[B]mkosi/mkosi.conf\f[R] or
464 \f[B]mkosi/mkosi.tools.conf\f[R] exists, the configuration will be
465 parsed from the \f[B]mkosi/\f[R] subdirectory of the specified directory
466 instead.
467 .IP \[bu] 2
468 \f[B]mkosi.conf.d/\f[R] is parsed in the same directory as
469 \f[B]mkosi.conf\f[R] if it exists.
470 Each directory and each file with the \f[B].conf\f[R] extension in
471 \f[B]mkosi.conf.d/\f[R] is parsed.
472 Any directory in \f[B]mkosi.conf.d\f[R] is parsed as if it were a
473 regular top level directory, except for \f[B]mkosi.images/\f[R] and
474 \f[B]mkosi.tools.conf\f[R], which are only picked up in the top level
475 directory.
476 .IP \[bu] 2
477 If any profiles are configured, their configuration is parsed from the
478 \f[B]mkosi.profiles/\f[R] directory.
479 .IP \[bu] 2
480 Subimages are parsed from the \f[B]mkosi.images/\f[R] directory if it
481 exists.
482 .PP
483 Note that settings configured via the command line always override
484 settings configured via configuration files.
485 If the same setting is configured more than once via configuration
486 files, later assignments override earlier assignments except for
487 settings that take a collection of values.
488 Also, settings read from \f[B]mkosi.local.conf\f[R] or
489 \f[B]mkosi.local/\f[R] will override settings from configuration files
490 that are parsed later, but not settings specified on the CLI.
491 .PP
492 For settings that take a single value, the empty assignment
493 (\f[B]SomeSetting=\f[R] or \f[B]\-\-some\-setting=\f[R]) can be used to
494 override a previous setting and reset to the default.
495 .PP
496 Settings that take a collection of values are merged by appending the
497 new values to the previously configured values.
498 Assigning the empty string to such a setting removes all previously
499 assigned values, and overrides any configured default values as well.
500 The values specified on the CLI are appended after all the values from
501 configuration files.
502 .PP
503 To conditionally include configuration files, the \f[B][Match]\f[R]
504 section can be used.
505 A \f[B][Match]\f[R] section consists of individual conditions.
506 Conditions can use a pipe symbol (\f[B]|\f[R]) after the equals sign
507 (\f[B]\&...=|\&...\f[R]), which causes the condition to become a
508 triggering condition.
509 The config file will be included if the logical AND of all
510 non\-triggering conditions and the logical OR of all triggering
511 conditions is satisfied.
512 To negate the result of a condition, prefix the argument with an
513 exclamation mark.
514 If an argument is prefixed with the pipe symbol and an exclamation mark,
515 the pipe symbol must be passed first, and the exclamation second.
516 .PP
517 Note that \f[B][Match]\f[R] conditions compare against the current
518 values of specific settings, and do not take into account changes made
519 to the setting in configuration files that have not been parsed yet
520 (settings specified on the CLI are taken into account).
521 Also note that matching against a setting and then changing its value
522 afterwards in a different config file may lead to unexpected results.
523 .PP
524 The \f[B][Match]\f[R] section of a \f[B]mkosi.conf\f[R] file in a
525 directory applies to the entire directory.
526 If the conditions are not satisfied, the entire directory is skipped.
527 The \f[B][Match]\f[R] sections of files in \f[B]mkosi.conf.d/\f[R] and
528 \f[B]mkosi.local.conf\f[R] only apply to the file itself.
529 .PP
530 If there are multiple \f[B][Match]\f[R] sections in the same
531 configuration file, each of them has to be satisfied in order for the
532 configuration file to be included.
533 Specifically, triggering conditions only apply to the current
534 \f[B][Match]\f[R] section and are reset between multiple
535 \f[B][Match]\f[R] sections.
536 As an example, the following will only match if the output format is one
537 of \f[B]disk\f[R] or \f[B]directory\f[R] and the architecture is one of
538 \f[B]x86\-64\f[R] or \f[B]arm64\f[R]:
539 .IP
540 .EX
541 \f[B][Match]\f[R]
542 Format=|disk
543 Format=|directory
544
545 \f[B][Match]\f[R]
546 Architecture=|x86\-64
547 Architecture=|arm64
548 .EE
549 .PP
550 The \f[B][TriggerMatch]\f[R] section can be used to indicate triggering
551 matches.
552 These are identical to triggering conditions in systemd units except
553 they apply to the entire match section instead of just a single
554 condition.
555 As an example, the following will match if the distribution is
556 \f[B]debian\f[R] and the release is \f[B]bookworm\f[R] or if the
557 distribution is \f[B]ubuntu\f[R] and the release is \f[B]noble\f[R].
558 .IP
559 .EX
560 \f[B][TriggerMatch]\f[R]
561 Distribution=debian
562 Release=bookworm
563
564 \f[B][TriggerMatch]\f[R]
565 Distribution=ubuntu
566 Release=noble
567 .EE
568 .PP
569 The semantics of conditions in \f[B][TriggerMatch]\f[R] sections is the
570 same as in \f[B][Match]\f[R], i.e.\ all normal conditions are joined by
571 a logical AND and all triggering conditions are joined by a logical OR.
572 When mixing \f[B][Match]\f[R] and \f[B][TriggerMatch]\f[R] sections, a
573 match is achieved when all \f[B][Match]\f[R] sections match and at least
574 one \f[B][TriggerMatch]\f[R] section matches.
575 The absence of match sections is valued as true.
576 Logically this means:
577 .IP
578 .EX
579 (⋀ᵢ Matchᵢ) ∧ (⋁ᵢ TriggerMatchᵢ)
580 .EE
581 .PP
582 There is also support for \f[B][Assert]\f[R] and
583 \f[B][TriggerAssert]\f[R] sections which behave identically to match
584 sections except parsing configuration will fail if the assert sections
585 are not satisfied, i.e.\ all \f[B][Assert]\f[R] sections in a file as
586 well as at least one \f[B][TriggertAssert]\f[R] section have to be
587 satisfied or config parsing will fail.
588 .PP
589 Command line options that take no argument are shown without \f[B]=\f[R]
590 in their long version.
591 In the config files, they should be specified with a boolean argument:
592 either \f[B]1\f[R], \f[B]yes\f[R], or \f[B]true\f[R] to enable, or
593 \f[B]0\f[R], \f[B]no\f[R], \f[B]false\f[R] to disable.
594 .SS [Distribution] Section
595 .TP
596 \f[B]Distribution=\f[R], \f[B]\-\-distribution=\f[R], \f[B]\-d\f[R]
597 The distribution to install in the image.
598 Takes one of the following arguments: \f[B]fedora\f[R],
599 \f[B]debian\f[R], \f[B]kali\f[R], \f[B]ubuntu\f[R], \f[B]arch\f[R],
600 \f[B]opensuse\f[R], \f[B]mageia\f[R], \f[B]centos\f[R], \f[B]rhel\f[R],
601 \f[B]rhel\-ubi\f[R], \f[B]openmandriva\f[R], \f[B]rocky\f[R],
602 \f[B]alma\f[R], \f[B]azure\f[R] or \f[B]custom\f[R].
603 If not specified, defaults to the distribution of the host or
604 \f[B]custom\f[R] if the distribution of the host is not a supported
605 distribution.
606 .TP
607 \f[B]Release=\f[R], \f[B]\-\-release=\f[R], \f[B]\-r\f[R]
608 The release of the distribution to install in the image.
609 The precise syntax of the argument this takes depends on the
610 distribution used, and is either a numeric string (in case of Fedora
611 Linux, CentOS, \&..., e.g.\ \f[B]29\f[R]), or a distribution version
612 name (in case of Debian, Kali, Ubuntu, \&..., e.g.\ \f[B]artful\f[R]).
613 Defaults to a recent version of the chosen distribution, or the version
614 of the distribution running on the host if it matches the configured
615 distribution.
616 .TP
617 \f[B]Architecture=\f[R], \f[B]\-\-architecture=\f[R]
618 The architecture to build the image for.
619 The architectures that are actually supported depends on the
620 distribution used and whether a bootable image is requested or not.
621 When building for a foreign architecture, you\[cq]ll also need to
622 install and register a user mode emulator for that architecture.
623 .RS
624 .PP
625 One of the following architectures can be specified per image built:
626 \f[B]alpha\f[R], \f[B]arc\f[R], \f[B]arm\f[R], \f[B]arm64\f[R],
627 \f[B]ia64\f[R], \f[B]loongarch64\f[R], \f[B]mips64\-le\f[R],
628 \f[B]mips\-le\f[R], \f[B]parisc\f[R], \f[B]ppc\f[R], \f[B]ppc64\f[R],
629 \f[B]ppc64\-le\f[R], \f[B]riscv32\f[R], \f[B]riscv64\f[R],
630 \f[B]s390\f[R], \f[B]s390x\f[R], \f[B]tilegx\f[R], \f[B]x86\f[R],
631 \f[B]x86\-64\f[R].
632 .RE
633 .TP
634 \f[B]Mirror=\f[R], \f[B]\-\-mirror=\f[R], \f[B]\-m\f[R]
635 The mirror to use for downloading the distribution packages.
636 Expects a mirror URL as argument.
637 If not provided, the default mirror for the distribution is used.
638 .RS
639 .PP
640 The default mirrors for each distribution are as follows (unless
641 specified, the same mirror is used for all architectures):
642 .PP
643 .TS
644 tab(@);
645 lw(13.3n) lw(30.0n) lw(26.7n).
646 T{
647 T}@T{
648 x86\-64
649 T}@T{
650 aarch64
651 T}
652 _
653 T{
654 \f[B]debian\f[R]
655 T}@T{
656 http://deb.debian.org
657 T}@T{
658 T}
659 T{
660 \f[B]arch\f[R]
661 T}@T{
662 https://fastly.mirror.pkgbuild.com
663 T}@T{
664 http://mirror.archlinuxarm.org
665 T}
666 T{
667 \f[B]opensuse\f[R]
668 T}@T{
669 http://download.opensuse.org
670 T}@T{
671 T}
672 T{
673 \f[B]kali\f[R]
674 T}@T{
675 http://http.kali.org/kali
676 T}@T{
677 T}
678 T{
679 \f[B]ubuntu\f[R]
680 T}@T{
681 http://archive.ubuntu.com
682 T}@T{
683 http://ports.ubuntu.com
684 T}
685 T{
686 \f[B]centos\f[R]
687 T}@T{
688 https://mirrors.centos.org
689 T}@T{
690 T}
691 T{
692 \f[B]rocky\f[R]
693 T}@T{
694 https://mirrors.rockylinux.org
695 T}@T{
696 T}
697 T{
698 \f[B]alma\f[R]
699 T}@T{
700 https://mirrors.almalinux.org
701 T}@T{
702 T}
703 T{
704 \f[B]fedora\f[R]
705 T}@T{
706 https://mirrors.fedoraproject.org
707 T}@T{
708 T}
709 T{
710 \f[B]rhel\-ubi\f[R]
711 T}@T{
712 https://cdn\-ubi.redhat.com
713 T}@T{
714 T}
715 T{
716 \f[B]mageia\f[R]
717 T}@T{
718 https://www.mageia.org
719 T}@T{
720 T}
721 T{
722 \f[B]openmandriva\f[R]
723 T}@T{
724 http://mirrors.openmandriva.org
725 T}@T{
726 T}
727 T{
728 \f[B]azure\f[R]
729 T}@T{
730 https://packages.microsoft.com/
731 T}@T{
732 T}
733 .TE
734 .RE
735 .TP
736 \f[B]Snapshot=\f[R]
737 Download packages from the given snapshot instead of downloading the
738 latest distribution packages from the given mirror.
739 Takes a snapshot ID (the format of the snapshot ID differs per
740 distribution), use the \f[B]latest\-snapshot\f[R] verb to figure out the
741 latest available snapshot.
742 .RS
743 .PP
744 If this setting is configured and \f[B]Mirror=\f[R] is not explicitly
745 configured, different default mirrors are used:
746 .PP
747 .TS
748 tab(@);
749 lw(13.3n) lw(30.0n) lw(26.7n).
750 T{
751 T}@T{
752 x86\-64
753 T}@T{
754 aarch64
755 T}
756 _
757 T{
758 \f[B]debian\f[R]
759 T}@T{
760 https://snapshot.debian.org
761 T}@T{
762 T}
763 T{
764 \f[B]arch\f[R]
765 T}@T{
766 https://archive.archlinux.org
767 T}@T{
768 http://mirror.archlinuxarm.org
769 T}
770 T{
771 \f[B]opensuse\f[R]
772 T}@T{
773 http://download.opensuse.org
774 T}@T{
775 T}
776 T{
777 \f[B]ubuntu\f[R]
778 T}@T{
779 http://archive.ubuntu.com
780 T}@T{
781 http://ports.ubuntu.com
782 T}
783 T{
784 \f[B]centos\f[R]
785 T}@T{
786 https://composes.stream.centos.org
787 T}@T{
788 T}
789 T{
790 \f[B]fedora\f[R]
791 T}@T{
792 https://kojipkgs.fedoraproject.org
793 T}@T{
794 T}
795 .TE
796 .PP
797 For any distribution not listed above, snapshots are not supported.
798 .RE
799 .TP
800 \f[B]LocalMirror=\f[R], \f[B]\-\-local\-mirror=\f[R]
801 The mirror will be used as a local, plain and direct mirror instead of
802 using it as a prefix for the full set of repositories normally supported
803 by distributions.
804 Useful for fully offline builds with a single repository.
805 Supported on \f[B]deb\f[R]\-, \f[B]rpm\f[R]\-, and
806 \f[B]pacman\f[R]\-based distributions.
807 Overrides \f[B]\-\-mirror=\f[R] but only for the local \f[B]mkosi\f[R]
808 build, it will not be configured inside the final image,
809 \f[B]\-\-mirror=\f[R] (or the default repository) will be configured
810 inside the final image instead.
811 .TP
812 \f[B]RepositoryKeyCheck=\f[R], \f[B]\-\-repository\-key\-check=\f[R]
813 Controls signature/key checks when using repositories, enabled by
814 default.
815 Useful to disable checks when combined with \f[B]\-\-local\-mirror=\f[R]
816 and using only a repository from a local filesystem.
817 .TP
818 \f[B]RepositoryKeyFetch=\f[R], \f[B]\-\-repository\-key\-fetch=\f[R]
819 Controls whether \f[B]mkosi\f[R] will fetch distribution GPG keys
820 remotely.
821 Enabled by default on Ubuntu when not using a tools tree or when using
822 Ubuntu tools trees to build Arch Linux or RPM\-based distributions.
823 Disabled by default on all other distributions.
824 When disabled, the distribution GPG keys for the target distribution
825 have to be installed locally on the host system alongside the package
826 manager for that distribution.
827 .RS
828 .PP
829 This setting is only implemented for distributions using \f[B]dnf\f[R],
830 \f[B]pacman\f[R] or \f[B]zypper\f[R] as their package manager.
831 For other distributions the distribution GPG keys are always looked up
832 locally regardless of the value of this setting.
833 To make the distribution GPG keys for distributions available without
834 enabling this setting, the corresponding package has to be installed on
835 the host.
836 This is usually one of \f[B]archlinux\-keyring\f[R],
837 \f[B]debian\-keyring\f[R], \f[B]kali\-archive\-keyring\f[R],
838 \f[B]ubuntu\-keyring\f[R] or \f[B]distribution\-gpg\-keys\f[R] (for
839 RPM\-based distributions).
840 .RE
841 .TP
842 \f[B]Repositories=\f[R], \f[B]\-\-repositories=\f[R]
843 Enable package repositories that are disabled by default.
844 This can be used to enable the EPEL repos for CentOS or different
845 components of the Debian/Kali/Ubuntu repositories.
846 .SS [Output] Section
847 .TP
848 \f[B]Format=\f[R], \f[B]\-\-format=\f[R], \f[B]\-t\f[R]
849 The image format type to generate.
850 One of \f[B]directory\f[R] (for generating an OS image directly in a
851 local directory), \f[B]tar\f[R] (similar, but a tarball of the OS image
852 is generated), \f[B]cpio\f[R] (similar, but a cpio archive is
853 generated), \f[B]disk\f[R] (a block device OS image with a GPT partition
854 table), \f[B]uki\f[R] (a unified kernel image with the OS image in the
855 \f[B].initrd\f[R] PE section), \f[B]esp\f[R] (a disk image with only an
856 ESP partition, bootloader and optionally a UKI), \f[B]oci\f[R] (a
857 directory compatible with the OCI image specification),
858 \f[B]sysext\f[R], \f[B]confext\f[R], \f[B]portable\f[R], \f[B]addon\f[R]
859 or \f[B]none\f[R] (the OS image is solely intended as a build image to
860 produce another artifact).
861 .RS
862 .PP
863 If the \f[B]disk\f[R] output format is used, the disk image is generated
864 using \f[B]systemd\-repart\f[R].
865 The repart partition definition files to use can be configured using the
866 \f[B]RepartDirectories=\f[R] setting or via \f[B]mkosi.repart/\f[R].
867 When verity partitions are configured using
868 \f[B]systemd\-repart\f[R]\[cq]s \f[B]Verity=\f[R] setting,
869 \f[B]mkosi\f[R] will automatically parse the verity hash partition\[cq]s
870 roothash from \f[B]systemd\-repart\f[R]\[cq]s JSON output and include it
871 in the kernel command line of every unified kernel image built by
872 \f[B]mkosi\f[R].
873 .PP
874 If the \f[B]none\f[R] output format is used, the outputs from a previous
875 build are not removed, but clean scripts (see \f[B]CleanScripts=\f[R])
876 are still executed.
877 This allows rerunning a build script (see \f[B]BuildScripts=\f[R])
878 without removing the results of a previous build.
879 .RE
880 .TP
881 \f[B]ManifestFormat=\f[R], \f[B]\-\-manifest\-format=\f[R]
882 The manifest format type or types to generate.
883 A comma\-delimited list consisting of \f[B]json\f[R] (the standard JSON
884 output format that describes the packages installed),
885 \f[B]changelog\f[R] (a human\-readable text format designed for
886 diffing).
887 By default no manifest is generated.
888 .TP
889 \f[B]Output=\f[R], \f[B]\-\-output=\f[R], \f[B]\-o\f[R]
890 Name to use for the generated output image file or directory.
891 Defaults to \f[B]image\f[R] or, if \f[B]ImageId=\f[R] is specified, it
892 is used as the default output name, optionally suffixed with the version
893 set with \f[B]ImageVersion=\f[R] or if a specific image is built from
894 \f[B]mkosi.images\f[R], the name of the image is preferred over
895 \f[B]ImageId\f[R].
896 Note that this option does not allow configuring the output directory,
897 use \f[B]OutputDirectory=\f[R] for that.
898 .RS
899 .PP
900 Note that this only specifies the output prefix, depending on the
901 specific output format, compression and image version used, the full
902 output name might be \f[B]image_7.8.raw.xz\f[R].
903 .RE
904 .TP
905 \f[B]OutputExtension=\f[R], \f[B]\-\-output\-extension=\f[R]
906 Use the specified extension for the output file.
907 Defaults to the appropriate extension based on the output format.
908 Only includes the file extension, not any compression extension which
909 will be appended to this extension if compression is enabled.
910 .TP
911 \f[B]CompressOutput=\f[R], \f[B]\-\-compress\-output=\f[R]
912 Configure compression for the resulting image or archive.
913 The argument can be either a boolean or a compression algorithm
914 (\f[B]xz\f[R], \f[B]zstd\f[R]).
915 \f[B]zstd\f[R] compression is used by default, except CentOS and
916 derivatives up to version 8, which default to \f[B]xz\f[R], and OCI
917 images, which default to \f[B]gzip\f[R].
918 Note that when applied to block device image types, compression means
919 the image cannot be started directly but needs to be decompressed first.
920 This also means that the \f[B]shell\f[R], \f[B]boot\f[R], \f[B]vm\f[R]
921 verbs are not available when this option is used.
922 Implied for \f[B]tar\f[R], \f[B]cpio\f[R], \f[B]uki\f[R], \f[B]esp\f[R],
923 \f[B]oci\f[R] and \f[B]addon\f[R].
924 .TP
925 \f[B]CompressLevel=\f[R], \f[B]\-\-compress\-level=\f[R]
926 Configure the compression level to use.
927 Takes an integer.
928 The possible values depend on the compression being used.
929 .TP
930 \f[B]OutputDirectory=\f[R], \f[B]\-\-output\-directory=\f[R], \f[B]\-O\f[R]
931 Path to a directory where to place all generated artifacts.
932 If this is not specified and the directory \f[B]mkosi.output/\f[R]
933 exists in the local directory, it is automatically used for this
934 purpose.
935 .TP
936 \f[B]OutputMode=\f[R], \f[B]\-\-output\-mode=\f[R]
937 File system access mode used when creating the output image file.
938 Takes an access mode in octal notation.
939 If not set, uses the current system defaults.
940 .TP
941 \f[B]ImageVersion=\f[R], \f[B]\-\-image\-version=\f[R]
942 Configure the image version.
943 This accepts any string, but it is recommended to specify a series of
944 dot separated components.
945 The version may also be configured by reading a \f[B]mkosi.version\f[R]
946 file (in which case it may be conveniently managed via the
947 \f[B]bump\f[R] verb or the \f[B]\-\-auto\-bump\f[R] option) or by
948 reading stdout if it is executable (see the \f[B]Scripts\f[R] section
949 below).
950 When specified the image version is included in the default output file
951 name, i.e.\ instead of \f[B]image.raw\f[R] the default will be
952 \f[B]image_0.1.raw\f[R] for version \f[B]0.1\f[R] of the image, and
953 similar.
954 The version is also passed via the \f[B]$IMAGE_VERSION\f[R] to any build
955 scripts invoked (which may be useful to patch it into
956 \f[B]/usr/lib/os\-release\f[R] or similar, in particular the
957 \f[B]IMAGE_VERSION=\f[R] field of it).
958 .TP
959 \f[B]ImageId=\f[R], \f[B]\-\-image\-id=\f[R]
960 Configure the image identifier.
961 This accepts a freeform string that shall be used to identify the image
962 with.
963 If set the default output file will be named after it (possibly suffixed
964 with the version).
965 The identifier is also passed via the \f[B]$IMAGE_ID\f[R] to any build
966 scripts invoked.
967 The image ID is automatically added to \f[B]/usr/lib/os\-release\f[R].
968 .TP
969 \f[B]SplitArtifacts=\f[R], \f[B]\-\-split\-artifacts=\f[R]
970 The artifact types to split out of the final image.
971 A comma\-delimited list consisting of \f[B]uki\f[R], \f[B]kernel\f[R],
972 \f[B]initrd\f[R], \f[B]os\-release\f[R], \f[B]prcs\f[R],
973 \f[B]partitions\f[R], \f[B]roothash\f[R],
974 \f[B]kernel\-modules\-initrd\f[R], \f[B]repart\-definitions\f[R] and
975 \f[B]tar\f[R].
976 When building a bootable image \f[B]kernel\f[R] and \f[B]initrd\f[R]
977 correspond to their artifact found in the image (or in the UKI), while
978 \f[B]uki\f[R] copies out the entire UKI.
979 If \f[B]pcrs\f[R] is specified, a JSON file containing the
980 pre\-calculated TPM2 digests is written out, according to the \c
981 .UR https://uapi-group.org/specifications/specs/unified_kernel_image/#json-format-for-pcrsig
982 UKI specification
983 .UE \c
984 , which is useful for offline signing.
985 .RS
986 .PP
987 When building a disk image and \f[B]partitions\f[R] is specified, pass
988 \f[B]\-\-split=yes\f[R] to \f[B]systemd\-repart\f[R] to have it write
989 out split partition files for each configured partition.
990 Read the \c
991 .UR https://www.freedesktop.org/software/systemd/man/systemd-repart.html#--split=BOOL
992 man
993 .UE \c
994 \ page for more information.
995 This is useful in A/B update scenarios where an existing disk image
996 shall be augmented with a new version of a root or \f[B]/usr\f[R]
997 partition along with its Verity partition and unified kernel.
998 .PP
999 When \f[B]tar\f[R] is specified, the rootfs is additionally archived as
1000 a tar archive (compressed according to \f[B]CompressOutput=\f[R]).
1001 .PP
1002 When \f[B]roothash\f[R] is specified and a dm\-verity disk image is
1003 built, the dm\-verity roothash is written out as a separate file, which
1004 is useful for offline signing.
1005 .PP
1006 \f[B]kernel\-modules\-initrd\f[R] corresponds to the separate kernel
1007 modules initrd which mkosi appends to the main initrd.
1008 This is primarily intended for debugging as many initrd inspection tools
1009 don\[cq]t properly handle multiple initrds appended to each other.
1010 .PP
1011 When \f[B]repart\-definitions\f[R] is specified, a directory containing
1012 the used repart definition files is written to the output directory.
1013 If multiple directories are configured via \f[B]RepartDirectories=\f[R],
1014 they are merged, with later directories taking priority over earlier
1015 ones when files with identical names exist.
1016 .PP
1017 By default \f[B]uki\f[R], \f[B]kernel\f[R] and \f[B]initrd\f[R] are
1018 split out.
1019 .RE
1020 .TP
1021 \f[B]RepartDirectories=\f[R], \f[B]\-\-repart\-directory=\f[R]
1022 Paths to directories containing \f[B]systemd\-repart\f[R] partition
1023 definition files that are used when \f[B]mkosi\f[R] invokes
1024 \f[B]systemd\-repart\f[R] when building a disk image.
1025 If \f[B]mkosi.repart/\f[R] exists in the local directory, it will be
1026 used for this purpose as well.
1027 Note that \f[B]mkosi\f[R] invokes repart with \f[B]\-\-root=\f[R] set to
1028 the root of the image root, so any \f[B]CopyFiles=\f[R] source paths in
1029 partition definition files will be relative to the image root directory.
1030 .TP
1031 \f[B]SectorSize=\f[R], \f[B]\-\-sector\-size=\f[R]
1032 Override the default sector size that \f[B]systemd\-repart\f[R] uses
1033 when building a disk image.
1034 .TP
1035 \f[B]Overlay=\f[R], \f[B]\-\-overlay=\f[R]
1036 When used together with \f[B]BaseTrees=\f[R], the output will consist
1037 only out of changes to the specified base trees.
1038 Each base tree is attached as a lower layer in an overlayfs structure,
1039 and the output becomes the upper layer, initially empty.
1040 Thus files that are not modified compared to the base trees will not be
1041 present in the final output.
1042 .RS
1043 .PP
1044 This option may be used to create \c
1045 .UR https://uapi-group.org/specifications/specs/extension_image
1046 systemd \f[I]system extensions\f[R]
1047 .UE \c
1048 \&.
1049 .RE
1050 .TP
1051 \f[B]Seed=\f[R], \f[B]\-\-seed=\f[R]
1052 Takes a UUID as argument or the special value \f[B]random\f[R].
1053 Overrides the seed that \f[B]systemd\-repart\f[R] uses when building a
1054 disk image.
1055 This is useful to achieve reproducible builds, where deterministic UUIDs
1056 and other partition metadata should be derived on each build.
1057 If not specified explicitly and the file \f[B]mkosi.seed\f[R] exists in
1058 the local directory, the UUID to use is read from it.
1059 Otherwise, a random UUID is used.
1060 .TP
1061 \f[B]CleanScripts=\f[R], \f[B]\-\-clean\-script=\f[R]
1062 Takes a comma\-separated list of paths to executables that are used as
1063 the clean scripts for this image.
1064 See the \f[B]SCRIPTS\f[R] section for more information.
1065 .SS [Content] Section
1066 .TP
1067 \f[B]Packages=\f[R], \f[B]\-\-package=\f[R], \f[B]\-p\f[R]
1068 Install the specified distribution packages (i.e.\ RPM, deb, \&...)
1069 in the image.
1070 Takes a comma\-separated list of package specifications.
1071 This option may be used multiple times in which case the specified
1072 package lists are combined.
1073 Use \f[B]BuildPackages=\f[R] to specify packages that shall only be
1074 installed in an overlay that is mounted when the prepare scripts are
1075 executed with the \f[B]build\f[R] argument and when the build scripts
1076 are executed.
1077 .RS
1078 .PP
1079 The types and syntax of \f[I]package specifications\f[R] that are
1080 allowed depend on the package installer (e.g.\ \f[B]dnf\f[R] for
1081 RPM\-based distros or \f[B]apt\f[R] for deb\-based distros), but may
1082 include package names, package names with version and/or architecture,
1083 package name globs, package groups, and virtual provides, including file
1084 paths.
1085 .PP
1086 See \f[B]PackageDirectories=\f[R] for information on how to make local
1087 packages available for installation with \f[B]Packages=\f[R].
1088 .PP
1089 \f[B]Example\f[R]: when using a distro that uses \f[B]dnf\f[R], the
1090 following configuration would install the \f[B]meson\f[R] package (in
1091 the latest version), the 32\-bit version of the
1092 \f[B]libfdisk\-devel\f[R] package, all available packages that start
1093 with the \f[B]git\-\f[R] prefix, a \f[B]systemd\f[R] RPM from the local
1094 file system, one of the packages that provides \f[B]/usr/bin/ld\f[R],
1095 the packages in the \f[I]Development Tools\f[R] group, and the package
1096 that contains the \f[B]mypy\f[R] python module.
1097 .IP
1098 .EX
1099 Packages=meson
1100 libfdisk\-devel.i686
1101 git\-*
1102 /usr/bin/ld
1103 \[at]development\-tools
1104 python3dist(mypy)
1105 .EE
1106 .RE
1107 .TP
1108 \f[B]BuildPackages=\f[R], \f[B]\-\-build\-package=\f[R]
1109 Similar to \f[B]Packages=\f[R], but configures packages to install only
1110 in an overlay that is made available on top of the image to the prepare
1111 scripts when executed with the \f[B]build\f[R] argument and the build
1112 scripts.
1113 This option should be used to list packages containing header files,
1114 compilers, build systems, linkers and other build tools the
1115 \f[B]mkosi.build\f[R] scripts require to operate.
1116 Note that packages listed here will be absent in the final image.
1117 .TP
1118 \f[B]VolatilePackages=\f[R], \f[B]\-\-volatile\-package=\f[R]
1119 Similar to \f[B]Packages=\f[R], but packages configured with this
1120 setting are not cached when \f[B]Incremental=\f[R] is enabled and are
1121 installed after executing any build scripts.
1122 .RS
1123 .PP
1124 Specifically, this setting can be used to install packages that change
1125 often or which are built by a build script.
1126 .RE
1127 .TP
1128 \f[B]PackageDirectories=\f[R], \f[B]\-\-package\-directory=\f[R]
1129 Specify directories containing extra packages to be made available
1130 during the build.
1131 \f[B]mkosi\f[R] will create a local repository containing all packages
1132 in these directories and make it available when installing packages or
1133 running scripts.
1134 If the \f[B]mkosi.packages/\f[R] directory is found in the local
1135 directory it is also used for this purpose.
1136 .TP
1137 \f[B]VolatilePackageDirectories=\f[R], \f[B]\-\-volatile\-package\-directory=\f[R]
1138 Like \f[B]PackageDirectories=\f[R], but any changes to the packages in
1139 these directories will not invalidate the cached images if
1140 \f[B]Incremental=\f[R] is enabled.
1141 .RS
1142 .PP
1143 Additionally, build scripts can add more packages to the local
1144 repository by placing the built packages in \f[B]$PACKAGEDIR\f[R].
1145 The packages placed in \f[B]$PACKAGEDIR\f[R] are shared between all
1146 image builds and thus available for installation in all images using
1147 \f[B]VolatilePackages=\f[R].
1148 .RE
1149 .TP
1150 \f[B]WithRecommends=\f[R], \f[B]\-\-with\-recommends=\f[R]
1151 Configures whether to install recommended or weak dependencies,
1152 depending on how they are named by the used package manager, or not.
1153 By default, recommended packages are not installed.
1154 This is only used for package managers that support the concept, which
1155 are currently \f[B]apt\f[R], \f[B]dnf\f[R] and \f[B]zypper\f[R].
1156 .TP
1157 \f[B]WithDocs=\f[R], \f[B]\-\-with\-docs=\f[R]
1158 Include documentation in the image.
1159 Enabled by default.
1160 When disabled, if the underlying distribution package manager supports
1161 it documentation is not included in the image.
1162 The \f[B]$WITH_DOCS\f[R] environment variable passed to the
1163 \f[B]mkosi.build\f[R] scripts is set to \f[B]0\f[R] or \f[B]1\f[R]
1164 depending on whether this option is enabled or disabled.
1165 .TP
1166 \f[B]BaseTrees=\f[R], \f[B]\-\-base\-tree=\f[R]
1167 Takes a comma\-separated list of paths to use as base trees.
1168 When used, these base trees are each copied into the OS tree and form
1169 the base distribution instead of installing the distribution from
1170 scratch.
1171 Only extra packages are installed on top of the ones already installed
1172 in the base trees.
1173 Note that for this to work properly, the base image still needs to
1174 contain the package manager metadata by setting
1175 \f[B]CleanPackageMetadata=no\f[R] (see \f[B]CleanPackageMetadata=\f[R]).
1176 .RS
1177 .PP
1178 Instead of a directory, a tar file or a disk image may be provided.
1179 In this case it is unpacked into the OS tree.
1180 This mode of operation allows setting permissions and file ownership
1181 explicitly, in particular for projects stored in a version control
1182 system such as \f[B]git\f[R] which retain full file ownership and access
1183 mode metadata for committed files.
1184 .RE
1185 .TP
1186 \f[B]SkeletonTrees=\f[R], \f[B]\-\-skeleton\-tree=\f[R]
1187 Takes a comma\-separated list of colon\-separated path pairs.
1188 The first path of each pair refers to a directory to copy into the OS
1189 tree before invoking the package manager.
1190 The second path of each pair refers to the target directory inside the
1191 image.
1192 If the second path is not provided, the directory is copied on top of
1193 the root directory of the image.
1194 The second path is always interpreted as an absolute path.
1195 Use this to insert files and directories into the OS tree before the
1196 package manager installs any packages.
1197 If the \f[B]mkosi.skeleton/\f[R] directory is found in the local
1198 directory it is also used for this purpose with the root directory as
1199 target (also see the \f[B]FILES\f[R] section below).
1200 .RS
1201 .PP
1202 Note that skeleton trees are cached and any changes to skeleton trees
1203 after a cached image has been built (when using \f[B]Incremental=\f[R])
1204 are only applied when the cached image is rebuilt (by using
1205 \f[B]\-ff\f[R] or running \f[B]mkosi \-f clean\f[R]).
1206 .PP
1207 As with the base tree logic above, instead of a directory, a tar file
1208 may be provided too.
1209 \f[B]mkosi.skeleton.tar\f[R] will be automatically used if found in the
1210 local directory.
1211 .PP
1212 To add extra package manager configuration files such as extra
1213 repositories, use \f[B]SandboxTrees=\f[R] as \f[B]mkosi\f[R] invokes the
1214 package managers from outside the image and not inside so any package
1215 manager configuration files provided via \f[B]SkeletonTrees=\f[R]
1216 won\[cq]t take effect when \f[B]mkosi\f[R] invokes a package manager to
1217 install packages.
1218 .RE
1219 .TP
1220 \f[B]ExtraTrees=\f[R], \f[B]\-\-extra\-tree=\f[R]
1221 Takes a comma\-separated list of colon\-separated path pairs.
1222 The first path of each pair refers to a directory to copy from the host
1223 into the image.
1224 The second path of each pair refers to the target directory inside the
1225 image.
1226 If the second path is not provided, the directory is copied on top of
1227 the root directory of the image.
1228 The second path is always interpreted as an absolute path.
1229 Use this to override any default configuration files shipped with the
1230 distribution.
1231 If the \f[B]mkosi.extra/\f[R] directory is found in the local directory
1232 it is also used for this purpose with the root directory as target (also
1233 see the \f[B]FILES\f[R] section below).
1234 .RS
1235 .PP
1236 As with the base tree logic above, instead of a directory, a tar file
1237 may be provided too.
1238 \f[B]mkosi.extra.tar\f[R] will be automatically used if found in the
1239 local directory.
1240 .RE
1241 .TP
1242 \f[B]RemovePackages=\f[R], \f[B]\-\-remove\-package=\f[R]
1243 Takes a comma\-separated list of package specifications for removal, in
1244 the same format as \f[B]Packages=\f[R].
1245 The removal will be performed as one of the last steps.
1246 This step is skipped if \f[B]CleanPackageMetadata=no\f[R] is used.
1247 .TP
1248 \f[B]RemoveFiles=\f[R], \f[B]\-\-remove\-files=\f[R]
1249 Takes a comma\-separated list of globs.
1250 Files in the image matching the globs will be purged at the end.
1251 .TP
1252 \f[B]CleanPackageMetadata=\f[R], \f[B]\-\-clean\-package\-metadata=\f[R]
1253 Enable/disable removal of package manager databases and repository
1254 metadata at the end of installation.
1255 Can be specified as \f[B]true\f[R], \f[B]false\f[R], or \f[B]auto\f[R]
1256 (the default).
1257 With \f[B]auto\f[R], package manager databases and repository metadata
1258 will be removed if the respective package manager executable is
1259 \f[I]not\f[R] present at the end of the installation.
1260 .TP
1261 \f[B]SourceDateEpoch=\f[R], \f[B]\-\-source\-date\-epoch=\f[R]
1262 Takes a timestamp in seconds since the UNIX epoch as argument.
1263 File modification times of all files will be clamped to this value.
1264 The variable is also propagated to \f[B]systemd\-repart\f[R] and scripts
1265 executed by \f[B]mkosi\f[R].
1266 If not set explicitly, \f[B]SOURCE_DATE_EPOCH\f[R] from
1267 \f[B]\-\-environment=\f[R] and from the host environment are tried in
1268 that order.
1269 This is useful to make builds reproducible.
1270 See \c
1271 .UR https://reproducible-builds.org/specs/source-date-epoch/
1272 SOURCE_DATE_EPOCH
1273 .UE \c
1274 \ for more information.
1275 .TP
1276 \f[B]SyncScripts=\f[R], \f[B]\-\-sync\-script=\f[R]
1277 Takes a comma\-separated list of paths to executables that are used as
1278 the sync scripts for this image.
1279 See the \f[B]SCRIPTS\f[R] section for more information.
1280 .TP
1281 \f[B]PrepareScripts=\f[R], \f[B]\-\-prepare\-script=\f[R]
1282 Takes a comma\-separated list of paths to executables that are used as
1283 the prepare scripts for this image.
1284 See the \f[B]SCRIPTS\f[R] section for more information.
1285 .TP
1286 \f[B]BuildScripts=\f[R], \f[B]\-\-build\-script=\f[R]
1287 Takes a comma\-separated list of paths to executables that are used as
1288 the build scripts for this image.
1289 See the \f[B]SCRIPTS\f[R] section for more information.
1290 .TP
1291 \f[B]PostInstallationScripts=\f[R], \f[B]\-\-postinst\-script=\f[R]
1292 Takes a comma\-separated list of paths to executables that are used as
1293 the post\-installation scripts for this image.
1294 See the \f[B]SCRIPTS\f[R] section for more information.
1295 .TP
1296 \f[B]FinalizeScripts=\f[R], \f[B]\-\-finalize\-script=\f[R]
1297 Takes a comma\-separated list of paths to executables that are used as
1298 the finalize scripts for this image.
1299 See the \f[B]SCRIPTS\f[R] section for more information.
1300 .TP
1301 \f[B]PostOutputScripts=\f[R], \f[B]\-\-postoutput\-script=\f[R]
1302 Takes a comma\-separated list of paths to executables that are used as
1303 the post output scripts for this image.
1304 See the \f[B]SCRIPTS\f[R] section for more information.
1305 .TP
1306 \f[B]Bootable=\f[R], \f[B]\-\-bootable=\f[R]
1307 Takes a boolean or \f[B]auto\f[R].
1308 Enables or disables generation of a bootable image.
1309 If enabled, \f[B]mkosi\f[R] will install an EFI bootloader, and add an
1310 ESP partition when the disk image output is used.
1311 If the selected EFI bootloader (see \f[B]Bootloader=\f[R]) is not
1312 installed or no kernel images can be found, the build will fail.
1313 \f[B]auto\f[R] behaves as if the option was enabled, but the build
1314 won\[cq]t fail if either no kernel images or the selected EFI bootloader
1315 can\[cq]t be found.
1316 If disabled, no bootloader will be installed even if found inside the
1317 image, no unified kernel images will be generated and no ESP partition
1318 will be added to the image if the disk output format is used.
1319 .RS
1320 .PP
1321 If the \f[B]esp\f[R] output format is used, an ESP partition and
1322 bootloader are always added, and the \f[B]Bootable=\f[R] option only
1323 controls whether a UKI is added to the ESP partition or not.
1324 .RE
1325 .TP
1326 \f[B]Bootloader=\f[R], \f[B]\-\-bootloader=\f[R]
1327 Takes one of \f[B]none\f[R], \f[B]systemd\-boot\f[R], \f[B]uki\f[R],
1328 \f[B]grub\f[R], \f[B]systemd\-boot\-signed\f[R], \f[B]uki\-signed\f[R]
1329 or \f[B]grub\-signed\f[R].
1330 Defaults to \f[B]systemd\-boot\f[R].
1331 If set to \f[B]none\f[R], no EFI bootloader will be installed into the
1332 image.
1333 If set to \f[B]systemd\-boot\f[R], \f[B]systemd\-boot\f[R] will be
1334 installed and for each installed kernel, a UKI will be generated and
1335 stored in \f[B]EFI/Linux\f[R] in the ESP.
1336 If set to \f[B]uki\f[R], a single UKI will be generated for the latest
1337 installed kernel (the one with the highest version) which is installed
1338 to \f[B]EFI/BOOT/BOOTX64.EFI\f[R] in the ESP.
1339 If set to \f[B]grub\f[R], for each installed kernel, a UKI will be
1340 generated and stored in \f[B]EFI/Linux\f[R] in the ESP.
1341 For each generated UKI, a menu entry is appended to the grub
1342 configuration in \f[B]grub/grub.cfg\f[R] in the ESP which chainloads
1343 into the UKI.
1344 A shim grub.cfg is also written to \f[B]EFI/<distribution>/grub.cfg\f[R]
1345 in the ESP which loads \f[B]grub/grub.cfg\f[R] in the ESP for
1346 compatibility with signed versions of grub which load the grub
1347 configuration from this location.
1348 .RS
1349 .PP
1350 The \f[B]signed\f[R] variants will only install pre\-signed EFI binaries
1351 shipped by the distribution.
1352 .PP
1353 Kernels need to be placed into the root filesystem (for example using
1354 \f[B]ExtraTrees=\f[R]) under \f[B]/usr/lib/modules/$version\f[R], named
1355 \f[B]vmlinux\f[R] or \f[B]vmlinuz\f[R].
1356 The \f[B]$version\f[R] is as produced by Kbuild\[cq]s
1357 \f[B]kernelversion\f[R] make target.
1358 .PP
1359 Note: When using \f[B]systemd\-boot\f[R] or
1360 \f[B]systemd\-boot\-signed\f[R], \f[B]mkosi\f[R] expects the
1361 \f[B]systemd\-boot\f[R] EFI binaries to be present in the image.
1362 Depending on your distribution, these may be packaged separately.
1363 For example, Debian\- based images will need
1364 \f[B]systemd\-boot\-efi\f[R].
1365 .RE
1366 .TP
1367 \f[B]BiosBootloader=\f[R], \f[B]\-\-bios\-bootloader=\f[R]
1368 Takes one of \f[B]none\f[R] or \f[B]grub\f[R].
1369 Defaults to \f[B]none\f[R].
1370 If set to \f[B]none\f[R], no BIOS bootloader will be installed.
1371 If set to \f[B]grub\f[R], grub is installed as the BIOS boot loader if a
1372 bootable image is requested with the \f[B]Bootable=\f[R] option.
1373 If no repart partition definition files are configured, \f[B]mkosi\f[R]
1374 will add a grub BIOS boot partition and an EFI system partition to the
1375 default partition definition files.
1376 .RS
1377 .PP
1378 Note that this option is not mutually exclusive with
1379 \f[B]Bootloader=\f[R].
1380 It is possible to have an image that is both bootable on UEFI and BIOS
1381 by configuring both \f[B]Bootloader=\f[R] and \f[B]BiosBootloader=\f[R].
1382 .PP
1383 The grub BIOS boot partition should have UUID
1384 \f[B]21686148\-6449\-6e6f\-744e\-656564454649\f[R] and should be at
1385 least 1MB.
1386 .PP
1387 Even if no EFI bootloader is installed, we still need an ESP for BIOS
1388 boot as that\[cq]s where we store the kernel, initrd and grub modules.
1389 .RE
1390 .TP
1391 \f[B]ShimBootloader=\f[R], \f[B]\-\-shim\-bootloader=\f[R]
1392 Takes one of \f[B]none\f[R], \f[B]unsigned\f[R], or \f[B]signed\f[R].
1393 Defaults to \f[B]none\f[R].
1394 If set to \f[B]none\f[R], shim and MokManager will not be installed to
1395 the ESP.
1396 If set to \f[B]unsigned\f[R], \f[B]mkosi\f[R] will search for unsigned
1397 shim and MokManager EFI binaries and install them.
1398 If \f[B]SecureBoot=\f[R] is enabled, \f[B]mkosi\f[R] will sign the
1399 unsigned EFI binaries before installing them.
1400 If set to \f[B]signed\f[R], \f[B]mkosi\f[R] will search for signed EFI
1401 binaries and install those.
1402 Even if \f[B]SecureBoot=\f[R] is enabled, \f[B]mkosi\f[R] won\[cq]t sign
1403 these binaries again.
1404 .RS
1405 .PP
1406 Note that this option only takes effect when an image that is bootable
1407 on UEFI firmware is requested using other options (\f[B]Bootable=\f[R],
1408 \f[B]Bootloader=\f[R]).
1409 .PP
1410 Note that when this option is enabled, \f[B]mkosi\f[R] will only install
1411 already signed bootloader binaries, kernel image files and unified
1412 kernel images as self\-signed binaries would not be accepted by the
1413 signed version of shim.
1414 .RE
1415 .TP
1416 \f[B]UnifiedKernelImages=\f[R], \f[B]\-\-unified\-kernel\-images=\f[R]
1417 Specifies whether to use unified kernel images or not when
1418 \f[B]Bootloader=\f[R] is set to \f[B]systemd\-boot\f[R] or
1419 \f[B]grub\f[R].
1420 Takes one of \f[B]none\f[R], \f[B]unsigned\f[R], \f[B]signed\f[R] or
1421 \f[B]auto\f[R].
1422 Defaults to \f[B]auto\f[R].
1423 If \f[B]unsigned\f[R] or \f[B]signed\f[R], unified kernel images are
1424 always used and the build will fail if any components required to build
1425 unified kernel images are missing.
1426 If set to \f[B]auto\f[R], unified kernel images will be used if all
1427 necessary components are available.
1428 Otherwise Type 1 entries as defined by the Boot Loader Specification
1429 will be used instead.
1430 If disabled, Type 1 entries will always be used.
1431 If \f[B]Bootloader=\f[R] is set to one of the signed variant, a
1432 pre\-built UKI will be searched and the build will fail if it cannot be
1433 found, unless \f[B]UnifiedKernelImages=\f[R] is set to
1434 \f[B]unsigned\f[R], in which case the UKI will be built locally.
1435 This is useful when combined with the runtime \f[B]Firmware=\f[R] option
1436 set to \f[B]custom\f[R] so that the local signing key is enrolled in
1437 UEFI db.
1438 .TP
1439 \f[B]UnifiedKernelImageFormat=\f[R], \f[B]\-\-unified\-kernel\-image\-format=\f[R]
1440 Takes a filename without any path components to specify the format that
1441 unified kernel images should be installed as.
1442 This may include both the regular specifiers (see \f[B]Specifiers\f[R])
1443 and special delayed specifiers, that are expanded during the
1444 installation of the files, which are described below.
1445 The default format for this parameter is \f[B]&e\-&k\f[R] with
1446 \f[B]\-&h\f[R] being appended if \f[B]roothash=\f[R] or
1447 \f[B]usrhash=\f[R] is found on the kernel command line and \f[B]+&c\f[R]
1448 if \f[B]/etc/kernel/tries\f[R] is found in the image.
1449 .RS
1450 .PP
1451 The following specifiers may be used:
1452 .PP
1453 .TS
1454 tab(@);
1455 l l.
1456 T{
1457 Specifier
1458 T}@T{
1459 Value
1460 T}
1461 _
1462 T{
1463 \f[B]&&\f[R]
1464 T}@T{
1465 \f[B]&\f[R] character
1466 T}
1467 T{
1468 \f[B]&e\f[R]
1469 T}@T{
1470 Entry Token
1471 T}
1472 T{
1473 \f[B]&k\f[R]
1474 T}@T{
1475 Kernel version
1476 T}
1477 T{
1478 \f[B]&h\f[R]
1479 T}@T{
1480 \f[B]roothash=\f[R] or \f[B]usrhash=\f[R] value of kernel argument
1481 T}
1482 .TE
1483 .RE
1484 .TP
1485 \f[B]UnifiedKernelImageProfiles=\f[R], \f[B]\-\-uki\-profile=\f[R]
1486 Build additional UKI profiles.
1487 Takes a comma\-separated list of paths to UKI profile config files.
1488 This option may be used multiple times in which case each config gets
1489 built into a corresponding UKI profile.
1490 Config files in the \f[B]mkosi.uki\-profiles/\f[R] directory are
1491 automatically picked up.
1492 All configured UKI profiles are added as additional UKI profiles to each
1493 UKI built by \f[B]mkosi\f[R].
1494 .RS
1495 .PP
1496 See the documentation for the \f[B]UKIProfile\f[R] section for
1497 information on which settings can be configured in UKI profile config
1498 files.
1499 .RE
1500 .TP
1501 \f[B]Initrds=\f[R], \f[B]\-\-initrd=\f[R]
1502 Use user\-provided initrd(s).
1503 Takes a comma\-separated list of paths to initrd files.
1504 This option may be used multiple times in which case the initrd lists
1505 are combined.
1506 If no initrds are specified and a bootable image is requested,
1507 \f[B]mkosi\f[R] will automatically build a default initrd.
1508 .RS
1509 .PP
1510 \f[B]mkosi\f[R] will also look for initrds in a subdirectory
1511 \f[B]io.mkosi.initrd\f[R] of the artifact directory (see
1512 \f[B]$ARTIFACTDIR\f[R] in the section \f[B]ENVIRONMENT VARIABLES\f[R]).
1513 Any initrds found there are appended to the user\-provided initrd(s) and
1514 any default initrd built by mkosi.
1515 .RE
1516 .TP
1517 \f[B]InitrdProfiles=\f[R], \f[B]\-\-initrd\-profile=\f[R]
1518 Set the profiles to enable for the default initrd.
1519 Takes a comma\-delimited list of profiles.
1520 By default, all profiles are disabled.
1521 .RS
1522 .PP
1523 The \f[B]lvm\f[R] profile enables support for LVM.
1524 The \f[B]network\f[R] profile enables support for network via
1525 \f[B]systemd\-networkd\f[R].
1526 The \f[B]nfs\f[R] profile enables support for NFS.
1527 It requires networking in the initrd, using the \f[B]network\f[R]
1528 profile, or some other custom method.
1529 The \f[B]pkcs11\f[R] profile enables support for PKCS#11.
1530 The \f[B]plymouth\f[R] profile provides a graphical interface at boot
1531 (animation and password prompt).
1532 The \f[B]raid\f[R] profile enables support for RAID arrays.
1533 .RE
1534 .TP
1535 \f[B]InitrdPackages=\f[R], \f[B]\-\-initrd\-package=\f[R]
1536 Extra packages to install into the default initrd.
1537 Takes a comma separated list of package specifications.
1538 This option may be used multiple times in which case the specified
1539 package lists are combined.
1540 .TP
1541 \f[B]InitrdVolatilePackages=\f[R], \f[B]\-\-initrd\-volatile\-package=\f[R]
1542 Similar to \f[B]VolatilePackages=\f[R], except it applies to the default
1543 initrd.
1544 .TP
1545 \f[B]Devicetrees=\f[R], \f[B]\-\-devicetrees=\f[R]
1546 Comma\-separated list of devicetree patterns for automatic
1547 hardware\-based selection.
1548 Patterns are glob expressions.
1549 \f[B]mkosi\f[R] searches for devicetree files in standard locations
1550 relative to \f[B]/usr/lib/modules/<kver>/dtb/\f[R],
1551 \f[B]/usr/lib/firmware/<kver>/device\-tree/\f[R], and
1552 \f[B]/usr/lib/linux\-image\-<kver>/\f[R].
1553 .RS
1554 .PP
1555 For UKI builds, multiple matches enable automatic hardware\-based
1556 selection using the \f[B].dtbauto\f[R] sections.
1557 Type 1 boot entries require exactly one match.
1558 .PP
1559 Example: \f[B]Devicetrees=rockchip/*,imx.*\f[R] would include all
1560 Rockchip devicetrees and any IMX devicetrees.
1561 .RE
1562 .TP
1563 \f[B]Splash=\f[R], \f[B]\-\-splash=\f[R]
1564 When set, the boot splash for any unified kernel image built by
1565 \f[B]mkosi\f[R] will be picked up from the given path inside the image.
1566 .TP
1567 \f[B]MicrocodeHost=\f[R], \f[B]\-\-microcode\-host=\f[R]
1568 When set to true only include microcode for the host\[cq]s CPU in the
1569 image.
1570 .TP
1571 \f[B]KernelCommandLine=\f[R], \f[B]\-\-kernel\-command\-line=\f[R]
1572 Use the specified kernel command line when building images.
1573 .RS
1574 .PP
1575 If the root or usr partition are created with verity enabled,
1576 \f[B]roothash=\f[R] or \f[B]usrhash=\f[R] respectively are automatically
1577 added to the kernel command line and \f[B]root=\f[R] or
1578 \f[B]mount.usr=\f[R] should not be added.
1579 Otherwise, if the value of this setting contains the literals
1580 \f[B]root=PARTUUID\f[R] or \f[B]mount.usr=PARTUUID\f[R], these are
1581 replaced with the partition UUID of the root or usr partition
1582 respectively.
1583 For example, \f[B]root=PARTUUID\f[R] would be replaced with
1584 \f[B]root=PARTUUID=58c7d0b2\-d224\-4834\-a16f\-e036322e88f7\f[R] where
1585 \f[B]58c7d0b2\-d224\-4834\-a16f\-e036322e88f7\f[R] is the partition UUID
1586 of the root partition.
1587 .RE
1588 .TP
1589 \f[B]KernelModules=\f[R], \f[B]\-\-kernel\-modules=\f[R]
1590 Takes a list of glob patterns that specify which kernel modules to
1591 include in the image.
1592 Each argument may be prefixed with a dash (\f[B]\-\f[R]), to
1593 \f[I]exclude\f[R] matching modules.
1594 The arguments are evaluated in order, the last positive or negative
1595 matching pattern determines the result.
1596 The modules that were last matched by a positive pattern are included in
1597 the image, as well as their module and firmware dependencies.
1598 .RS
1599 .PP
1600 The \f[B].ko\f[R] suffix and compression suffix are ignored during
1601 matching.
1602 .PP
1603 Globs are matched against module paths relative to
1604 \f[B]/usr/lib/module/<kver>\f[R], e.g.\ the module at
1605 \f[B]/usr/lib/module/<kver>/kernel/foo/bar.ko.xz\f[R] becomes
1606 \f[B]kernel/foo/bar\f[R] for matching purposes.
1607 .PP
1608 Globs beginning with \[lq]/\[rq] are treated specially.
1609 The glob is \f[I]first\f[R] matched against a path relative to
1610 \f[B]/usr/lib/module/<kver>/kernel\f[R], and only then against
1611 \f[B]/usr/lib/module/<kver>/\f[R].
1612 This is a convenience, since usually only the in\-tree modules under
1613 \f[B]kernel/\f[R] are of interest.
1614 .PP
1615 For example, the module
1616 at\f[B]/usr/lib/module/<kver>/kernel/foo/bar.ko.xz\f[R] can be matched
1617 by either \f[B]/foo/bar\f[R] or \f[B]/kernel/foo/bar\f[R].
1618 .PP
1619 The glob patterns may include just the basename (e.g.\ \f[B]loop\f[R]),
1620 which must match the basename of the module, the relative path
1621 (e.g.\ \f[B]block/loop\f[R]), which must match the final components of
1622 the module path up to the basename, or an absolute path
1623 (e.g.\ \f[B]/drivers/block/loop\f[R]), which must match the full path to
1624 the module.
1625 .PP
1626 When suffixed with \f[B]/\f[R], the pattern will match all modules
1627 underneath that directory.
1628 .PP
1629 The patterns may include shell\-style globs (\f[B]*\f[R], \f[B]?\f[R],
1630 \f[B][\&...\-\&...]\f[R]).
1631 .PP
1632 If the special value \f[B]default\f[R] is used, the default kernel
1633 modules defined in the \f[B]mkosi\-initrd\f[R] configuration are
1634 included as well.
1635 .PP
1636 If the special value \f[B]host\f[R] is used, the currently loaded
1637 modules on the host system are included as well.
1638 .RE
1639 .TP
1640 \f[B]KernelModulesInitrd=\f[R], \f[B]\-\-kernel\-modules\-initrd=\f[R]
1641 Boolean value, enabled (true) by default.
1642 If enabled, when building a bootable image, \f[B]mkosi\f[R] will
1643 generate an extra initrd for each unified kernel image it assembles.
1644 This initrd contains only modules and possibly firmware, and is then
1645 appended to the base initrd to form the final initrd file.
1646 This keeps the base initrd kernel independent, and only augments it with
1647 the necessary kernel\-version specific modules when the UKI is
1648 assembled.
1649 .RS
1650 .PP
1651 If disabled, no extra initrd is generated.
1652 Note that the kernel modules will still \f[B]not\f[R] be included in the
1653 base initrd, which remains kernel independent.
1654 Instead, it is assumed the user provides the necessary modules, if any,
1655 via an additional custom initrd.
1656 .RE
1657 .TP
1658 \f[B]KernelInitrdModules=\f[R], \f[B]\-\-kernel\-modules\-initrd\-include=\f[R]
1659 Like \f[B]KernelModules=\f[R], but specifies the kernel modules to
1660 include in the initrd.
1661 .TP
1662 \f[B]FirmwareFiles=\f[R], \f[B]\-\-firmware\-files=\f[R]
1663 Takes a list of glob patterns that specify which firmware files to
1664 include in the image.
1665 The patterns are interpreted in the same way as in the
1666 \f[B]KernelModules=\f[R] settings, except that the paths are relative to
1667 \f[B]/usr/lib/firmware/<subdir>\f[R].
1668 The compression suffix is ignored and must not be included in the
1669 pattern.
1670 .RS
1671 .PP
1672 Firmware dependencies of kernel modules installed in the image are
1673 automatically included.
1674 .PP
1675 Example: \f[B]FirmwareFiles=cxgb4/bcm8483.bin\f[R] or
1676 \f[B]FirmwareFiles=bcm8483.*\f[R] would both cause
1677 \f[B]/usr/lib/firmware/cxgb4/bcm8483.bin.xz\f[R] to be included, even if
1678 not listed by a module.
1679 .RE
1680 .TP
1681 \f[B]Locale=\f[R], \f[B]\-\-locale=\f[R], \f[B]LocaleMessages=\f[R], \f[B]\-\-locale\-messages=\f[R], \f[B]Keymap=\f[R], \f[B]\-\-keymap=\f[R], \f[B]Timezone=\f[R], \f[B]\-\-timezone=\f[R], \f[B]Hostname=\f[R], \f[B]\-\-hostname=\f[R], \f[B]RootShell=\f[R], \f[B]\-\-root\-shell=\f[R]
1682 The settings \f[B]Locale=\f[R], \f[B]\-\-locale=\f[R],
1683 \f[B]LocaleMessages=\f[R], \f[B]\-\-locale\-messages=\f[R],
1684 \f[B]Keymap=\f[R], \f[B]\-\-keymap=\f[R], \f[B]Timezone=\f[R],
1685 \f[B]\-\-timezone=\f[R], \f[B]Hostname=\f[R], \f[B]\-\-hostname=\f[R],
1686 \f[B]RootShell=\f[R], \f[B]\-\-root\-shell=\f[R] correspond to the
1687 identically named systemd\-firstboot options.
1688 See \f[B]systemd\-firstboot\f[R](1) for more information.
1689 Additionally, where applicable, the corresponding systemd credentials
1690 for these settings are written to \f[B]/usr/lib/credstore\f[R], so that
1691 they apply even if only \f[B]/usr\f[R] is shipped in the image.
1692 .TP
1693 \f[B]RootPassword=\f[R], \f[B]\-\-root\-password=\f[R],
1694 Set the system root password.
1695 If this option is not used, but a \f[B]mkosi.rootpw\f[R] file is found
1696 in the local directory, the password is automatically read from it or if
1697 the file is executable it is run as a script and stdout is read instead
1698 (see the \f[B]SCRIPTS\f[R] section below).
1699 If the password starts with \f[B]hashed:\f[R], it is treated as an
1700 already hashed root password.
1701 The root password is also stored in \f[B]/usr/lib/credstore\f[R] under
1702 the appropriate systemd credential so that it applies even if only
1703 \f[B]/usr\f[R] is shipped in the image.
1704 To create an unlocked account without any password use \f[B]hashed:\f[R]
1705 without a hash.
1706 .TP
1707 \f[B]Autologin=\f[R], \f[B]\-\-autologin=\f[R], \f[B]\-a\f[R]
1708 Enable autologin for the \f[B]root\f[R] user on \f[B]/dev/pts/0\f[R]
1709 (nspawn), \f[B]/dev/tty1\f[R] and \f[B]/dev/hvc0\f[R].
1710 .TP
1711 \f[B]MakeInitrd=\f[R], \f[B]\-\-make\-initrd=\f[R]
1712 Add \f[B]/etc/initrd\-release\f[R] and \f[B]/init\f[R] to the image so
1713 that it can be used as an initramfs.
1714 .TP
1715 \f[B]Ssh=\f[R], \f[B]\-\-ssh=\f[R]
1716 Specifies whether to install an \f[B]sshd\f[R] socket unit and matching
1717 service in the final image.
1718 Takes one of \f[B]always\f[R], \f[B]never\f[R], \f[B]auto\f[R] or
1719 \f[B]runtime\f[R].
1720 Defaults to \f[B]auto\f[R].
1721 .RS
1722 .PP
1723 If set to \f[B]auto\f[R] and \f[B]sshd\f[R] is present in the image and
1724 the generator binary \f[B]systemd\-ssh\-generator\f[R] is not present,
1725 or if set to \f[B]always\f[R], mkosi will install \f[B]sshd\f[R] units
1726 in the final image that expose SSH over VSock.
1727 If set to \f[B]never\f[R], mkosi will not install these units.
1728 If the \f[B]runtime\f[R] value is used, mkosi will also not install any
1729 units but abort starting \f[B]mkosi vm\f[R] if no SSH credentials are
1730 configured.
1731 When building with this option and running the image using \f[B]mkosi
1732 vm\f[R], the \f[B]mkosi ssh\f[R] command can be used to connect to the
1733 container/VM via SSH.
1734 Note that you still have to make sure openssh is installed in the image
1735 to make \f[B]mkosi ssh\f[R] behave correctly.
1736 Run \f[B]mkosi genkey\f[R] to automatically generate an X.509
1737 certificate and private key to be used by \f[B]mkosi\f[R] to enable SSH
1738 access to any virtual machines via \f[B]mkosi ssh\f[R].
1739 To access images booted using \f[B]mkosi boot\f[R], use
1740 \f[B]machinectl\f[R].
1741 .PP
1742 Starting with systemd v256, systemd\-ssh\-generator(8) will
1743 automatically provide \f[B]sshd\f[R] over VSock when running inside a
1744 VM.
1745 So if you\[cq]re using a recent version of systemd inside a VM, this
1746 option is generally not used.
1747 You still need openssh installed in the image, and the default setting
1748 of \f[B]\-\-vsock=auto\f[R] is enough to ensure a VSock is available
1749 inside the VM.
1750 .PP
1751 Note: if the image distro uses SELinux, mkosi\[cq]s sshd service will be
1752 denied access to the VSock, resulting in failure to connect to it from
1753 the host.
1754 You will need to either disable SELinux enforcement, or create a custom
1755 policy module (e.g.\ with \f[B]audit2allow\f[R]).
1756 .RE
1757 .TP
1758 \f[B]SELinuxRelabel=\f[R], \f[B]\-\-selinux\-relabel=\f[R]
1759 Specifies whether to relabel files to match the image\[cq]s SELinux
1760 policy.
1761 Takes a boolean value or \f[B]auto\f[R].
1762 Defaults to \f[B]auto\f[R].
1763 If disabled, files will not relabeled.
1764 If enabled, an SELinux policy has to be installed in the image and
1765 \f[B]setfiles\f[R] has to be available to relabel files.
1766 If any errors occur during \f[B]setfiles\f[R], the build will fail.
1767 If set to \f[B]auto\f[R], files will be relabeled if mkosi is not
1768 building a directory image, an SELinux policy is installed in the image
1769 and if \f[B]setfiles\f[R] is available.
1770 Any errors occurred during \f[B]setfiles\f[R] will be ignored.
1771 .RS
1772 .PP
1773 Note that when running unprivileged, \f[B]setfiles\f[R] will fail to set
1774 any labels that are not in the host\[cq]s SELinux policy.
1775 To ensure \f[B]setfiles\f[R] succeeds without errors, make sure to run
1776 \f[B]mkosi\f[R] as root or build from a host system with the same
1777 SELinux policy as the image you\[cq]re building.
1778 .RE
1779 .TP
1780 \f[B]MachineId=\f[R], \f[B]\-\-machine\-id=\f[R]
1781 Takes a UUID or the special value \f[B]random\f[R].
1782 Sets the machine ID of the image to the specified UUID.
1783 If set to \f[B]random\f[R], a random UUID will be written to
1784 \f[B]/etc/machine\-id\f[R].
1785 If not specified explicitly and the file \f[B]mkosi.machine\-id\f[R]
1786 exists in the local directory, the UUID to use is read from it.
1787 Otherwise, \f[B]uninitialized\f[R] will be written to
1788 \f[B]/etc/machine\-id\f[R].
1789 .SS [Validation] Section
1790 .TP
1791 \f[B]SecureBoot=\f[R], \f[B]\-\-secure\-boot=\f[R]
1792 Sign \f[B]systemd\-boot\f[R] (if it is not signed yet) and any generated
1793 unified kernel images for UEFI SecureBoot.
1794 .TP
1795 \f[B]SecureBootAutoEnroll=\f[R], \f[B]\-\-secure\-boot\-auto\-enroll=\f[R]
1796 Set up automatic enrollment of the secure boot keys in virtual machines
1797 as documented in \f[B]systemd\-boot\f[R](7) if \f[B]SecureBoot=\f[R] is
1798 used.
1799 Note that \f[B]systemd\-boot\f[R] will only do automatic secure boot key
1800 enrollment in virtual machines starting from systemd v253.
1801 To do auto enrollment on systemd v252 or on bare metal machines, write a
1802 \f[B]systemd\-boot\f[R] configuration file to
1803 \f[B]/efi/loader/loader.conf\f[R] using an extra tree with
1804 \f[B]secure\-boot\-enroll force\f[R] or \f[B]secure\-boot\-enroll
1805 manual\f[R] in it.
1806 Auto enrollment is not supported on systemd versions older than v252.
1807 Defaults to \f[B]yes\f[R].
1808 .TP
1809 \f[B]SecureBootKey=\f[R], \f[B]\-\-secure\-boot\-key=\f[R]
1810 Path to the PEM file containing the secret key for signing the UEFI
1811 kernel image if \f[B]SecureBoot=\f[R] is used and PCR signatures when
1812 \f[B]SignExpectedPcr=\f[R] is also used.
1813 When \f[B]SecureBootKeySource=\f[R] is specified, the input type depends
1814 on the source.
1815 .TP
1816 \f[B]SecureBootCertificate=\f[R], \f[B]\-\-secure\-boot\-certificate=\f[R]
1817 Path to the X.509 file containing the certificate for the signed UEFI
1818 kernel image, if \f[B]SecureBoot=\f[R] is used.
1819 .TP
1820 \f[B]SecureBootSignTool=\f[R], \f[B]\-\-secure\-boot\-sign\-tool=\f[R]
1821 Tool to use to sign secure boot PE binaries.
1822 Takes one of \f[B]systemd\-sbsign\f[R], \f[B]sbsign\f[R] or
1823 \f[B]auto\f[R].
1824 Defaults to \f[B]auto\f[R].
1825 If set to \f[B]auto\f[R], either \f[B]systemd\-sbsign\f[R] or
1826 \f[B]sbsign\f[R] are used if available, with \f[B]systemd\-sbsign\f[R]
1827 being preferred.
1828 .TP
1829 \f[B]Verity=\f[R], \f[B]\-\-verity=\f[R]
1830 Whether to enforce or disable verity for extension images.
1831 Takes one of \f[B]signed\f[R], \f[B]hash\f[R], \f[B]defer\f[R],
1832 \f[B]auto\f[R] or a boolean value.
1833 If set to \f[B]signed\f[R], a verity key and certificate must be present
1834 and the build will fail if we don\[cq]t detect any verity partitions in
1835 the disk image produced by \f[B]systemd\-repart\f[R].
1836 If disabled, verity partitions will be excluded from the extension
1837 images produced by \f[B]systemd\-repart\f[R].
1838 If set to \f[B]hash\f[R], \f[B]mkosi\f[R] configures
1839 \f[B]systemd\-repart\f[R] to create a verity hash partition, but no
1840 signature partition.
1841 If set to \f[B]defer\f[R], space for the verity sig partition will be
1842 allocated but it will not be populated yet.
1843 If set to \f[B]auto\f[R] and a verity key and certificate are present,
1844 \f[B]mkosi\f[R] will pass them to \f[B]systemd\-repart\f[R] and expects
1845 the generated disk image to contain verity partitions, but the build
1846 won\[cq]t fail if no verity partitions are found in the disk image
1847 produced by \f[B]systemd\-repart\f[R].
1848 .RS
1849 .PP
1850 Note that explicitly disabling verity signature and/or hash is not yet
1851 implemented for the \f[B]disk\f[R] output and only works for extension
1852 images at the moment.
1853 .RE
1854 .TP
1855 \f[B]VerityKey=\f[R], \f[B]\-\-verity\-key=\f[R]
1856 Path to the PEM file containing the secret key for signing the verity
1857 signature, if a verity signature partition is added with
1858 \f[B]systemd\-repart\f[R].
1859 When \f[B]VerityKeySource=\f[R] is specified, the input type depends on
1860 the source.
1861 .TP
1862 \f[B]VerityCertificate=\f[R], \f[B]\-\-verity\-certificate=\f[R]
1863 Path to the X.509 file containing the certificate for signing the verity
1864 signature, if a verity signature partition is added with
1865 \f[B]systemd\-repart\f[R].
1866 .TP
1867 \f[B]SignExpectedPcr=\f[R], \f[B]\-\-sign\-expected\-pcr=\f[R]
1868 Measure the components of the unified kernel image (UKI) using
1869 \f[B]systemd\-measure\f[R] and embed the PCR signature into the unified
1870 kernel image.
1871 This option takes a boolean value or the special value \f[B]auto\f[R],
1872 which is the default, which is equal to a true value if the
1873 \f[B]systemd\-measure\f[R] binary is in \f[B]PATH\f[R].
1874 Depends on \f[B]SecureBoot=\f[R] being enabled and key from
1875 \f[B]SecureBootKey=\f[R].
1876 .TP
1877 \f[B]SignExpectedPcrKey=\f[R], \f[B]\-\-sign\-expected\-pcr\-key=\f[R]
1878 Path to the PEM file containing the secret key for signing the expected
1879 PCR signatures.
1880 When \f[B]SignExpectedPcrKeySource=\f[R] is specified, the input type
1881 depends on the source.
1882 .TP
1883 \f[B]SignExpectedPcrCertificate=\f[R], \f[B]\-\-sign\-expected\-pcr\-certificate=\f[R]
1884 Path to the X.509 file containing the certificate for signing the
1885 expected PCR signatures.
1886 .TP
1887 \f[B]SecureBootKeySource=\f[R], \f[B]\-\-secure\-boot\-key\-source=\f[R], \f[B]VerityKeySource=\f[R], \f[B]\-\-verity\-key\-source=\f[R], \f[B]SignExpectedPcrKeySource=\f[R], \f[B]\-\-sign\-expected\-key\-source=\f[R]
1888 The source of the corresponding private key, to support OpenSSL engines
1889 and providers,
1890 e.g.\ \f[B]\-\-secure\-boot\-key\-source=engine:pkcs11\f[R] or
1891 \f[B]\-\-secure\-boot\-key\-source=provider:pkcs11\f[R].
1892 .TP
1893 \f[B]SecureBootCertificateSource=\f[R], \f[B]\-\-secure\-boot\-certificate\-source=\f[R], \f[B]VerityCertificateSource=\f[R], \f[B]\-\-verity\-certificate\-source=\f[R], \f[B]SignExpectedPcrCertificateSource=\f[R], \f[B]\-\-sign\-expected\-certificate\-source=\f[R]
1894 The source of the corresponding certificate, to support OpenSSL
1895 providers,
1896 e.g.\ \f[B]\-\-secure\-boot\-certificate\-source=provider:pkcs11\f[R].
1897 Note that engines are not supported.
1898 .TP
1899 \f[B]Passphrase=\f[R], \f[B]\-\-passphrase=\f[R]
1900 Specify the path to a file containing the passphrase to use for LUKS
1901 encryption.
1902 It should contain the passphrase literally, and not end in a newline
1903 character (i.e.\ in the same format as \f[B]cryptsetup\f[R] and
1904 \f[B]/etc/crypttab\f[R] expect the passphrase files).
1905 The file must have an access mode of 0600 or less.
1906 .RS
1907 .PP
1908 Note that this setting on its own does not enable any encryption.
1909 You also have to add one or more partition definition files to
1910 \f[B]mkosi.repart/\f[R] with \f[B]Encrypt=key\-file\f[R] to add
1911 encrypted partitions to the image.
1912 .RE
1913 .TP
1914 \f[B]Checksum=\f[R], \f[B]\-\-checksum=\f[R]
1915 Generate a \f[B]<output>.SHA256SUMS\f[R] file of all generated artifacts
1916 after the build is complete.
1917 .TP
1918 \f[B]Sign=\f[R], \f[B]\-\-sign=\f[R]
1919 Sign the generated \f[B]SHA256SUMS\f[R] using \f[B]gpg\f[R] after
1920 completion.
1921 .TP
1922 \f[B]OpenPGPTool=\f[R], \f[B]\-\-openpgp\-tool=\f[R]
1923 OpenPGP implementation to use for signing.
1924 \f[B]gpg\f[R] is the default.
1925 Selecting a value different than the default will use the given
1926 Stateless OpenPGP (SOP) tool for signing the \f[B]SHA256SUMS\f[R] file.
1927 .RS
1928 .PP
1929 Exemplary choices are \f[B]sqop\f[R] and \f[B]rsop\f[R], but any
1930 implementation from https://www.openpgp.org/about/sop/ that can be
1931 installed locally will work.
1932 .RE
1933 .TP
1934 \f[B]Key=\f[R], \f[B]\-\-key=\f[R]
1935 Select the \f[B]gpg\f[R] key to use for signing \f[B]SHA256SUMS\f[R].
1936 This key must be already present in the \f[B]gpg\f[R] keyring.
1937 .SS [Build] Section
1938 .TP
1939 \f[B]ToolsTree=\f[R], \f[B]\-\-tools\-tree=\f[R]
1940 If specified, programs executed by \f[B]mkosi\f[R] to build and boot an
1941 image are looked up inside the given tree instead of in the host system.
1942 Use this option to make image builds more reproducible by always using
1943 the same versions of programs to build the final image instead of
1944 whatever version is installed on the host system.
1945 If this option is not used, but the \f[B]mkosi.tools/\f[R] directory is
1946 found in the local directory it is automatically used for this purpose
1947 with the root directory as target.
1948 .RS
1949 .PP
1950 The tools tree directory is kept between repeated image builds unless
1951 cleaned by calling \f[B]mkosi clean \-f\f[R].
1952 .PP
1953 Note that binaries found in any of the paths configured with
1954 \f[B]ExtraSearchPaths=\f[R] will be executed with \f[B]/usr/\f[R] from
1955 the tools tree instead of from the host.
1956 If the host distribution or release does not match the tools tree
1957 distribution or release respectively, this might result in failures when
1958 trying to execute binaries from any of the extra search paths.
1959 .PP
1960 If set to \f[B]yes\f[R], \f[B]mkosi\f[R] will automatically add an extra
1961 tools tree image and use it as the tools tree.
1962 This image can be further configured using the settings below or with
1963 \f[B]mkosi.tools.conf\f[R] which can either be a file or directory
1964 containing extra configuration for the default tools tree.
1965 .PP
1966 See the \f[B]TOOLS TREE\f[R] section for further details.
1967 .RE
1968 .TP
1969 \f[B]ToolsTreeDistribution=\f[R], \f[B]\-\-tools\-tree\-distribution=\f[R]
1970 Set the distribution to use for the default tools tree.
1971 Defaults to the host distribution except for Ubuntu, which defaults to
1972 Debian, and RHEL, CentOS, Alma and Rocky, which default to Fedora, or
1973 \f[B]custom\f[R] if the distribution of the host is not a supported
1974 distribution.
1975 .TP
1976 \f[B]ToolsTreeRelease=\f[R], \f[B]\-\-tools\-tree\-release=\f[R]
1977 Set the distribution release to use for the default tools tree.
1978 By default, the hardcoded default release in \f[B]mkosi\f[R] for the
1979 distribution is used.
1980 .TP
1981 \f[B]ToolsTreeProfiles=\f[R], \f[B]\-\-tools\-tree\-profile=\f[R]
1982 Set the profiles to enable for the default tools tree.
1983 Takes a comma\-delimited list consisting of \f[B]devel\f[R],
1984 \f[B]misc\f[R], \f[B]package\-manager\f[R] and \f[B]runtime\f[R].
1985 By default, all profiles except \f[B]devel\f[R] are enabled.
1986 .RS
1987 .PP
1988 The \f[B]devel\f[R] profile contains tools required to build (C/C++)
1989 projects.
1990 The \f[B]misc\f[R] profile contains various useful tools that are handy
1991 to have available in scripts.
1992 The package manager profile contains package managers and related tools
1993 other than those native to the tools tree distribution.
1994 The \f[B]runtime\f[R] profile contains the tools required to boot images
1995 in a systemd\-nspawn container or in a virtual machine.
1996 .RE
1997 .TP
1998 \f[B]ToolsTreeMirror=\f[R], \f[B]\-\-tools\-tree\-mirror=\f[R]
1999 Set the mirror to use for the default tools tree.
2000 By default, the default mirror for the tools tree distribution is used.
2001 .TP
2002 \f[B]ToolsTreeRepositories=\f[R], \f[B]\-\-tools\-tree\-repository=\f[R]
2003 Same as \f[B]Repositories=\f[R] but for the default tools tree.
2004 .TP
2005 \f[B]ToolsTreeSandboxTrees=\f[R], \f[B]\-\-tools\-tree\-sandbox\-tree=\f[R]
2006 Same as \f[B]SandboxTrees=\f[R] but for the default tools tree.
2007 .TP
2008 \f[B]ToolsTreePackages=\f[R], \f[B]\-\-tools\-tree\-package=\f[R]
2009 Extra packages to install into the default tools tree.
2010 Takes a comma separated list of package specifications.
2011 This option may be used multiple times in which case the specified
2012 package lists are combined.
2013 .TP
2014 \f[B]ToolsTreePackageDirectories=\f[R], \f[B]\-\-tools\-tree\-package\-directory=\f[R]
2015 Same as \f[B]PackageDirectories=\f[R], but for the default tools tree.
2016 .TP
2017 \f[B]ToolsTreeCertificates=\f[R], \f[B]\-\-tools\-tree\-certificates=\f[R]
2018 Specify whether to use certificates and keys from the tools tree.
2019 Enabled by default.
2020 If enabled, \f[B]/etc/pki/ca\-trust\f[R], \f[B]/etc/pki/tls\f[R],
2021 \f[B]/etc/ssl\f[R], \f[B]/etc/ca\-certificates\f[R], and
2022 \f[B]/var/lib/ca\-certificates\f[R] from the tools tree are used.
2023 Otherwise, these directories are picked up from the host.
2024 .TP
2025 \f[B]ExtraSearchPaths=\f[R], \f[B]\-\-extra\-search\-path=\f[R]
2026 List of colon\-separated paths to look for tools in, before using the
2027 regular \f[B]$PATH\f[R] search path.
2028 .TP
2029 \f[B]Incremental=\f[R], \f[B]\-\-incremental=\f[R], \f[B]\-i\f[R]
2030 Takes either \f[B]strict\f[R] or a boolean value as its argument.
2031 Enables incremental build mode.
2032 In this mode, a copy of the OS image is created immediately after all OS
2033 packages are installed and the prepare scripts have executed but before
2034 the \f[B]mkosi.build\f[R] scripts are invoked (or anything that happens
2035 after it).
2036 On subsequent invocations of \f[B]mkosi\f[R] with the \f[B]\-i\f[R]
2037 switch this cached image may be used to skip the OS package
2038 installation, thus drastically speeding up repetitive build times.
2039 Note that while there is some rudimentary cache invalidation, it is
2040 definitely not perfect.
2041 In order to force a rebuild of the cached image, combine \f[B]\-i\f[R]
2042 with \f[B]\-ff\f[R] to ensure the cached image is first removed and then
2043 re\-created.
2044 .RS
2045 .PP
2046 If set to \f[B]strict\f[R], the build fails if previously built cached
2047 image does not exist.
2048 .RE
2049 .TP
2050 \f[B]CacheOnly=\f[R], \f[B]\-\-cache\-only=\f[R]
2051 Takes one of \f[B]auto\f[R], \f[B]metadata\f[R], \f[B]always\f[R] or
2052 \f[B]never\f[R].
2053 Defaults to \f[B]auto\f[R].
2054 If \f[B]always\f[R], the package manager is instructed not to contact
2055 the network.
2056 This provides a minimal level of reproducibility, as long as the package
2057 cache is already fully populated.
2058 If set to \f[B]metadata\f[R], the package manager can still download
2059 packages, but we won\[cq]t sync the repository metadata.
2060 If set to \f[B]auto\f[R], the repository metadata is synced unless we
2061 have a cached image (see \f[B]Incremental=\f[R]) and packages can be
2062 downloaded during the build.
2063 If set to \f[B]never\f[R], repository metadata is always synced and
2064 packages can be downloaded during the build.
2065 .TP
2066 \f[B]SandboxTrees=\f[R], \f[B]\-\-sandbox\-tree=\f[R]
2067 Takes a comma\-separated list of colon\-separated path pairs.
2068 The first path of each pair refers to a directory to copy into the mkosi
2069 sandbox before executing a tool.
2070 The second path of each pair refers to the target directory inside the
2071 sandbox.
2072 If the second path is not provided, the directory is copied on top of
2073 the root directory of the sandbox.
2074 The second path is always interpreted as an absolute path.
2075 If the \f[B]mkosi.sandbox/\f[R] directory is found in the local
2076 directory it is used for this purpose with the root directory as target
2077 (also see the \f[B]FILES\f[R] section below).
2078 .RS
2079 .PP
2080 \f[B]mkosi\f[R] will look for the package manager configuration and
2081 related files in the configured sandbox trees.
2082 Unless specified otherwise, it will use the configuration files from
2083 their canonical locations in \f[B]/usr\f[R] or \f[B]/etc\f[R] in the
2084 sandbox trees.
2085 For example, it will look for \f[B]/etc/dnf/dnf.conf\f[R] in the sandbox
2086 trees if \f[B]dnf\f[R] is used to install packages.
2087 .RE
2088 .TP
2089 \f[B]WorkspaceDirectory=\f[R], \f[B]\-\-workspace\-directory=\f[R]
2090 Path to a directory where to store data required temporarily while
2091 building the image.
2092 This directory should have enough space to store the full OS image,
2093 though in most modes the actually used disk space is smaller.
2094 If not specified, a subdirectory of \f[B]$XDG_CACHE_HOME\f[R] (if set),
2095 \f[B]$CACHE_DIRECTORY\f[R] (if set), \f[B]$HOME/.cache\f[R] (if set) or
2096 \f[B]/var/tmp\f[R] is used.
2097 .RS
2098 .PP
2099 The data in this directory is removed automatically after each build.
2100 It\[cq]s safe to manually remove the contents of this directory should
2101 an \f[B]mkosi\f[R] invocation be aborted abnormally (for example, due to
2102 reboot/power failure).
2103 .RE
2104 .TP
2105 \f[B]CacheDirectory=\f[R], \f[B]\-\-cache\-directory=\f[R]
2106 Takes a path to a directory to use as the incremental cache directory
2107 for the incremental images produced when the \f[B]Incremental=\f[R]
2108 option is enabled.
2109 If this option is not used, but a \f[B]mkosi.cache/\f[R] directory is
2110 found in the local directory it is automatically used for this purpose.
2111 .TP
2112 \f[B]CacheKey=\f[R], \f[B]\-\-cache\-key=\f[R]
2113 Specifies the subdirectory within the cache directory where to store the
2114 cached image.
2115 This may include both the regular specifiers (see \f[B]Specifiers\f[R])
2116 and special delayed specifiers, that are expanded after config parsing
2117 has finished, instead of during config parsing, which are described
2118 below.
2119 The default format for this parameter is
2120 \f[B]&d\[ti]&r\[ti]&a\[ti]&I\f[R].
2121 .RS
2122 .PP
2123 The following specifiers may be used:
2124 .PP
2125 .TS
2126 tab(@);
2127 l l.
2128 T{
2129 Specifier
2130 T}@T{
2131 Value
2132 T}
2133 _
2134 T{
2135 \f[B]&&\f[R]
2136 T}@T{
2137 \f[B]&\f[R] character
2138 T}
2139 T{
2140 \f[B]&d\f[R]
2141 T}@T{
2142 \f[B]Distribution=\f[R]
2143 T}
2144 T{
2145 \f[B]&r\f[R]
2146 T}@T{
2147 \f[B]Release=\f[R]
2148 T}
2149 T{
2150 \f[B]&a\f[R]
2151 T}@T{
2152 \f[B]Architecture=\f[R]
2153 T}
2154 T{
2155 \f[B]&i\f[R]
2156 T}@T{
2157 \f[B]ImageId=\f[R]
2158 T}
2159 T{
2160 \f[B]&v\f[R]
2161 T}@T{
2162 \f[B]ImageVersion=\f[R]
2163 T}
2164 T{
2165 \f[B]&I\f[R]
2166 T}@T{
2167 Subimage name within mkosi.images/ or \f[B]main\f[R]
2168 T}
2169 .TE
2170 .PP
2171 Note that all images within a build must have a unique cache key.
2172 .RE
2173 .TP
2174 \f[B]PackageCacheDirectory=\f[R], \f[B]\-\-package\-cache\-dir=\f[R]
2175 Takes a path to a directory to use as the package cache directory for
2176 the distribution package manager used.
2177 If unset, but a \f[B]mkosi.pkgcache/\f[R] directory is found in the
2178 local directory it is automatically used for this purpose, otherwise a
2179 suitable directory in the user\[cq]s home directory or system is used.
2180 .TP
2181 \f[B]BuildDirectory=\f[R], \f[B]\-\-build\-directory=\f[R]
2182 Takes a path to a directory to use as the build directory for build
2183 systems that support out\-of\-tree builds (such as Meson).
2184 The directory used this way is shared between repeated builds, and
2185 allows the build system to reuse artifacts (such as object files,
2186 executable, \&...)
2187 generated on previous invocations.
2188 The build scripts can find the path to this directory in the
2189 \f[B]$BUILDDIR\f[R] environment variable.
2190 This directory is mounted into the image\[cq]s root directory when
2191 \f[B]mkosi\-chroot\f[R] is invoked during execution of the build
2192 scripts.
2193 If this option is not specified, but a directory
2194 \f[B]mkosi.builddir/\f[R] exists in the local directory it is
2195 automatically used for this purpose (also see the \f[B]FILES\f[R]
2196 section below).
2197 .TP
2198 \f[B]BuildKey=\f[R], \f[B]\-\-build\-key=\f[R]
2199 Specifies the subdirectory within the build directory where to store
2200 incremental build artifacts.
2201 This may include both the regular specifiers (see \f[B]Specifiers\f[R])
2202 and special delayed specifiers, that are expanded after config parsing
2203 has finished, instead of during config parsing, which are the same
2204 delayed specifiers that are supported by \f[B]CacheKey=\f[R].
2205 The default format for this parameter is \f[B]&d\[ti]&r\[ti]&a\f[R].
2206 .RS
2207 .PP
2208 To disable usage of a build subdirectory completely, assign a literal
2209 \f[B]\-\f[R] to this setting.
2210 .RE
2211 .TP
2212 \f[B]UseSubvolumes=\f[R], \f[B]\-\-use\-subvolumes=\f[R]
2213 Takes a boolean or \f[B]auto\f[R].
2214 Enables or disables use of btrfs subvolumes for directory tree outputs.
2215 If enabled, \f[B]mkosi\f[R] will create the root directory as a btrfs
2216 subvolume and use btrfs subvolume snapshots where possible to copy base
2217 or cached trees which is much faster than doing a recursive copy.
2218 If explicitly enabled and \f[B]btrfs\f[R] is not installed or subvolumes
2219 cannot be created, an error is raised.
2220 If \f[B]auto\f[R], missing \f[B]btrfs\f[R] or failures to create
2221 subvolumes are ignored.
2222 .TP
2223 \f[B]RepartOffline=\f[R], \f[B]\-\-repart\-offline=\f[R]
2224 Specifies whether to build disk images using loopback devices.
2225 Enabled by default.
2226 When enabled, \f[B]systemd\-repart\f[R] will not use loopback devices to
2227 build disk images.
2228 When disabled, \f[B]systemd\-repart\f[R] will always use loopback
2229 devices to build disk images.
2230 .RS
2231 .PP
2232 Note that when using \f[B]RepartOffline=no\f[R], \f[B]mkosi\f[R] cannot
2233 run unprivileged and the image build has to be done as the root user
2234 outside of any containers and with loopback devices available on the
2235 host system.
2236 .PP
2237 There are currently two known scenarios where \f[B]RepartOffline=no\f[R]
2238 has to be used.
2239 The first is when using \f[B]Subvolumes=\f[R] in a repart partition
2240 definition file, as subvolumes cannot be created without using loopback
2241 devices.
2242 The second is when creating a system with SELinux and an XFS root
2243 partition.
2244 Because \f[B]mkfs.xfs\f[R] does not support populating an XFS filesystem
2245 with extended attributes, loopback devices have to be used to ensure the
2246 SELinux extended attributes end up in the generated XFS filesystem.
2247 .RE
2248 .TP
2249 \f[B]History=\f[R], \f[B]\-\-history=\f[R]
2250 Takes a boolean.
2251 If enabled, \f[B]mkosi\f[R] will write the configuration provided via
2252 the CLI for the latest build to the \f[B].mkosi\-private\f[R]
2253 subdirectory in the directory from which it was invoked.
2254 These arguments are then reused as long as the image is not rebuilt to
2255 avoid having to specify them over and over again.
2256 .RS
2257 .PP
2258 To give an example of why this is useful, if you run \f[B]mkosi \-O
2259 my\-custom\-output\-dir \-f\f[R] followed by \f[B]mkosi vm\f[R],
2260 \f[B]mkosi\f[R] will fail saying the image hasn\[cq]t been built yet.
2261 If you run \f[B]mkosi \-O my\-custom\-output\-dir \-\-history=yes
2262 \-f\f[R] followed by \f[B]mkosi vm\f[R], it will boot the image built in
2263 the previous step as expected.
2264 .RE
2265 .TP
2266 \f[B]BuildSources=\f[R], \f[B]\-\-build\-sources=\f[R]
2267 Takes a comma\-separated list of colon\-separated path pairs.
2268 The first path of each pair refers to a directory to mount from the
2269 host.
2270 The second path of each pair refers to the directory where the source
2271 directory should be mounted when running scripts.
2272 Every target path is prefixed with \f[B]/work/src\f[R] and all build
2273 sources are sorted lexicographically by their target before mounting, so
2274 that top level paths are mounted first.
2275 If not configured explicitly, the current working directory is mounted
2276 to \f[B]/work/src\f[R].
2277 .TP
2278 \f[B]BuildSourcesEphemeral=\f[R], \f[B]\-\-build\-sources\-ephemeral=\f[R]
2279 Takes a boolean or the special value \f[B]buildcache\f[R].
2280 Disabled by default.
2281 Configures whether changes to source directories, the working directory
2282 and configured using \f[B]BuildSources=\f[R], are persisted.
2283 If enabled, all source directories will be reset to their original state
2284 every time after running all scripts of a specific type (except sync
2285 scripts).
2286 .RS
2287 .PP
2288 💥💣💥 If set to \f[B]buildcache\f[R] the overlay is not discarded when
2289 running build scripts, but saved to the build directory, configured via
2290 \f[B]BuildDirectory=\f[R], and will be reused on subsequent runs.
2291 The overlay is still discarded for all other scripts.
2292 This option can be used to implement more advanced caching of builds,
2293 but can lead to unexpected states of the source directory.
2294 When using this option, a build directory must be configured.
2295 💥💣💥
2296 .RE
2297 .TP
2298 \f[B]Environment=\f[R], \f[B]\-\-environment=\f[R]
2299 Adds variables to the environment that package managers and the
2300 prepare/build/postinstall/finalize scripts are executed with.
2301 Takes a space\-separated list of variable assignments or just variable
2302 names.
2303 In the latter case, the values of those variables will be passed through
2304 from the environment in which \f[B]mkosi\f[R] was invoked.
2305 This option may be specified more than once, in which case all listed
2306 variables will be set.
2307 If the same variable is set twice, the later setting overrides the
2308 earlier one.
2309 .TP
2310 \f[B]EnvironmentFiles=\f[R], \f[B]\-\-env\-file=\f[R]
2311 Takes a comma\-separated list of paths to files that contain environment
2312 variable definitions to be added to the scripting environment.
2313 Uses \f[B]mkosi.env\f[R] if it is found in the local directory.
2314 The variables are first read from \f[B]mkosi.env\f[R] if it exists, then
2315 from the given list of files and then from the \f[B]Environment=\f[R]
2316 settings.
2317 .TP
2318 \f[B]WithTests=\f[R], \f[B]\-\-with\-tests=\f[R], \f[B]\-T\f[R]
2319 If set to false (or when the command\-line option is used), the
2320 \f[B]$WITH_TESTS\f[R] environment variable is set to \f[B]0\f[R] when
2321 the \f[B]mkosi.build\f[R] scripts are invoked.
2322 This is supposed to be used by the build scripts to bypass any unit or
2323 integration tests that are normally run during the source build process.
2324 Note that this option has no effect unless the \f[B]mkosi.build\f[R]
2325 build scripts honor it.
2326 .TP
2327 \f[B]WithNetwork=\f[R], \f[B]\-\-with\-network=\f[R]
2328 When true, enables network connectivity while the build scripts
2329 \f[B]mkosi.build\f[R] are invoked.
2330 By default, the build scripts run with networking turned off.
2331 The \f[B]$WITH_NETWORK\f[R] environment variable is passed to the
2332 \f[B]mkosi.build\f[R] build scripts indicating whether the build is done
2333 with or without network.
2334 .TP
2335 \f[B]ProxyUrl=\f[R], \f[B]\-\-proxy\-url=\f[R]
2336 Configure a proxy to be used for all outgoing network connections.
2337 Various tools that \f[B]mkosi\f[R] invokes and for which the proxy can
2338 be configured are configured to use this proxy.
2339 \f[B]mkosi\f[R] also sets various well\-known environment variables to
2340 specify the proxy to use for any programs it invokes that may need
2341 internet access.
2342 .TP
2343 \f[B]ProxyExclude=\f[R], \f[B]\-\-proxy\-exclude=\f[R]
2344 Configure hostnames for which requests should not go through the proxy.
2345 Takes a comma\-separated list of hostnames.
2346 .TP
2347 \f[B]ProxyPeerCertificate=\f[R], \f[B]\-\-proxy\-peer\-certificate=\f[R]
2348 Configure a file containing certificates used to verify the proxy.
2349 Defaults to the system\-wide certificate store.
2350 .RS
2351 .PP
2352 Currently, setting a proxy peer certificate is only supported when
2353 \f[B]dnf\f[R] or \f[B]dnf5\f[R] is used to build the image.
2354 .RE
2355 .TP
2356 \f[B]ProxyClientCertificate=\f[R], \f[B]\-\-proxy\-client\-certificate=\f[R]
2357 Configure a file containing the certificate used to authenticate the
2358 client with the proxy.
2359 .RS
2360 .PP
2361 Currently, setting a proxy client certificate is only supported when
2362 \f[B]dnf\f[R] or \f[B]dnf5\f[R] is used to build the image.
2363 .RE
2364 .TP
2365 \f[B]ProxyClientKey=\f[R], \f[B]\-\-proxy\-client\-key=\f[R]
2366 Configure a file containing the private key used to authenticate the
2367 client with the proxy.
2368 Defaults to the proxy client certificate if one is provided.
2369 .RS
2370 .PP
2371 Currently, setting a proxy client key is only supported when
2372 \f[B]dnf\f[R] or \f[B]dnf5\f[R] is used to build the image.
2373 .RE
2374 .SS [Runtime] Section (previously known as the [Host] section)
2375 .TP
2376 \f[B]NSpawnSettings=\f[R], \f[B]\-\-settings=\f[R]
2377 Specifies a \f[B].nspawn\f[R] settings file for
2378 \f[B]systemd\-nspawn\f[R] to use in the \f[B]boot\f[R] and
2379 \f[B]shell\f[R] verbs, and to place next to the generated image file.
2380 This is useful to configure the \f[B]systemd\-nspawn\f[R] environment
2381 when the image is run.
2382 If this setting is not used but an \f[B]mkosi.nspawn\f[R] file found in
2383 the local directory it is automatically used for this purpose.
2384 .TP
2385 \f[B]VirtualMachineMonitor=\f[R], \f[B]\-\-vmm=\f[R]
2386 Configures the virtual machine monitor to use.
2387 Takes one of \f[B]qemu\f[R] or \f[B]vmspawn\f[R].
2388 Defaults to \f[B]qemu\f[R].
2389 .RS
2390 .PP
2391 When set to \f[B]qemu\f[R], the image is booted with \f[B]qemu\f[R].
2392 Most output formats can be booted in \f[B]qemu\f[R].
2393 Any arguments specified after the verb are appended to the
2394 \f[B]qemu\f[R] invocation and are interpreted as extra \f[B]qemu\f[R]
2395 command line arguments.
2396 .PP
2397 When set to \f[B]vmspawn\f[R], \f[B]systemd\-vmspawn\f[R] is used to
2398 boot up the image, \f[B]vmspawn\f[R] only supports disk and directory
2399 type images.
2400 Any arguments specified after the verb are appended to the
2401 \f[B]systemd\-vmspawn\f[R] invocation and are interpreted as extra
2402 vmspawn options and extra kernel command line arguments.
2403 .RE
2404 .TP
2405 \f[B]Console=\f[R], \f[B]\-\-console=\f[R]
2406 Configures how to set up the console of the VM.
2407 Takes one of \f[B]interactive\f[R], \f[B]read\-only\f[R],
2408 \f[B]native\f[R], or \f[B]gui\f[R].
2409 Defaults to \f[B]interactive\f[R].
2410 \f[B]interactive\f[R] provides an interactive terminal interface to the
2411 VM.
2412 \f[B]read\-only\f[R] is similar, but is strictly read\-only, i.e.\ does
2413 not accept any input from the user.
2414 \f[B]native\f[R] also provides a TTY\-based interface, but uses
2415 \f[B]qemu\f[R]\[cq]s native implementation (which means the
2416 \f[B]qemu\f[R] monitor is available).
2417 \f[B]gui\f[R] shows the \f[B]qemu\f[R] graphical UI.
2418 .TP
2419 \f[B]CPUs=\f[R], \f[B]\-\-cpus=\f[R]
2420 Configures the number of CPU cores to assign to the guest when booting a
2421 virtual machine.
2422 Defaults to \f[B]2\f[R].
2423 .RS
2424 .PP
2425 When set to \f[B]0\f[R], the number of CPUs available to the
2426 \f[B]mkosi\f[R] process will be used.
2427 .RE
2428 .TP
2429 \f[B]RAM=\f[R], \f[B]\-\-ram=\f[R]
2430 Configures the amount of RAM assigned to the guest when booting a
2431 virtual machine.
2432 Defaults to \f[B]2G\f[R].
2433 .TP
2434 \f[B]MaxMem=\f[R], \f[B]\-\-maxmem=\f[R]
2435 Configures the maximum amount of memory the guest may deploy in total
2436 (RAM + hotplug memory devices).
2437 Defaults to the amount of RAM configured.
2438 .TP
2439 \f[B]KVM=\f[R], \f[B]\-\-kvm=\f[R]
2440 Configures whether KVM acceleration should be used when booting a
2441 virtual machine.
2442 Takes a boolean value or \f[B]auto\f[R].
2443 Defaults to \f[B]auto\f[R].
2444 .TP
2445 \f[B]CXL=\f[R], \f[B]\-\-cxl=\f[R]
2446 Configures whether CXL devices are enabled for a given machine.
2447 Only valid if the architecture supports cxl.
2448 Takes a boolean value.
2449 Defaults to \f[B]false\f[R].
2450 .TP
2451 \f[B]VSock=\f[R], \f[B]\-\-vsock=\f[R]
2452 Configures whether to provision a vsock when booting a virtual machine.
2453 Takes a boolean value or \f[B]auto\f[R].
2454 Defaults to \f[B]auto\f[R].
2455 .TP
2456 \f[B]VSockCID=\f[R], \f[B]\-\-vsock\-cid=\f[R]
2457 Configures the vsock connection ID to use when booting a virtual
2458 machine.
2459 Takes a number in the interval \f[B][3, 0xFFFFFFFF)\f[R] or
2460 \f[B]hash\f[R] or \f[B]auto\f[R].
2461 Defaults to \f[B]auto\f[R].
2462 When set to \f[B]hash\f[R], the connection ID will be derived from the
2463 full path to the image.
2464 When set to \f[B]auto\f[R], \f[B]mkosi\f[R] will try to find a free
2465 connection ID automatically.
2466 Otherwise, the provided number will be used as is.
2467 .TP
2468 \f[B]TPM=\f[R], \f[B]\-\-tpm=\f[R]
2469 Configure whether to use a virtual TPM when booting a virtual machine.
2470 Takes a boolean value or \f[B]auto\f[R].
2471 Defaults to \f[B]auto\f[R].
2472 .TP
2473 \f[B]Removable=\f[R], \f[B]\-\-removable=\f[R]
2474 Configures whether to attach the image as a removable device when
2475 booting a virtual machine.
2476 Takes a boolean value.
2477 Defaults to \f[B]no\f[R].
2478 .TP
2479 \f[B]Firmware=\f[R], \f[B]\-\-firmware=\f[R]
2480 Configures the virtual machine firmware to use.
2481 Takes one of \f[B]uefi\f[R], \f[B]uefi\-secure\-boot\f[R],
2482 \f[B]bios\f[R], \f[B]linux\f[R], \f[B]linux\-noinitrd\f[R] or
2483 \f[B]auto\f[R].
2484 Defaults to \f[B]auto\f[R].
2485 When set to \f[B]uefi\f[R], the OVMF firmware without secure boot
2486 support is used.
2487 When set to \f[B]uefi\-secure\-boot\f[R], the OVMF firmware with secure
2488 boot support is used.
2489 When set to \f[B]bios\f[R], the default SeaBIOS firmware is used.
2490 When set to \f[B]linux\f[R], direct kernel boot is used.
2491 See the \f[B]Linux=\f[R] option for more details on which kernel image
2492 is used with direct kernel boot.
2493 \f[B]linux\-noinitrd\f[R] is identical to \f[B]linux\f[R] except that no
2494 initrd is used.
2495 When set to \f[B]auto\f[R], \f[B]uefi\-secure\-boot\f[R] is used if
2496 possible and \f[B]linux\f[R] otherwise.
2497 .TP
2498 \f[B]FirmwareVariables=\f[R], \f[B]\-\-firmware\-variables=\f[R]
2499 Configures the path to the virtual machine firmware variables file to
2500 use.
2501 Currently, this option is only taken into account when the
2502 \f[B]uefi\f[R] or \f[B]uefi\-secure\-boot\f[R] firmware is used.
2503 If not specified, \f[B]mkosi\f[R] will search for the default variables
2504 file and use that instead.
2505 .RS
2506 .PP
2507 When set to \f[B]microsoft\f[R], a firmware variables file with the
2508 Microsoft secure boot certificates already enrolled will be used.
2509 .PP
2510 When set to \f[B]microsoft\-mok\f[R], a firmware variables file with the
2511 Microsoft secure boot certificates already enrolled will be extended
2512 with a \f[B]MokList\f[R] variable containing the secure boot certificate
2513 from \f[B]SecureBootCertificate=\f[R].
2514 This is intended to be used together with shim binaries signed by the
2515 distribution and locally signed EFI binaries.
2516 .PP
2517 When set to \f[B]custom\f[R], the secure boot certificate from
2518 \f[B]SecureBootCertificate=\f[R] will be enrolled into the default
2519 firmware variables file.
2520 .PP
2521 \f[B]virt\-fw\-vars\f[R] from the \c
2522 .UR https://gitlab.com/kraxel/virt-firmware
2523 virt\-firmware
2524 .UE \c
2525 \ project can be used to customize OVMF variable files.
2526 .RE
2527 .TP
2528 \f[B]Linux=\f[R], \f[B]\-\-linux=\f[R]
2529 Set the kernel image to use for \f[B]qemu\f[R] direct kernel boot.
2530 If not specified, \f[B]mkosi\f[R] will use the kernel provided via the
2531 command line (\f[B]\-kernel\f[R] option) or the latest kernel that was
2532 installed into the image (or fail if no kernel was installed into the
2533 image).
2534 .RS
2535 .PP
2536 Note that when the \f[B]cpio\f[R] output format is used, direct kernel
2537 boot is used regardless of the configured firmware.
2538 Depending on the configured firmware, \f[B]qemu\f[R] might boot the
2539 kernel itself or using the configured firmware.
2540 .PP
2541 This setting may include both the regular specifiers (see
2542 \f[B]Specifiers\f[R]) and special delayed specifiers, that are expanded
2543 after config parsing has finished, instead of during config parsing,
2544 which are described below.
2545 .PP
2546 The following specifiers may be used:
2547 .PP
2548 .TS
2549 tab(@);
2550 l l.
2551 T{
2552 Specifier
2553 T}@T{
2554 Value
2555 T}
2556 _
2557 T{
2558 \f[B]&&\f[R]
2559 T}@T{
2560 \f[B]&\f[R] character
2561 T}
2562 T{
2563 \f[B]&b\f[R]
2564 T}@T{
2565 The final build directory (including subdirectory)
2566 T}
2567 .TE
2568 .RE
2569 .TP
2570 \f[B]Drives=\f[R], \f[B]\-\-drive=\f[R]
2571 Add a drive.
2572 Takes a colon\-delimited string of format
2573 \f[B]<id>:<size>[:<directory>[:<options>[:<file\-id>[:<flags>]]]]\f[R].
2574 \f[B]id\f[R] specifies the ID assigned to the drive.
2575 This can be used as the \f[B]drive=\f[R] property in various
2576 \f[B]qemu\f[R] devices.
2577 \f[B]size\f[R] specifies the size of the drive.
2578 This takes a size in bytes.
2579 Additionally, the suffixes \f[B]K\f[R], \f[B]M\f[R] and \f[B]G\f[R] can
2580 be used to specify a size in kilobytes, megabytes and gigabytes
2581 respectively.
2582 \f[B]directory\f[R] optionally specifies the directory in which to
2583 create the file backing the drive.
2584 If unset, the file will be created under \f[B]/var/tmp\f[R].
2585 \f[B]options\f[R] optionally specifies extra comma\-delimited properties
2586 which are passed verbatim to \f[B]qemu\f[R]\[cq]s \f[B]\-blockdev\f[R]
2587 option.
2588 \f[B]file\-id\f[R] specifies the ID of the file backing the drive.
2589 If unset, this defaults to the drive ID.
2590 Drives with the same file ID will share the backing file.
2591 The directory and size of the file will be determined from the first
2592 drive with a given file ID.
2593 \f[B]flags\f[R] takes a comma\-separated list of drive flags which
2594 currently only supports \f[B]persist\f[R].
2595 \f[B]persist\f[R] determines whether the drive will be persisted across
2596 \f[B]qemu\f[R] invocations.
2597 The files backing the drives will be created with the schema
2598 \f[B]/<directory>/mkosi\-drive\-<machine\-or\-image\-name>\-<file\-id>\f[R].
2599 You can skip values by setting them to the empty string, specifying
2600 e.g.\ \f[B]myfs:1G::::persist\f[R] will create a persistent drive under
2601 \f[B]/var/tmp/mkosi\-drive\-main\-myfs\f[R].
2602 .RS
2603 .PP
2604 \f[B]Example usage:\f[R]
2605 .IP
2606 .EX
2607 \f[B][Runtime]\f[R]
2608 Drives=btrfs:10G
2609 ext4:20G
2610 QemuArgs=\-device nvme,serial=btrfs,drive=btrfs
2611 \-device nvme,serial=ext4,drive=ext4
2612 .EE
2613 .RE
2614 .TP
2615 \f[B]QemuArgs=\f[R]
2616 Space\-delimited list of additional arguments to pass when invoking
2617 \f[B]qemu\f[R].
2618 .TP
2619 \f[B]Ephemeral=\f[R], \f[B]\-\-ephemeral=\f[R]
2620 When used with the \f[B]shell\f[R], \f[B]boot\f[R], or \f[B]vm\f[R]
2621 verbs, this option runs the specified verb on a temporary snapshot of
2622 the output image that is removed immediately when the container
2623 terminates.
2624 Taking the temporary snapshot is more efficient on file systems that
2625 support reflinks natively (\f[B]btrfs\f[R] or \f[B]xfs\f[R]) than on
2626 more traditional file systems that do not (ext4).
2627 .TP
2628 \f[B]Credentials=\f[R], \f[B]\-\-credential=\f[R]
2629 Set credentials to be passed to \f[B]systemd\-nspawn\f[R] or the virtual
2630 machine respectively when \f[B]mkosi shell/boot\f[R] or \f[B]mkosi
2631 vm\f[R] are used.
2632 This option takes a space separated list of values which can be either
2633 key=value pairs or paths.
2634 If a path is provided, if it is a file, the credential name will be the
2635 name of the file.
2636 If the file is executable, the credential value will be the output of
2637 executing the file.
2638 Otherwise, the credential value will be the contents of the file.
2639 If the path is a directory, the same logic applies to each file in the
2640 directory.
2641 .RS
2642 .PP
2643 Note that values will only be treated as paths if they do not contain
2644 the delimiter (\f[B]=\f[R]).
2645 .RE
2646 .TP
2647 \f[B]KernelCommandLineExtra=\f[R], \f[B]\-\-kernel\-command\-line\-extra=\f[R]
2648 Set extra kernel command line entries that are appended to the kernel
2649 command line at runtime when booting the image.
2650 When booting in a container, these are passed as extra arguments to
2651 systemd.
2652 When booting in a VM, these are appended to the kernel command line via
2653 the SMBIOS io.systemd.stub.kernel\-cmdline\-extra OEM string.
2654 This will only be picked up by \f[B]systemd\-boot\f[R] and
2655 \f[B]systemd\-stub\f[R] versions newer than or equal to v254.
2656 .TP
2657 \f[B]RuntimeTrees=\f[R], \f[B]\-\-runtime\-tree=\f[R]
2658 Takes a colon\-separated pair of paths.
2659 The first path refers to a directory to mount into any machine
2660 (container or VM) started by mkosi.
2661 The second path refers to the target directory inside the machine.
2662 If the second path is not provided, the directory is mounted at
2663 \f[B]/root/src\f[R] in the machine.
2664 If the second path is relative, it is interpreted relative to
2665 \f[B]/root/src\f[R] in the machine.
2666 .RS
2667 .PP
2668 For each mounted directory, the uid and gid of the user running mkosi
2669 are mapped to the root user in the machine.
2670 This means that all the files and directories will appear as if
2671 they\[cq]re owned by root in the machine, and all new files and
2672 directories created by root in the machine in these directories will be
2673 owned by the user running mkosi on the host.
2674 .PP
2675 Note that when using \f[B]mkosi vm\f[R] with this feature systemd v254
2676 or newer has to be installed in the image.
2677 .RE
2678 .TP
2679 \f[B]RuntimeSize=\f[R], \f[B]\-\-runtime\-size=\f[R]
2680 If specified, disk images are grown to the specified size when
2681 they\[cq]re booted with \f[B]mkosi boot\f[R] or \f[B]mkosi vm\f[R].
2682 Takes a size in bytes.
2683 Additionally, the suffixes \f[B]K\f[R], \f[B]M\f[R] and \f[B]G\f[R] can
2684 be used to specify a size in kilobytes, megabytes and gigabytes
2685 respectively.
2686 .TP
2687 \f[B]RuntimeNetwork=\f[R], \f[B]\-\-runtime\-network=\f[R]
2688 Takes one of \f[B]user\f[R], \f[B]interface\f[R] or \f[B]none\f[R].
2689 Defaults to \f[B]user\f[R].
2690 Specifies the networking to set up when booting the image.
2691 \f[B]user\f[R] sets up usermode networking.
2692 \f[B]interface\f[R] sets up a virtual network connection between the
2693 host and the image.
2694 This translates to a veth interface for \f[B]mkosi shell\f[R] and
2695 \f[B]mkosi boot\f[R] and a tap interface for \f[B]mkosi vm\f[R] and
2696 \f[B]mkosi vmspawn\f[R].
2697 .RS
2698 .PP
2699 Note that when using \f[B]interface\f[R], \f[B]mkosi\f[R] does not
2700 automatically configure the host interface.
2701 It is expected that a recent version of \f[B]systemd\-networkd\f[R] is
2702 running on the host which will automatically configure the host
2703 interface of the link.
2704 .RE
2705 .TP
2706 \f[B]RuntimeBuildSources=\f[R], \f[B]\-\-runtime\-build\-sources=\f[R]
2707 Mount the build sources configured with \f[B]BuildSources=\f[R] and the
2708 build directory (if one is configured) to the same locations in
2709 \f[B]/work\f[R] that they were mounted to when running the build script
2710 when using \f[B]mkosi boot\f[R] or \f[B]mkosi vm\f[R].
2711 .TP
2712 \f[B]BindUser=\f[R], \f[B]\-\-bind\-user=\f[R]
2713 Bind the home directory of the current user into the container/vm.
2714 Takes a boolean.
2715 Disabled by default.
2716 .TP
2717 \f[B]UnitProperties=\f[R], \f[B]\-\-unit\-property=\f[R]
2718 Configure systemd unit properties to add to the systemd scopes allocated
2719 when using \f[B]mkosi boot\f[R] or \f[B]mkosi vm\f[R].
2720 These are passed directly to the \f[B]\-\-property=\f[R] options of
2721 \f[B]systemd\-nspawn\f[R] and \f[B]systemd\-run\f[R] respectively.
2722 .TP
2723 \f[B]SshKey=\f[R], \f[B]\-\-ssh\-key=\f[R]
2724 Path to the X.509 private key in PEM format to use to connect to a
2725 virtual machine started with \f[B]mkosi vm\f[R] and built with the
2726 \f[B]Ssh=\f[R] option enabled (or with \f[B]systemd\-ssh\-generator\f[R]
2727 installed) via the \f[B]mkosi ssh\f[R] command.
2728 If not configured and \f[B]mkosi.key\f[R] exists in the working
2729 directory, it will automatically be used for this purpose.
2730 Run \f[B]mkosi genkey\f[R] to automatically generate a key in
2731 \f[B]mkosi.key\f[R].
2732 .TP
2733 \f[B]SshCertificate=\f[R], \f[B]\-\-ssh\-certificate=\f[R]
2734 Path to the X.509 certificate in PEM format to provision as the SSH
2735 public key in virtual machines started with \f[B]mkosi vm\f[R].
2736 If not configured and \f[B]mkosi.crt\f[R] exists in the working
2737 directory, it will automatically be used for this purpose.
2738 Run \f[B]mkosi genkey\f[R] to automatically generate a certificate in
2739 \f[B]mkosi.crt\f[R].
2740 .TP
2741 \f[B]Machine=\f[R], \f[B]\-\-machine=\f[R]
2742 Specify the machine name to use when booting the image.
2743 Can also be used to refer to a specific image when SSH\-ing into an
2744 image (e.g.
2745 \f[B]mkosi \-\-image=myimage ssh\f[R]).
2746 .RS
2747 .PP
2748 Note that \f[B]Ephemeral=\f[R] has to be enabled to start multiple
2749 instances of the same image.
2750 .RE
2751 .TP
2752 \f[B]Register=\f[R], \f[B]\-\-register=\f[R]
2753 Takes a boolean value or \f[B]auto\f[R].
2754 Specifies whether to register the vm/container with systemd\-machined.
2755 If enabled, mkosi will fail if it can\[cq]t register the vm/container
2756 with systemd\-machined.
2757 If disabled, mkosi will not register the vm/container with
2758 systemd\-machined.
2759 If \f[B]auto\f[R], mkosi will register the vm/container with
2760 systemd\-machined if it is available.
2761 Defaults to \f[B]auto\f[R].
2762 .TP
2763 \f[B]ForwardJournal=\f[R], \f[B]\-\-forward\-journal=\f[R]
2764 Specify the path to which journal logs from containers and virtual
2765 machines should be forwarded.
2766 If the path has the \f[B].journal\f[R] extension, it is interpreted as a
2767 file to which the journal should be written.
2768 Otherwise, the path is interpreted as a directory to which the journal
2769 should be written.
2770 .RS
2771 .PP
2772 Note that systemd v256 or newer is required in the virtual machine for
2773 log forwarding to work.
2774 .PP
2775 Note that if a path with the \f[B].journal\f[R] extension is given, the
2776 journal size is limited to \f[B]4G\f[R].
2777 Configure an output directory instead of file if your workload produces
2778 more than \f[B]4G\f[R] worth of journal data.
2779 .RE
2780 .TP
2781 \f[B]StorageTargetMode=\f[R], \f[B]\-\-storage\-target\-mode=\f[R]
2782 Specifies whether the \f[B]serve\f[R] verb should start
2783 \f[B]systemd\-storagetm\f[R] to serve disk images over NVME\-TCP.
2784 Takes a boolean value or \f[B]auto\f[R].
2785 If enabled, systemd\-storagetm is always started and mkosi will fail if
2786 it cannot start systemd\-storagetm.
2787 If disabled, systemd\-storagetm is never started.
2788 If \f[B]auto\f[R], systemd\-storagetm will be started if a disk image is
2789 being built, the systemd\-storagetm binary is found and \f[B]mkosi
2790 serve\f[R] is being invoked as the root user.
2791 .TP
2792 \f[B]SysupdateDirectory=\f[R], \f[B]\-\-sysupdate\-directory=\f[R]
2793 Path to a directory containing systemd\-sysupdate transfer definition
2794 files that are used by \f[B]mkosi sysupdate\f[R].
2795 If \f[B]mkosi.sysupdate/\f[R] exists in the local directory, it will be
2796 used for this purpose as well.
2797 .RS
2798 .PP
2799 Note that \f[B]mkosi sysupdate\f[R] invokes \f[B]systemd\-sysupdate\f[R]
2800 with \f[B]\-\-transfer\-source=\f[R] set to the \f[B]mkosi\f[R] output
2801 directory.
2802 To make use of this in a transfer definition file, set
2803 \f[B]PathRelativeTo=explicit\f[R] to have the \f[B]Path=\f[R] setting
2804 for the transfer source be interpreted relative to the \f[B]mkosi\f[R]
2805 output directory.
2806 Generally, configuring \f[B]PathRelativeTo=explicit\f[R] and
2807 \f[B]Path=/\f[R] for the transfer source is sufficient for the match
2808 pattern to be interpreted relative to the \f[B]mkosi\f[R] output
2809 directory.
2810 .RE
2811 .SS [Match] Section
2812 .TP
2813 \f[B]Profiles=\f[R]
2814 Matches against the configured profiles.
2815 .TP
2816 \f[B]Distribution=\f[R]
2817 Matches against the configured distribution.
2818 .TP
2819 \f[B]Release=\f[R]
2820 Matches against the configured distribution release.
2821 If this condition is used and no distribution has been explicitly
2822 configured yet, the host distribution and release are used.
2823 .TP
2824 \f[B]Architecture=\f[R]
2825 Matches against the configured architecture.
2826 If this condition is used and no architecture has been explicitly
2827 configured yet, the host architecture is used.
2828 \f[B]Architecture=uefi\f[R] can be used to match against any
2829 architecture that supports UEFI.
2830 .TP
2831 \f[B]Repositories=\f[R]
2832 Matches against repositories enabled with the \f[B]Repositories=\f[R]
2833 setting.
2834 Takes a single repository name.
2835 .TP
2836 \f[B]PathExists=\f[R]
2837 This condition is satisfied if the given path exists.
2838 Relative paths are interpreted relative to the parent directory of the
2839 config file that the condition is read from.
2840 .TP
2841 \f[B]ImageId=\f[R]
2842 Matches against the configured image ID, supporting globs.
2843 If this condition is used and no image ID has been explicitly configured
2844 yet, this condition fails.
2845 .TP
2846 \f[B]ImageVersion=\f[R]
2847 Matches against the configured image version.
2848 Image versions can be prepended by the operators \f[B]==\f[R],
2849 \f[B]!=\f[R], \f[B]>=\f[R], \f[B]<=\f[R], \f[B]<\f[R], \f[B]>\f[R] for
2850 rich version comparisons according to the UAPI group version format
2851 specification.
2852 If no operator is prepended, the equality operator is assumed by
2853 default.
2854 If this condition is used and no image version has been explicitly
2855 configured yet, this condition fails.
2856 .TP
2857 \f[B]Bootable=\f[R]
2858 Matches against the configured value for the \f[B]Bootable=\f[R]
2859 feature.
2860 Takes a boolean value or \f[B]auto\f[R].
2861 .TP
2862 \f[B]Format=\f[R]
2863 Matches against the configured value for the \f[B]Format=\f[R] option.
2864 Takes an output format (see the \f[B]Format=\f[R] option).
2865 .TP
2866 \f[B]SystemdVersion=\f[R]
2867 Matches against the systemd version on the host (as reported by
2868 \f[B]systemctl \-\-version\f[R]).
2869 Values can be prepended by the operators \f[B]==\f[R], \f[B]!=\f[R],
2870 \f[B]>=\f[R], \f[B]<=\f[R], \f[B]<\f[R], \f[B]>\f[R] for rich version
2871 comparisons according to the UAPI group version format specification.
2872 If no operator is prepended, the equality operator is assumed by
2873 default.
2874 .TP
2875 \f[B]BuildSources=\f[R]
2876 Takes a build source target path (see \f[B]BuildSources=\f[R]).
2877 This match is satisfied if any of the configured build sources uses this
2878 target path.
2879 For example, if we have a \f[B]mkosi.conf\f[R] file containing:
2880 .RS
2881 .IP
2882 .EX
2883 \f[B][Build]\f[R]
2884 BuildSources=../abc/qed:kernel
2885 .EE
2886 .PP
2887 and a drop\-in containing:
2888 .IP
2889 .EX
2890 \f[B][Match]\f[R]
2891 BuildSources=kernel
2892 .EE
2893 .PP
2894 The drop\-in will be included.
2895 .PP
2896 Any absolute paths passed to this setting are interpreted relative to
2897 the current working directory.
2898 .RE
2899 .TP
2900 \f[B]HostArchitecture=\f[R]
2901 Matches against the host\[cq]s native architecture.
2902 See the \f[B]Architecture=\f[R] setting for a list of possible values.
2903 .TP
2904 \f[B]ToolsTreeDistribution=\f[R]
2905 Matches against the configured tools tree distribution.
2906 .TP
2907 \f[B]ToolsTreeRelease=\f[R]
2908 Matches against the configured tools tree release.
2909 .TP
2910 \f[B]Environment=\f[R]
2911 Matches against a specific key/value pair configured with
2912 \f[B]Environment=\f[R].
2913 If no value is provided, check if the given key is in the environment
2914 regardless of which value it has.
2915 .TP
2916 \f[B]Image=\f[R]
2917 Match against the current (sub)image name.
2918 The name of a subimage is its name in \f[B]mkosi.images/\f[R] (without
2919 any \f[B].conf\f[R] suffix).
2920 The name of the top level image is \f[B]main\f[R].
2921 The main use case is to allow having a shared config that can be
2922 included by both the top level image and subimages by gating the
2923 universal settings behind a \f[B]Image=main\f[R] match.
2924 .PP
2925 This table shows which matchers support globs, rich comparisons and the
2926 default value that is matched against if no value has been configured at
2927 the time the config file is read:
2928 .PP
2929 .TS
2930 tab(@);
2931 lw(13.1n) lw(3.5n) lw(9.1n) lw(44.3n).
2932 T{
2933 Matcher
2934 T}@T{
2935 Globs
2936 T}@T{
2937 Rich Comparisons
2938 T}@T{
2939 Default
2940 T}
2941 _
2942 T{
2943 \f[B]Profiles=\f[R]
2944 T}@T{
2945 no
2946 T}@T{
2947 no
2948 T}@T{
2949 match fails
2950 T}
2951 T{
2952 \f[B]Distribution=\f[R]
2953 T}@T{
2954 no
2955 T}@T{
2956 no
2957 T}@T{
2958 match host distribution
2959 T}
2960 T{
2961 \f[B]Release=\f[R]
2962 T}@T{
2963 no
2964 T}@T{
2965 no
2966 T}@T{
2967 match host release
2968 T}
2969 T{
2970 \f[B]Architecture=\f[R]
2971 T}@T{
2972 no
2973 T}@T{
2974 no
2975 T}@T{
2976 match host architecture
2977 T}
2978 T{
2979 \f[B]PathExists=\f[R]
2980 T}@T{
2981 no
2982 T}@T{
2983 no
2984 T}@T{
2985 n/a
2986 T}
2987 T{
2988 \f[B]ImageId=\f[R]
2989 T}@T{
2990 yes
2991 T}@T{
2992 no
2993 T}@T{
2994 match fails
2995 T}
2996 T{
2997 \f[B]ImageVersion=\f[R]
2998 T}@T{
2999 no
3000 T}@T{
3001 yes
3002 T}@T{
3003 match fails
3004 T}
3005 T{
3006 \f[B]Bootable=\f[R]
3007 T}@T{
3008 no
3009 T}@T{
3010 no
3011 T}@T{
3012 match auto feature
3013 T}
3014 T{
3015 \f[B]Format=\f[R]
3016 T}@T{
3017 no
3018 T}@T{
3019 no
3020 T}@T{
3021 match default format
3022 T}
3023 T{
3024 \f[B]SystemdVersion=\f[R]
3025 T}@T{
3026 no
3027 T}@T{
3028 yes
3029 T}@T{
3030 n/a
3031 T}
3032 T{
3033 \f[B]BuildSources=\f[R]
3034 T}@T{
3035 no
3036 T}@T{
3037 no
3038 T}@T{
3039 match fails
3040 T}
3041 T{
3042 \f[B]HostArchitecture=\f[R]
3043 T}@T{
3044 no
3045 T}@T{
3046 no
3047 T}@T{
3048 n/a
3049 T}
3050 T{
3051 \f[B]ToolsTreeDistribution=\f[R]
3052 T}@T{
3053 no
3054 T}@T{
3055 no
3056 T}@T{
3057 match the fallback tools tree distribution (see
3058 \f[B]ToolsTreeDistribution=\f[R] in \f[B][Build]\f[R])
3059 T}
3060 T{
3061 \f[B]ToolsTreeRelease=\f[R]
3062 T}@T{
3063 no
3064 T}@T{
3065 no
3066 T}@T{
3067 match default tools tree release
3068 T}
3069 T{
3070 \f[B]Environment=\f[R]
3071 T}@T{
3072 no
3073 T}@T{
3074 no
3075 T}@T{
3076 n/a
3077 T}
3078 T{
3079 \f[B]Image=\f[R]
3080 T}@T{
3081 no
3082 T}@T{
3083 no
3084 T}@T{
3085 n/a
3086 T}
3087 .TE
3088 .SS [Include]
3089 .TP
3090 \f[B]Include=\f[R], \f[B]\-\-include=\f[R], \f[B]\-I\f[R]
3091 Include extra configuration from the given file or directory.
3092 The extra configuration is included immediately after parsing the
3093 setting, except when used on the command line, in which case the extra
3094 configuration is included after parsing all command line arguments.
3095 .RS
3096 .PP
3097 Note that each path containing extra configuration is only parsed once,
3098 even if included more than once with \f[B]Include=\f[R].
3099 .PP
3100 The builtin configs for the \f[B]mkosi\f[R] default initrd, default
3101 tools tree, default virtual machine image and default UKI addon can be
3102 included by including the literal value \f[B]mkosi\-initrd\f[R],
3103 \f[B]mkosi\-tools\f[R], \f[B]mkosi\-vm\f[R] or \f[B]mkosi\-addon\f[R]
3104 respectively.
3105 .PP
3106 Note: Include names starting with either of the literals
3107 \f[B]mkosi\-\f[R] or \f[B]contrib\-\f[R] are reserved for use by
3108 \f[B]mkosi\f[R] itself.
3109 .RE
3110 .SS [Config] Section
3111 .TP
3112 \f[B]Profiles=\f[R], \f[B]\-\-profile=\f[R]
3113 Select the given profiles.
3114 A profile is a configuration file or directory in the
3115 \f[B]mkosi.profiles/\f[R] directory.
3116 The configuration files and directories of each profile are included
3117 after parsing the \f[B]mkosi.conf.d/*.conf\f[R] drop in configuration.
3118 .TP
3119 \f[B]Dependencies=\f[R], \f[B]\-\-dependency=\f[R]
3120 The images that this image depends on specified as a comma\-separated
3121 list.
3122 All images configured in this option will be built before this image.
3123 .RS
3124 .PP
3125 When this setting is specified for the \[lq]main\[rq] image, it
3126 specifies which subimages should be built.
3127 See the \f[B]BUILDING MULTIPLE IMAGES\f[R] section for more information.
3128 .RE
3129 .TP
3130 \f[B]MinimumVersion=\f[R], \f[B]\-\-minimum\-version=\f[R]
3131 The minimum \f[B]mkosi\f[R] version required to build this
3132 configuration.
3133 If specified multiple times, the highest specified version is used.
3134 .RS
3135 .PP
3136 The minimum version can also be specified as a git commit hash when
3137 prefixed with \f[B]commit:\f[R], in which case mkosi must be executed
3138 from a git checkout and the specified git commit hash must be an
3139 ancestor of the currently checked out git commit in the repository that
3140 mkosi is being executed from.
3141 .RE
3142 .TP
3143 \f[B]ConfigureScripts=\f[R], \f[B]\-\-configure\-script=\f[R]
3144 Takes a comma\-separated list of paths to executables that are used as
3145 the configure scripts for this image.
3146 See the \f[B]SCRIPTS\f[R] section for more information.
3147 .TP
3148 \f[B]PassEnvironment=\f[R], \f[B]\-\-pass\-environment=\f[R]
3149 Takes a list of environment variable names separated by spaces.
3150 When building multiple images, pass the listed environment variables to
3151 each individual subimage as if they were \[lq]universal\[rq] settings.
3152 See the \f[B]BUILDING MULTIPLE IMAGES\f[R] section for more information.
3153 .SS [UKIProfile] Section
3154 The \f[B]UKIProfile\f[R] section can be used in UKI profile config files
3155 which are passed to the \f[B]UnifiedKernelImageProfiles=\f[R] setting.
3156 The following settings can be specified in the \f[B]UKIProfile\f[R]
3157 section:
3158 .TP
3159 \f[B]Profile=\f[R]
3160 The contents of the \f[B].profile\f[R] section of the UKI profile.
3161 Takes a list of key/value pairs separated by \f[B]=\f[R].
3162 The \f[B]ID=\f[R] key must be specified.
3163 See the UKI \c
3164 .UR https://uapi-group.org/specifications/specs/unified_kernel_image/#multi-profile-ukis
3165 specification
3166 .UE \c
3167 \ for a full list of possible keys.
3168 .TP
3169 \f[B]Cmdline=\f[R]
3170 Extra kernel command line options for the UKI profile.
3171 Takes a space delimited list of extra kernel command line arguments.
3172 Note that the final \f[B].cmdline\f[R] section will the combination of
3173 the base \f[B].cmdline\f[R] section and the extra kernel command line
3174 arguments specified with this setting.
3175 .TP
3176 \f[B]SignExpectedPcr=\f[R]
3177 Sign expected PCR measurements for this UKI profile.
3178 Takes a boolean.
3179 Enabled by default.
3180 .SS Specifiers
3181 The current value of various settings can be accessed when parsing
3182 configuration files by using specifiers.
3183 To write a literal \f[B]%\f[R] character in a configuration file without
3184 treating it as a specifier, use \f[B]%%\f[R].
3185 The following specifiers are understood:
3186 .PP
3187 .TS
3188 tab(@);
3189 l l.
3190 T{
3191 Setting
3192 T}@T{
3193 Specifier
3194 T}
3195 _
3196 T{
3197 \f[B]Distribution=\f[R]
3198 T}@T{
3199 \f[B]%d\f[R]
3200 T}
3201 T{
3202 \f[B]Release=\f[R]
3203 T}@T{
3204 \f[B]%r\f[R]
3205 T}
3206 T{
3207 \f[B]Architecture=\f[R]
3208 T}@T{
3209 \f[B]%a\f[R]
3210 T}
3211 T{
3212 \f[B]Format=\f[R]
3213 T}@T{
3214 \f[B]%t\f[R]
3215 T}
3216 T{
3217 \f[B]Output=\f[R]
3218 T}@T{
3219 \f[B]%o\f[R]
3220 T}
3221 T{
3222 \f[B]OutputDirectory=\f[R]
3223 T}@T{
3224 \f[B]%O\f[R]
3225 T}
3226 T{
3227 \f[B]ImageId=\f[R]
3228 T}@T{
3229 \f[B]%i\f[R]
3230 T}
3231 T{
3232 \f[B]ImageVersion=\f[R]
3233 T}@T{
3234 \f[B]%v\f[R]
3235 T}
3236 .TE
3237 .PP
3238 There are also specifiers that are independent of settings:
3239 .PP
3240 .TS
3241 tab(@);
3242 l l.
3243 T{
3244 Specifier
3245 T}@T{
3246 Value
3247 T}
3248 _
3249 T{
3250 \f[B]%C\f[R]
3251 T}@T{
3252 Parent directory of current config file
3253 T}
3254 T{
3255 \f[B]%P\f[R]
3256 T}@T{
3257 Current working directory
3258 T}
3259 T{
3260 \f[B]%D\f[R]
3261 T}@T{
3262 Directory that \f[B]mkosi\f[R] was invoked in
3263 T}
3264 T{
3265 \f[B]%I\f[R]
3266 T}@T{
3267 Name of the current subimage in \f[B]mkosi.images\f[R]
3268 T}
3269 .TE
3270 .PP
3271 Finally, there are specifiers that are derived from a setting:
3272 .PP
3273 .TS
3274 tab(@);
3275 l l.
3276 T{
3277 Specifier
3278 T}@T{
3279 Value
3280 T}
3281 _
3282 T{
3283 \f[B]%F\f[R]
3284 T}@T{
3285 The default filesystem of the configured distribution
3286 T}
3287 .TE
3288 .PP
3289 Note that the current working directory changes as \f[B]mkosi\f[R]
3290 parses its configuration.
3291 Specifically, each time \f[B]mkosi\f[R] parses a directory containing a
3292 \f[B]mkosi.conf\f[R] file, \f[B]mkosi\f[R] changes its working directory
3293 to that directory.
3294 .PP
3295 Note that the directory that \f[B]mkosi\f[R] was invoked in is
3296 influenced by the \f[B]\-\-directory=\f[R] command line argument.
3297 .PP
3298 The following table shows example values for the directory specifiers
3299 listed above:
3300 .PP
3301 .TS
3302 tab(@);
3303 lw(4.7n) lw(13.4n) lw(25.2n) lw(26.7n).
3304 T{
3305 T}@T{
3306 \f[B]$D/mkosi.conf\f[R]
3307 T}@T{
3308 \f[B]$D/mkosi.conf.d/abc/abc.conf\f[R]
3309 T}@T{
3310 \f[B]$D/mkosi.conf.d/abc/mkosi.conf\f[R]
3311 T}
3312 _
3313 T{
3314 \f[B]%C\f[R]
3315 T}@T{
3316 \f[B]$D\f[R]
3317 T}@T{
3318 \f[B]$D/mkosi.conf.d\f[R]
3319 T}@T{
3320 \f[B]$D/mkosi.conf.d/abc\f[R]
3321 T}
3322 T{
3323 \f[B]%P\f[R]
3324 T}@T{
3325 \f[B]$D\f[R]
3326 T}@T{
3327 \f[B]$D\f[R]
3328 T}@T{
3329 \f[B]$D/mkosi.conf.d/abc\f[R]
3330 T}
3331 T{
3332 \f[B]%D\f[R]
3333 T}@T{
3334 \f[B]$D\f[R]
3335 T}@T{
3336 \f[B]$D\f[R]
3337 T}@T{
3338 \f[B]$D\f[R]
3339 T}
3340 .TE
3341 .SS Supported distributions
3342 Images may be created containing installations of the following
3343 distributions:
3344 .IP \[bu] 2
3345 \f[I]Fedora Linux\f[R]
3346 .IP \[bu] 2
3347 \f[I]Debian\f[R]
3348 .IP \[bu] 2
3349 \f[I]Kali Linux\f[R]
3350 .IP \[bu] 2
3351 \f[I]Ubuntu\f[R]
3352 .IP \[bu] 2
3353 \f[I]Arch Linux\f[R]
3354 .IP \[bu] 2
3355 \f[I]openSUSE\f[R]
3356 .IP \[bu] 2
3357 \f[I]Mageia\f[R]
3358 .IP \[bu] 2
3359 \f[I]CentOS\f[R]
3360 .IP \[bu] 2
3361 \f[I]RHEL\f[R]
3362 .IP \[bu] 2
3363 \f[I]RHEL UBI\f[R]
3364 .IP \[bu] 2
3365 \f[I]OpenMandriva\f[R]
3366 .IP \[bu] 2
3367 \f[I]Rocky Linux\f[R]
3368 .IP \[bu] 2
3369 \f[I]Alma Linux\f[R]
3370 .IP \[bu] 2
3371 \f[I]Azure Linux\f[R]
3372 .IP \[bu] 2
3373 \f[I]postmarketOS\f[R]
3374 .IP \[bu] 2
3375 \f[I]None\f[R] (\f[B]Requires the user to provide a pre\-built
3376 rootfs\f[R])
3377 .PP
3378 In theory, any distribution may be used on the host for building images
3379 containing any other distribution, as long as the necessary tools are
3380 available.
3381 Specifically, any distribution that packages \f[B]apt\f[R] may be used
3382 to build \f[I]Debian\f[R], \f[I]Kali\f[R] or \f[I]Ubuntu\f[R] images.
3383 Any distribution that packages \f[B]dnf\f[R] may be used to build images
3384 for any of the RPM\-based distributions.
3385 Any distro that packages \f[B]pacman\f[R] may be used to build \f[I]Arch
3386 Linux\f[R] images.
3387 Any distribution that packages \f[B]zypper\f[R] may be used to build
3388 \f[I]openSUSE\f[R] images.
3389 Other distributions and build automation tools for embedded Linux
3390 systems such as Buildroot, OpenEmbedded and Yocto Project may be used by
3391 selecting the \f[B]custom\f[R] distribution, and populating the rootfs
3392 via a combination of base trees, skeleton trees, and prepare scripts.
3393 .PP
3394 Currently, \f[I]Fedora Linux\f[R] packages all relevant tools as of
3395 Fedora 28.
3396 .PP
3397 Note that when not using a custom mirror, \f[B]RHEL\f[R] images can only
3398 be built from a host system with a \f[B]RHEL\f[R] subscription
3399 (established using e.g.\ \f[B]subscription\-manager\f[R]).
3400 .SH EXECUTION FLOW
3401 Execution flow for \f[B]mkosi build\f[R].
3402 Default values/calls are shown in parentheses.
3403 When building with \f[B]\-\-incremental=yes\f[R] \f[B]mkosi\f[R] creates
3404 a cache of the distribution installation if not already existing and
3405 replaces the distribution installation in consecutive runs with data
3406 from the cached one.
3407 .IP "1." 3
3408 Parse CLI options
3409 .IP "2." 3
3410 Parse configuration files
3411 .IP "3." 3
3412 Run configure scripts (\f[B]mkosi.configure\f[R])
3413 .IP "4." 3
3414 If we\[cq]re not running as root, unshare the user namespace and map the
3415 subuid range configured in \f[B]/etc/subuid\f[R] and
3416 \f[B]/etc/subgid\f[R] into it.
3417 .IP "5." 3
3418 Unshare the mount namespace
3419 .IP "6." 3
3420 Remount the following directories read\-only if they exist:
3421 .RS 4
3422 .IP \[bu] 2
3423 \f[B]/usr\f[R]
3424 .IP \[bu] 2
3425 \f[B]/etc\f[R]
3426 .IP \[bu] 2
3427 \f[B]/opt\f[R]
3428 .IP \[bu] 2
3429 \f[B]/srv\f[R]
3430 .IP \[bu] 2
3431 \f[B]/boot\f[R]
3432 .IP \[bu] 2
3433 \f[B]/efi\f[R]
3434 .IP \[bu] 2
3435 \f[B]/media\f[R]
3436 .IP \[bu] 2
3437 \f[B]/mnt\f[R]
3438 .RE
3439 .PP
3440 Then, for each image, we execute the following steps:
3441 .IP " 1." 4
3442 Copy sandbox trees into the workspace
3443 .IP " 2." 4
3444 Sync the package manager repository metadata
3445 .IP " 3." 4
3446 Run sync scripts (\f[B]mkosi.sync\f[R])
3447 .IP " 4." 4
3448 Copy base trees (\f[B]\-\-base\-tree=\f[R]) into the image
3449 .IP " 5." 4
3450 Reuse a cached image if one is available
3451 .IP " 6." 4
3452 Copy a snapshot of the package manager repository metadata into the
3453 image
3454 .IP " 7." 4
3455 Copy skeleton trees (\f[B]mkosi.skeleton\f[R]) into image
3456 .IP " 8." 4
3457 Install distribution and packages into image
3458 .IP " 9." 4
3459 Run prepare scripts on image with the \f[B]final\f[R] argument
3460 (\f[B]mkosi.prepare\f[R])
3461 .IP "10." 4
3462 Install build packages in overlay if any build scripts are configured
3463 .IP "11." 4
3464 Run prepare scripts on overlay with the \f[B]build\f[R] argument if any
3465 build scripts are configured (\f[B]mkosi.prepare\f[R])
3466 .IP "12." 4
3467 Cache the image if configured (\f[B]\-\-incremental=yes\f[R])
3468 .IP "13." 4
3469 Run build scripts on image + overlay if any build scripts are configured
3470 (\f[B]mkosi.build\f[R])
3471 .IP "14." 4
3472 Finalize the build if the output format \f[B]none\f[R] is configured
3473 .IP "15." 4
3474 Copy the build scripts outputs into the image
3475 .IP "16." 4
3476 Copy the extra trees into the image (\f[B]mkosi.extra\f[R])
3477 .IP "17." 4
3478 Run post\-install scripts (\f[B]mkosi.postinst\f[R])
3479 .IP "18." 4
3480 Write config files required for \f[B]Ssh=\f[R], \f[B]Autologin=\f[R] and
3481 \f[B]MakeInitrd=\f[R]
3482 .IP "19." 4
3483 Install systemd\-boot and configure secure boot if configured
3484 (\f[B]\-\-secure\-boot=yes\f[R])
3485 .IP "20." 4
3486 Run \f[B]systemd\-sysusers\f[R]
3487 .IP "21." 4
3488 Run \f[B]systemd\-tmpfiles\f[R]
3489 .IP "22." 4
3490 Run \f[B]systemctl preset\-all\f[R]
3491 .IP "23." 4
3492 Run \f[B]depmod\f[R]
3493 .IP "24." 4
3494 Run \f[B]systemd\-firstboot\f[R]
3495 .IP "25." 4
3496 Run \f[B]systemd\-hwdb\f[R]
3497 .IP "26." 4
3498 Remove packages and files (\f[B]RemovePackages=\f[R],
3499 \f[B]RemoveFiles=\f[R])
3500 .IP "27." 4
3501 Run SELinux relabel is a SELinux policy is installed
3502 .IP "28." 4
3503 Run finalize scripts (\f[B]mkosi.finalize\f[R])
3504 .IP "29." 4
3505 Generate unified kernel image if configured to do so
3506 .IP "30." 4
3507 Generate final output format
3508 .IP "31." 4
3509 Run post\-output scripts (\f[B]mkosi.postoutput\f[R])
3510 .SH SCRIPTS
3511 To allow for image customization that cannot be implemented using
3512 \f[B]mkosi\f[R]\[cq]s builtin features, \f[B]mkosi\f[R] supports running
3513 scripts at various points during the image build process that can
3514 customize the image as needed.
3515 Scripts are executed on the host system as root (either real root or
3516 root within the user namespace that \f[B]mkosi\f[R] created when running
3517 unprivileged) with a customized environment to simplify modifying the
3518 image.
3519 For each script, the configured build sources (\f[B]BuildSources=\f[R])
3520 are mounted into the current working directory before running the script
3521 in the current working directory.
3522 \f[B]$SRCDIR\f[R] is set to point to the current working directory.
3523 The following scripts are supported:
3524 .IP \[bu] 2
3525 If \f[B]\f[R]mkosi.configure\f[B]\f[R] (\f[B]ConfigureScripts=\f[R])
3526 exists, it is executed before building the image.
3527 This script may be used to dynamically modify the configuration.
3528 It receives the configuration serialized as JSON on stdin and should
3529 output the modified configuration serialized as JSON on stdout.
3530 Note that this script only runs when building or booting the image
3531 (\f[B]build\f[R], \f[B]vm\f[R], \f[B]boot\f[R] and \f[B]shell\f[R]
3532 verbs).
3533 If a default tools tree is configured, it will be built before running
3534 the configure scripts and the configure scripts will run with the tools
3535 tree available.
3536 This also means that the modifications made by configure scripts will
3537 not be visible in the \f[B]summary\f[R] output.
3538 .IP \[bu] 2
3539 If \f[B]\f[R]mkosi.sync\f[B]\f[R] (\f[B]SyncScripts=\f[R]) exists, it is
3540 executed before the image is built.
3541 This script may be used to update various sources that are used to build
3542 the image.
3543 One use case is to run \f[B]git pull\f[R] on various source repositories
3544 before building the image.
3545 Specifically, the \f[B]BuildSourcesEphemeral=\f[R] setting does not
3546 apply to sync scripts, which means sync scripts can be used to update
3547 build sources even if \f[B]BuildSourcesEphemeral=\f[R] is enabled.
3548 .IP \[bu] 2
3549 If \f[B]\f[R]mkosi.prepare\f[B]\f[R] (\f[B]PrepareScripts=\f[R]) exists,
3550 it is first called with the \f[B]final\f[R] argument, right after the
3551 software packages are installed.
3552 It is called a second time with the \f[B]build\f[R] command line
3553 parameter, right after the build packages are installed and the build
3554 overlay mounted on top of the image\[cq]s root directory .
3555 This script has network access and may be used to install packages from
3556 other sources than the distro\[cq]s package manager
3557 (e.g.\ \f[B]pip\f[R], \f[B]npm\f[R], \&...), after all software packages
3558 are installed but before the image is cached (if incremental mode is
3559 enabled).
3560 In contrast to a general purpose installation, it is safe to install
3561 packages to the system (\f[B]pip install\f[R], \f[B]npm install
3562 \-g\f[R]) instead of in \f[B]$SRCDIR\f[R] itself because the build image
3563 is only used for a single project and can easily be thrown away and
3564 rebuilt so there\[cq]s no risk of conflicting dependencies and no risk
3565 of polluting the host system.
3566 .IP \[bu] 2
3567 If \f[B]\f[R]mkosi.build\f[B]\f[R] (\f[B]BuildScripts=\f[R]) exists, it
3568 is executed with the build overlay mounted on top of the image\[cq]s
3569 root directory.
3570 When running the build script, \f[B]$DESTDIR\f[R] points to a directory
3571 where the script should place any files generated it would like to end
3572 up in the image.
3573 Note that \f[B]make\f[R]\-, \f[B]automake\f[R]\-, and
3574 \f[B]meson\f[R]\-based build systems generally honor \f[B]$DESTDIR\f[R],
3575 thus making it very natural to build \f[I]source\f[R] trees from the
3576 build script.
3577 After running the build script, the contents of \f[B]$DESTDIR\f[R] are
3578 copied into the image.
3579 .IP \[bu] 2
3580 If \f[B]\f[R]mkosi.postinst\f[B]\f[R]
3581 (\f[B]PostInstallationScripts=\f[R]) exists, it is executed after the
3582 (optional) build tree and extra trees have been installed.
3583 This script may be used to alter the images without any restrictions,
3584 after all software packages and built sources have been installed.
3585 .IP \[bu] 2
3586 If \f[B]\f[R]mkosi.finalize\f[B]\f[R] (\f[B]FinalizeScripts=\f[R])
3587 exists, it is executed as the last step of preparing an image.
3588 .IP \[bu] 2
3589 If \f[B]\f[R]mkosi.postoutput\f[B]\f[R] (\f[B]PostOutputScripts=\f[R])
3590 exists, it is executed right after all the output files have been
3591 generated, before they are finally moved into the output directory.
3592 This can be used to generate additional or alternative outputs,
3593 e.g.\ \f[B]SHA256FILES\f[R] or SBOM manifests.
3594 .IP \[bu] 2
3595 If \f[B]\f[R]mkosi.clean\f[B]\f[R] (\f[B]CleanScripts=\f[R]) exists, it
3596 is executed right after the outputs of a previous build have been
3597 cleaned up.
3598 A clean script can clean up any outputs that \f[B]mkosi\f[R] does not
3599 know about (e.g.
3600 artifacts from \f[B]SplitArtifacts=partitions\f[R] or RPMs built in a
3601 build script).
3602 Note that this script does not use the tools tree even if one is
3603 configured.
3604 .IP \[bu] 2
3605 If \f[B]\f[R]mkosi.version\f[B]\f[R] exists and is executable, it is run
3606 during configuration parsing and populates \f[B]ImageVersion=\f[R] with
3607 the output on stdout.
3608 This can be used for external version tracking, e.g.\ with \f[B]git
3609 describe\f[R] or \f[B]date \[aq]+%Y\-%m\-%d\[aq]\f[R].
3610 Note that this script is executed on the host system without any
3611 sandboxing.
3612 .IP \[bu] 2
3613 If \f[B]\f[R]mkosi.rootpw\f[B]\f[R] exists and is executable, it is run
3614 during configuration parsing and populates \f[B]RootPassword=\f[R] with
3615 the output on stdout.
3616 This can be used to randomly generate a password and can be remembered
3617 by outputting it to stderr or by reading \f[B]$MKOSI_CONFIG\f[R] in
3618 another script (e.g.\ \f[B]mkosi.postoutput\f[R]).
3619 Note that this script is executed on the host system without any
3620 sandboxing.
3621 .PP
3622 If a script uses the \f[B].chroot\f[R] extension, \f[B]mkosi\f[R] will
3623 chroot into the image using \f[B]mkosi\-chroot\f[R] (see below) before
3624 executing the script.
3625 For example, if \f[B]mkosi.postinst.chroot\f[R] exists, \f[B]mkosi\f[R]
3626 will chroot into the image and execute it as the post\-installation
3627 script.
3628 .PP
3629 Instead of a single file script, \f[B]mkosi\f[R] will also read all
3630 files in lexicographical order from appropriately named \f[B].d\f[R]
3631 directories, e.g.\ all files in a \f[B]mkosi.build.d\f[R] would be used
3632 as build scripts.
3633 This is supported by
3634 .IP \[bu] 2
3635 \f[B]mkosi.sync.d\f[R],
3636 .IP \[bu] 2
3637 \f[B]mkosi.prepare.d\f[R],
3638 .IP \[bu] 2
3639 \f[B]mkosi.build.d\f[R],
3640 .IP \[bu] 2
3641 \f[B]mkosi.postinst.d\f[R],
3642 .IP \[bu] 2
3643 \f[B]mkosi.finalize.d\f[R],
3644 .IP \[bu] 2
3645 \f[B]mkosi.postoutput.d\f[R], and
3646 .IP \[bu] 2
3647 \f[B]mkosi.clean.d\f[R].
3648 .PP
3649 This can be combined with the \f[B].chroot\f[R] extension,
3650 e.g.\ \f[B]mkosi.build.d/01\-foo.sh\f[R] would be run without chrooting
3651 into the image and \f[B]mkosi.build.d/02\-bar.sh.chroot\f[R] would be
3652 run after chrooting into the image first.
3653 .PP
3654 Scripts executed by \f[B]mkosi\f[R] receive the following environment
3655 variables:
3656 .IP \[bu] 2
3657 \f[B]$ARCHITECTURE\f[R] contains the architecture from the
3658 \f[B]Architecture=\f[R] setting.
3659 If \f[B]Architecture=\f[R] is not set, it will contain the native
3660 architecture of the host machine.
3661 See the documentation of \f[B]Architecture=\f[R] for possible values for
3662 this variable.
3663 .IP \[bu] 2
3664 \f[B]$QEMU_ARCHITECTURE\f[R] contains the architecture from
3665 \f[B]$ARCHITECTURE\f[R] in the format used by \f[B]qemu\f[R].
3666 Useful for finding the qemu binary (
3667 \f[B]qemu\-system\-$QEMU_ARCHITECTURE\f[R]).
3668 .IP \[bu] 2
3669 \f[B]$EFI_ARCHITECTURE\f[R] contains the architecture from
3670 \f[B]$ARCHITECTURE\f[R] in the format used by \f[B]UEFI\f[R].
3671 It is unset on architectures that do not support \f[B]UEFI\f[R].
3672 .IP \[bu] 2
3673 \f[B]$DISTRIBUTION\f[R] contains the distribution from the
3674 \f[B]Distribution=\f[R] setting.
3675 .IP \[bu] 2
3676 \f[B]$RELEASE\f[R] contains the release from the \f[B]Release=\f[R]
3677 setting.
3678 .IP \[bu] 2
3679 \f[B]$DISTRIBUTION_ARCHITECTURE\f[R] contains the architecture from
3680 \f[B]$ARCHITECTURE\f[R] in the format used by the configured
3681 distribution.
3682 .IP \[bu] 2
3683 \f[B]$PROFILES\f[R] contains the profiles from the \f[B]Profiles=\f[R]
3684 setting as a comma\-delimited string.
3685 .IP \[bu] 2
3686 \f[B]$CACHED\f[R] is set to \f[B]1\f[R] if a cached image is available,
3687 \f[B]0\f[R] otherwise.
3688 .IP \[bu] 2
3689 \f[B]$CHROOT_SCRIPT\f[R] contains the path to the running script
3690 relative to the image root directory.
3691 The primary usecase for this variable is in combination with the
3692 \f[B]mkosi\-chroot\f[R] script.
3693 See the description of \f[B]mkosi\-chroot\f[R] below for more
3694 information.
3695 .IP \[bu] 2
3696 \f[B]$SRCDIR\f[R] contains the path to the directory \f[B]mkosi\f[R] was
3697 invoked from, with any configured build sources mounted on top.
3698 \f[B]$CHROOT_SRCDIR\f[R] contains the value that \f[B]$SRCDIR\f[R] will
3699 have after invoking \f[B]mkosi\-chroot\f[R].
3700 .IP \[bu] 2
3701 \f[B]$BUILDDIR\f[R] is only defined if \f[B]mkosi.builddir\f[R] exists
3702 and points to the build directory to use.
3703 This is useful for all build systems that support out\-of\-tree builds
3704 to reuse already built artifacts from previous runs.
3705 \f[B]$CHROOT_BUILDDIR\f[R] contains the value that \f[B]$BUILDDIR\f[R]
3706 will have after invoking \f[B]mkosi\-chroot\f[R].
3707 .IP \[bu] 2
3708 \f[B]$DESTDIR\f[R] is a directory into which any installed software
3709 generated by a build script may be placed.
3710 This variable is only set when executing a build script.
3711 \f[B]$CHROOT_DESTDIR\f[R] contains the value that \f[B]$DESTDIR\f[R]
3712 will have after invoking \f[B]mkosi\-chroot\f[R].
3713 .IP \[bu] 2
3714 \f[B]$OUTPUTDIR\f[R] points to the staging directory used to store build
3715 artifacts generated during the build.
3716 \f[B]$CHROOT_OUTPUTDIR\f[R] contains the value that \f[B]$OUTPUTDIR\f[R]
3717 will have after invoking \f[B]mkosi\-chroot\f[R].
3718 .IP \[bu] 2
3719 \f[B]$PACKAGEDIR\f[R] points to the directory containing the local
3720 package repository.
3721 Build scripts can add more packages to the local repository by writing
3722 the packages to \f[B]$PACKAGEDIR\f[R].
3723 .IP \[bu] 2
3724 \f[B]$ARTIFACTDIR\f[R] points to the directory that is used to pass
3725 around build artifacts generated during the build and make them
3726 available for use by mkosi.
3727 This is similar to \f[B]PACKAGEDIR\f[R], but is meant for artifacts that
3728 may not be packages understood by the package manager, e.g.\ initrds
3729 created by other initrd generators than mkosi.
3730 Build scripts can add more artifacts to the directory by placing them in
3731 \f[B]$ARTIFACTDIR\f[R].
3732 Files in this directory are only available for the current build and are
3733 not copied out like the contents of \f[B]$OUTPUTDIR\f[R].
3734 .RS 2
3735 .PP
3736 \f[B]mkosi\f[R] will also use certain subdirectories of an artifacts
3737 directory to automatically use their contents at certain steps.
3738 Currently the following two subdirectories in the artifact directory are
3739 used by mkosi:
3740 .IP \[bu] 2
3741 \f[B]io.mkosi.microcode\f[R]: All files in this directory are used as
3742 microcode files, i.e.\ they are prepended to the initrds in
3743 lexicographical order.
3744 .IP \[bu] 2
3745 \f[B]io.mkosi.initrd\f[R]: All files in this directory are used as
3746 initrds and joined in lexicographical order.
3747 .PP
3748 It is recommended, that users of \f[B]$ARTIFACTDIR\f[R] put things for
3749 their own use in a similar namespaced directory,
3750 e.g.\ \f[B]local.my.namespace\f[R].
3751 .RE
3752 .IP \[bu] 2
3753 \f[B]$BUILDROOT\f[R] is the root directory of the image being built,
3754 optionally with the build overlay mounted on top depending on the script
3755 that\[cq]s being executed.
3756 .IP \[bu] 2
3757 \f[B]$WITH_DOCS\f[R] is either \f[B]0\f[R] or \f[B]1\f[R] depending on
3758 whether a build without or with installed documentation was requested
3759 (\f[B]WithDocs=yes\f[R]).
3760 A build script should suppress installation of any package documentation
3761 to \f[B]$DESTDIR\f[R] in case \f[B]$WITH_DOCS\f[R] is set to
3762 \f[B]0\f[R].
3763 .IP \[bu] 2
3764 \f[B]$WITH_TESTS\f[R] is either \f[B]0\f[R] or \f[B]1\f[R] depending on
3765 whether a build without or with running the test suite was requested
3766 (\f[B]WithTests=no\f[R]).
3767 A build script should avoid running any unit or integration tests in
3768 case \f[B]$WITH_TESTS\f[R] is \f[B]0\f[R].
3769 .IP \[bu] 2
3770 \f[B]$WITH_NETWORK\f[R] is either \f[B]0\f[R] or \f[B]1\f[R] depending
3771 on whether a build without or with networking is being executed
3772 (\f[B]WithNetwork=no\f[R]).
3773 A build script should avoid any network communication in case
3774 \f[B]$WITH_NETWORK\f[R] is \f[B]0\f[R].
3775 .IP \[bu] 2
3776 \f[B]$SOURCE_DATE_EPOCH\f[R] is defined if requested
3777 (\f[B]SourceDateEpoch=TIMESTAMP\f[R],
3778 \f[B]Environment=SOURCE_DATE_EPOCH=TIMESTAMP\f[R] or the host
3779 environment variable \f[B]$SOURCE_DATE_EPOCH\f[R]).
3780 This is useful to make builds reproducible.
3781 See \c
3782 .UR https://reproducible-builds.org/specs/source-date-epoch/
3783 SOURCE_DATE_EPOCH
3784 .UE \c
3785 \ for more information.
3786 .IP \[bu] 2
3787 \f[B]$MKOSI_UID\f[R] and \f[B]$MKOSI_GID\f[R] respectively are the uid,
3788 gid of the user that invoked mkosi.
3789 .IP \[bu] 2
3790 \f[B]$MKOSI_CONFIG\f[R] is a file containing a json summary of the
3791 settings of the current image.
3792 This file can be parsed inside scripts to gain access to all settings
3793 for the current image.
3794 .IP \[bu] 2
3795 \f[B]$IMAGE_ID\f[R] contains the identifier from the \f[B]ImageId=\f[R]
3796 or \f[B]\-\-image\-id=\f[R] setting.
3797 .IP \[bu] 2
3798 \f[B]$IMAGE_VERSION\f[R] contains the version from the
3799 \f[B]ImageVersion=\f[R] or \f[B]\-\-image\-version=\f[R] setting.
3800 .IP \[bu] 2
3801 \f[B]$MKOSI_DEBUG\f[R] is either \f[B]0\f[R] or \f[B]1\f[R] depending on
3802 whether debugging output is enabled.
3803 .PP
3804 Consult this table for which script receives which environment
3805 variables:
3806 .PP
3807 .TS
3808 tab(@);
3809 lw(17.4n) cw(7.8n) cw(4.8n) cw(6.6n) cw(5.4n) cw(7.2n) cw(7.2n) cw(8.4n) cw(5.4n).
3810 T{
3811 Variable
3812 T}@T{
3813 \f[B]configure\f[R]
3814 T}@T{
3815 \f[B]sync\f[R]
3816 T}@T{
3817 \f[B]prepare\f[R]
3818 T}@T{
3819 \f[B]build\f[R]
3820 T}@T{
3821 \f[B]postinst\f[R]
3822 T}@T{
3823 \f[B]finalize\f[R]
3824 T}@T{
3825 \f[B]postoutput\f[R]
3826 T}@T{
3827 \f[B]clean\f[R]
3828 T}
3829 _
3830 T{
3831 \f[B]ARCHITECTURE\f[R]
3832 T}@T{
3833 ✓
3834 T}@T{
3835 ✓
3836 T}@T{
3837 ✓
3838 T}@T{
3839 ✓
3840 T}@T{
3841 ✓
3842 T}@T{
3843 ✓
3844 T}@T{
3845 ✓
3846 T}@T{
3847 ✓
3848 T}
3849 T{
3850 \f[B]ARTIFACTDIR\f[R]
3851 T}@T{
3852 T}@T{
3853 T}@T{
3854 ✓
3855 T}@T{
3856 ✓
3857 T}@T{
3858 ✓
3859 T}@T{
3860 ✓
3861 T}@T{
3862 T}@T{
3863 T}
3864 T{
3865 \f[B]BUILDDIR\f[R]
3866 T}@T{
3867 T}@T{
3868 T}@T{
3869 T}@T{
3870 ✓
3871 T}@T{
3872 ✓
3873 T}@T{
3874 ✓
3875 T}@T{
3876 T}@T{
3877 T}
3878 T{
3879 \f[B]BUILDROOT\f[R]
3880 T}@T{
3881 T}@T{
3882 T}@T{
3883 ✓
3884 T}@T{
3885 ✓
3886 T}@T{
3887 ✓
3888 T}@T{
3889 ✓
3890 T}@T{
3891 T}@T{
3892 T}
3893 T{
3894 \f[B]CACHED\f[R]
3895 T}@T{
3896 T}@T{
3897 ✓
3898 T}@T{
3899 T}@T{
3900 T}@T{
3901 T}@T{
3902 T}@T{
3903 T}@T{
3904 T}
3905 T{
3906 \f[B]CHROOT_BUILDDIR\f[R]
3907 T}@T{
3908 T}@T{
3909 T}@T{
3910 T}@T{
3911 ✓
3912 T}@T{
3913 T}@T{
3914 T}@T{
3915 T}@T{
3916 T}
3917 T{
3918 \f[B]CHROOT_DESTDIR\f[R]
3919 T}@T{
3920 T}@T{
3921 T}@T{
3922 T}@T{
3923 ✓
3924 T}@T{
3925 T}@T{
3926 T}@T{
3927 T}@T{
3928 T}
3929 T{
3930 \f[B]CHROOT_OUTPUTDIR\f[R]
3931 T}@T{
3932 T}@T{
3933 T}@T{
3934 T}@T{
3935 T}@T{
3936 ✓
3937 T}@T{
3938 ✓
3939 T}@T{
3940 T}@T{
3941 T}
3942 T{
3943 \f[B]CHROOT_SCRIPT\f[R]
3944 T}@T{
3945 T}@T{
3946 T}@T{
3947 ✓
3948 T}@T{
3949 ✓
3950 T}@T{
3951 ✓
3952 T}@T{
3953 ✓
3954 T}@T{
3955 T}@T{
3956 T}
3957 T{
3958 \f[B]CHROOT_SRCDIR\f[R]
3959 T}@T{
3960 T}@T{
3961 T}@T{
3962 ✓
3963 T}@T{
3964 ✓
3965 T}@T{
3966 ✓
3967 T}@T{
3968 ✓
3969 T}@T{
3970 T}@T{
3971 T}
3972 T{
3973 \f[B]MKOSI_DEBUG\f[R]
3974 T}@T{
3975 ✓
3976 T}@T{
3977 ✓
3978 T}@T{
3979 ✓
3980 T}@T{
3981 ✓
3982 T}@T{
3983 ✓
3984 T}@T{
3985 ✓
3986 T}@T{
3987 ✓
3988 T}@T{
3989 ✓
3990 T}
3991 T{
3992 \f[B]DESTDIR\f[R]
3993 T}@T{
3994 T}@T{
3995 T}@T{
3996 T}@T{
3997 ✓
3998 T}@T{
3999 T}@T{
4000 T}@T{
4001 T}@T{
4002 T}
4003 T{
4004 \f[B]DISTRIBUTION\f[R]
4005 T}@T{
4006 ✓
4007 T}@T{
4008 ✓
4009 T}@T{
4010 ✓
4011 T}@T{
4012 ✓
4013 T}@T{
4014 ✓
4015 T}@T{
4016 ✓
4017 T}@T{
4018 ✓
4019 T}@T{
4020 ✓
4021 T}
4022 T{
4023 \f[B]DISTRIBUTION_ARCHITECTURE\f[R]
4024 T}@T{
4025 ✓
4026 T}@T{
4027 ✓
4028 T}@T{
4029 ✓
4030 T}@T{
4031 ✓
4032 T}@T{
4033 ✓
4034 T}@T{
4035 ✓
4036 T}@T{
4037 ✓
4038 T}@T{
4039 ✓
4040 T}
4041 T{
4042 \f[B]EFI_ARCHITECTURE\f[R]
4043 T}@T{
4044 ✓
4045 T}@T{
4046 ✓
4047 T}@T{
4048 ✓
4049 T}@T{
4050 ✓
4051 T}@T{
4052 ✓
4053 T}@T{
4054 ✓
4055 T}@T{
4056 ✓
4057 T}@T{
4058 ✓
4059 T}
4060 T{
4061 \f[B]IMAGE_ID\f[R]
4062 T}@T{
4063 ✓
4064 T}@T{
4065 ✓
4066 T}@T{
4067 ✓
4068 T}@T{
4069 ✓
4070 T}@T{
4071 ✓
4072 T}@T{
4073 ✓
4074 T}@T{
4075 ✓
4076 T}@T{
4077 ✓
4078 T}
4079 T{
4080 \f[B]IMAGE_VERSION\f[R]
4081 T}@T{
4082 ✓
4083 T}@T{
4084 ✓
4085 T}@T{
4086 ✓
4087 T}@T{
4088 ✓
4089 T}@T{
4090 ✓
4091 T}@T{
4092 ✓
4093 T}@T{
4094 ✓
4095 T}@T{
4096 ✓
4097 T}
4098 T{
4099 \f[B]MKOSI_CONFIG\f[R]
4100 T}@T{
4101 T}@T{
4102 ✓
4103 T}@T{
4104 ✓
4105 T}@T{
4106 ✓
4107 T}@T{
4108 ✓
4109 T}@T{
4110 ✓
4111 T}@T{
4112 ✓
4113 T}@T{
4114 ✓
4115 T}
4116 T{
4117 \f[B]MKOSI_GID\f[R]
4118 T}@T{
4119 ✓
4120 T}@T{
4121 ✓
4122 T}@T{
4123 ✓
4124 T}@T{
4125 ✓
4126 T}@T{
4127 ✓
4128 T}@T{
4129 ✓
4130 T}@T{
4131 ✓
4132 T}@T{
4133 ✓
4134 T}
4135 T{
4136 \f[B]MKOSI_UID\f[R]
4137 T}@T{
4138 ✓
4139 T}@T{
4140 ✓
4141 T}@T{
4142 ✓
4143 T}@T{
4144 ✓
4145 T}@T{
4146 ✓
4147 T}@T{
4148 ✓
4149 T}@T{
4150 ✓
4151 T}@T{
4152 ✓
4153 T}
4154 T{
4155 \f[B]OUTPUTDIR\f[R]
4156 T}@T{
4157 T}@T{
4158 T}@T{
4159 T}@T{
4160 T}@T{
4161 ✓
4162 T}@T{
4163 ✓
4164 T}@T{
4165 ✓
4166 T}@T{
4167 ✓
4168 T}
4169 T{
4170 \f[B]PACKAGEDIR\f[R]
4171 T}@T{
4172 T}@T{
4173 T}@T{
4174 ✓
4175 T}@T{
4176 ✓
4177 T}@T{
4178 ✓
4179 T}@T{
4180 ✓
4181 T}@T{
4182 T}@T{
4183 T}
4184 T{
4185 \f[B]PROFILES\f[R]
4186 T}@T{
4187 ✓
4188 T}@T{
4189 ✓
4190 T}@T{
4191 ✓
4192 T}@T{
4193 ✓
4194 T}@T{
4195 ✓
4196 T}@T{
4197 ✓
4198 T}@T{
4199 T}@T{
4200 ✓
4201 T}
4202 T{
4203 \f[B]QEMU_ARCHITECTURE\f[R]
4204 T}@T{
4205 ✓
4206 T}@T{
4207 T}@T{
4208 T}@T{
4209 T}@T{
4210 T}@T{
4211 T}@T{
4212 T}@T{
4213 T}
4214 T{
4215 \f[B]RELEASE\f[R]
4216 T}@T{
4217 ✓
4218 T}@T{
4219 ✓
4220 T}@T{
4221 ✓
4222 T}@T{
4223 ✓
4224 T}@T{
4225 ✓
4226 T}@T{
4227 ✓
4228 T}@T{
4229 ✓
4230 T}@T{
4231 ✓
4232 T}
4233 T{
4234 \f[B]SOURCE_DATE_EPOCH\f[R]
4235 T}@T{
4236 T}@T{
4237 T}@T{
4238 ✓
4239 T}@T{
4240 ✓
4241 T}@T{
4242 ✓
4243 T}@T{
4244 ✓
4245 T}@T{
4246 T}@T{
4247 ✓
4248 T}
4249 T{
4250 \f[B]SRCDIR\f[R]
4251 T}@T{
4252 ✓
4253 T}@T{
4254 ✓
4255 T}@T{
4256 ✓
4257 T}@T{
4258 ✓
4259 T}@T{
4260 ✓
4261 T}@T{
4262 ✓
4263 T}@T{
4264 ✓
4265 T}@T{
4266 ✓
4267 T}
4268 T{
4269 \f[B]WITH_DOCS\f[R]
4270 T}@T{
4271 T}@T{
4272 T}@T{
4273 ✓
4274 T}@T{
4275 ✓
4276 T}@T{
4277 T}@T{
4278 T}@T{
4279 T}@T{
4280 T}
4281 T{
4282 \f[B]WITH_NETWORK\f[R]
4283 T}@T{
4284 T}@T{
4285 T}@T{
4286 ✓
4287 T}@T{
4288 ✓
4289 T}@T{
4290 ✓
4291 T}@T{
4292 ✓
4293 T}@T{
4294 T}@T{
4295 T}
4296 T{
4297 \f[B]WITH_TESTS\f[R]
4298 T}@T{
4299 T}@T{
4300 T}@T{
4301 ✓
4302 T}@T{
4303 ✓
4304 T}@T{
4305 T}@T{
4306 T}@T{
4307 T}@T{
4308 T}
4309 .TE
4310 .PP
4311 Additionally, when a script is executed, a few scripts are made
4312 available via \f[B]$PATH\f[R] to simplify common usecases.
4313 .IP \[bu] 2
4314 \f[B]mkosi\-chroot\f[R]: This script will chroot into the image and
4315 execute the given command.
4316 On top of chrooting into the image, it will also mount various files and
4317 directories (\f[B]$SRCDIR\f[R], \f[B]$DESTDIR\f[R], \f[B]$BUILDDIR\f[R],
4318 \f[B]$OUTPUTDIR\f[R], \f[B]$CHROOT_SCRIPT\f[R]) into the image and
4319 modify the corresponding environment variables to point to the locations
4320 inside the image.
4321 It will also mount APIVFS filesystems (\f[B]/proc\f[R], \f[B]/dev\f[R],
4322 \&...)
4323 to make sure scripts and tools executed inside the chroot work properly.
4324 It also propagates \f[B]/etc/resolv.conf\f[R] from the host into the
4325 chroot if requested so that DNS resolution works inside the chroot.
4326 After the mkosi\-chroot command exits, various mount points are cleaned
4327 up.
4328 .RS 2
4329 .PP
4330 For example, to invoke \f[B]ls\f[R] inside of the image, use the
4331 following:
4332 .IP
4333 .EX
4334 mkosi\-chroot ls ...
4335 .EE
4336 .PP
4337 To execute the entire script inside the image, add a \f[B].chroot\f[R]
4338 suffix to the name (\f[B]mkosi.build.chroot\f[R] instead of
4339 \f[B]mkosi.build\f[R], etc.).
4340 .RE
4341 .IP \[bu] 2
4342 For all of the supported package managers (\f[B]dnf\f[R], \f[B]rpm\f[R],
4343 \f[B]apt\f[R], \f[B]dpkg\f[R], \f[B]pacman\f[R], \f[B]zypper\f[R]),
4344 scripts of the same name are put into \f[B]$PATH\f[R] that make sure
4345 these commands operate on the image\[cq]s root directory with the
4346 configuration supplied by the user instead of on the host system.
4347 This means that from a script, you can do e.g.
4348 \f[B]dnf install vim\f[R] to install vim into the image.
4349 .RS 2
4350 .PP
4351 Additionally, \f[B]mkosi\-install\f[R], \f[B]mkosi\-reinstall\f[R],
4352 \f[B]mkosi\-upgrade\f[R] and \f[B]mkosi\-remove\f[R] will invoke the
4353 corresponding operation of the package manager being used to built the
4354 image.
4355 .RE
4356 .IP \[bu] 2
4357 \f[B]git\f[R] is automatically invoked with \f[B]safe.directory=*\f[R]
4358 to avoid permissions errors when running as the root user in a user
4359 namespace.
4360 .IP \[bu] 2
4361 \f[B]useradd\f[R] and \f[B]groupadd\f[R] are automatically invoked with
4362 \f[B]\-\-root=$BUILDROOT\f[R] when executed outside of the image.
4363 .PP
4364 When scripts are executed, any directories that are still writable are
4365 also made read\-only (\f[B]/home\f[R], \f[B]/var\f[R], \f[B]/root\f[R],
4366 \&...)
4367 and only the minimal set of directories that need to be writable remain
4368 writable.
4369 This is to ensure that scripts can\[cq]t mess with the host system when
4370 \f[B]mkosi\f[R] is running as root.
4371 .PP
4372 Note that when executing scripts, all source directories are made
4373 ephemeral which means all changes made to source directories while
4374 running scripts are thrown away after the scripts finish executing.
4375 Use the output, build or cache directories if you need to persist data
4376 between builds.
4377 .SH FILES
4378 To make it easy to build images for development versions of your
4379 projects, \f[B]mkosi\f[R] can read configuration data from the local
4380 directory, under the assumption that it is invoked from a
4381 \f[I]source\f[R] tree.
4382 Specifically, the following files are used if they exist in the local
4383 directory:
4384 .IP \[bu] 2
4385 The \f[B]\f[R]mkosi.skeleton/\f[B]\f[R] directory or
4386 \f[B]\f[R]mkosi.skeleton.tar\f[B]\f[R] archive may be used to insert
4387 files into the image.
4388 The files are copied \f[I]before\f[R] the distribution packages are
4389 installed into the image.
4390 This allows creation of files that need to be provided early, for
4391 example to configure the package manager or set systemd presets.
4392 .RS 2
4393 .PP
4394 When using the directory, file ownership is not preserved: all files
4395 copied will be owned by root.
4396 To preserve ownership, use a tar archive.
4397 .RE
4398 .IP \[bu] 2
4399 The \f[B]\f[R]mkosi.extra/\f[B]\f[R] directory or
4400 \f[B]\f[R]mkosi.extra.tar\f[B]\f[R] archive may be used to insert
4401 additional files into the image, on top of what the distribution
4402 includes in its packages.
4403 They are similar to \f[B]mkosi.skeleton/\f[R] and
4404 \f[B]mkosi.skeleton.tar\f[R], but the files are copied into the
4405 directory tree of the image \f[I]after\f[R] the OS was installed.
4406 .RS 2
4407 .PP
4408 When using the directory, file ownership is not preserved: all files
4409 copied will be owned by root.
4410 To preserve ownership, use a tar archive.
4411 .RE
4412 .IP \[bu] 2
4413 The \f[B]\f[R]mkosi.sandbox/\f[B]\f[R] directory or
4414 \f[B]\f[R]mkosi.sandbox.tar\f[B]\f[R] archive may be used to configure
4415 the package manager without the files being inserted into the image.
4416 If the files should be included in the image \f[B]mkosi.skeleton/\f[R]
4417 and \f[B]mkosi.skeleton.tar\f[R] should be used instead.
4418 .RS 2
4419 .PP
4420 When using the directory, file ownership is not preserved: all files
4421 copied will be owned by root.
4422 To preserve ownership, use a tar archive.
4423 .RE
4424 .IP \[bu] 2
4425 The \f[B]\f[R]mkosi.nspawn\f[B]\f[R] nspawn settings file will be copied
4426 into the same place as the output image file, if it exists.
4427 This is useful since nspawn looks for settings files next to image files
4428 it boots, for additional container runtime settings.
4429 .IP \[bu] 2
4430 The \f[B]\f[R]mkosi.cache/\f[B]\f[R] directory, if it exists, is
4431 automatically used as package download cache, in order to speed repeated
4432 runs of the tool.
4433 .IP \[bu] 2
4434 The \f[B]\f[R]mkosi.builddir/\f[B]\f[R] directory, if it exists, is
4435 automatically used as out\-of\-tree build directory, if the build
4436 commands in the \f[B]mkosi.build\f[R] scripts support it.
4437 Specifically, this directory will be mounted into the build container,
4438 and the \f[B]$BUILDDIR\f[R] environment variable will be set to it when
4439 the build scripts are invoked.
4440 A build script may then use this directory as build directory, for
4441 \f[B]automake\f[R]\-style or \f[B]ninja\f[R]\-style out\-of\-tree
4442 builds.
4443 This speeds up builds considerably, in particular when \f[B]mkosi\f[R]
4444 is used in incremental mode (\f[B]\-i\f[R]): not only the image and
4445 build overlay, but also the build tree is reused between subsequent
4446 invocations.
4447 Note that if this directory does not exist the \f[B]$BUILDDIR\f[R]
4448 environment variable is not set, and it is up to the build scripts to
4449 decide whether to do an in\-tree or an out\-of\-tree build, and which
4450 build directory to use.
4451 .IP \[bu] 2
4452 The \f[B]\f[R]mkosi.rootpw\f[B]\f[R] file can be used to provide the
4453 password for the root user of the image.
4454 If the password is prefixed with \f[B]hashed:\f[R] it is treated as an
4455 already hashed root password.
4456 The password may optionally be followed by a newline character which is
4457 implicitly removed.
4458 The file must have an access mode of 0600 or less.
4459 If this file does not exist, the distribution\[cq]s default root
4460 password is set (which usually means access to the root user is
4461 blocked).
4462 .IP \[bu] 2
4463 The \f[B]\f[R]mkosi.passphrase\f[B]\f[R] file provides the passphrase to
4464 use when LUKS encryption is selected.
4465 It should contain the passphrase literally, and not end in a newline
4466 character (i.e.\ in the same format as \f[B]cryptsetup\f[R] and
4467 \f[B]/etc/crypttab\f[R] expect the passphrase files).
4468 The file must have an access mode of 0600 or less.
4469 .IP \[bu] 2
4470 The \f[B]\f[R]mkosi.crt\f[B]\f[R] and \f[B]\f[R]mkosi.key\f[B]\f[R]
4471 files contain an X.509 certificate and PEM private key to use when
4472 signing is required (UEFI SecureBoot, verity, \&...).
4473 .IP \[bu] 2
4474 The \f[B]\f[R]mkosi.output/\f[B]\f[R] directory is used to store all
4475 build artifacts.
4476 .IP \[bu] 2
4477 The \f[B]\f[R]mkosi.credentials/\f[B]\f[R] directory is used as a source
4478 of extra credentials similar to the \f[B]Credentials=\f[R] option.
4479 For each file in the directory, the filename will be used as the
4480 credential name and the file contents become the credential value, or,
4481 if the file is executable, \f[B]mkosi\f[R] will execute the file and the
4482 command\[cq]s output to stdout will be used as the credential value.
4483 Output to stderr will be ignored.
4484 Credentials configured with \f[B]Credentials=\f[R] take precedence over
4485 files in \f[B]mkosi.credentials\f[R].
4486 .IP \[bu] 2
4487 The \f[B]\f[R]mkosi.repart/\f[B]\f[R] directory is used as the source
4488 for \f[B]systemd\-repart\f[R] partition definition files which are
4489 passed to \f[B]systemd\-repart\f[R] when building a disk image.
4490 If it does not exist and the \f[B]RepartDirectories=\f[R] setting is not
4491 configured, \f[B]mkosi\f[R] will default to the following partition
4492 definition files:
4493 .RS 2
4494 .PP
4495 \f[B]00\-esp.conf\f[R] (if we\[cq]re building a bootable image):
4496 .IP
4497 .EX
4498 \f[B][Partition]\f[R]
4499 Type=esp
4500 Format=vfat
4501 CopyFiles=/boot:/
4502 CopyFiles=/efi:/
4503 SizeMinBytes=512M
4504 SizeMaxBytes=512M
4505 .EE
4506 .PP
4507 \f[B]05\-bios.conf\f[R] (if we\[cq]re building a BIOS bootable image):
4508 .IP
4509 .EX
4510 \f[B][Partition]\f[R]
4511 \f[I]# UUID of the grub BIOS boot partition which grubs needs on GPT to\f[R]
4512 \f[I]# embed itself into.\f[R]
4513 Type=21686148\-6449\-6e6f\-744e\-656564454649
4514 SizeMinBytes=1M
4515 SizeMaxBytes=1M
4516 .EE
4517 .PP
4518 \f[B]10\-root.conf\f[R]
4519 .IP
4520 .EX
4521 \f[B][Partition]\f[R]
4522 Type=root
4523 Format=<distribution\-default\-filesystem>
4524 CopyFiles=/
4525 Minimize=guess
4526 .EE
4527 .PP
4528 Note that if either \f[B]mkosi.repart/\f[R] is found or
4529 \f[B]RepartDirectories=\f[R] is used, we will not use any of the default
4530 partition definitions.
4531 .RE
4532 .PP
4533 All these files are optional.
4534 .PP
4535 Note that the location of all these files may also be configured during
4536 invocation via command line switches, and as settings in
4537 \f[B]mkosi.conf\f[R], in case the default settings are not acceptable
4538 for a project.
4539 .SH CACHING
4540 \f[B]mkosi\f[R] supports three different caches for speeding up
4541 repetitive re\-building of images.
4542 Specifically:
4543 .IP "1." 3
4544 The package cache of the distribution package manager may be cached
4545 between builds.
4546 This is configured with the \f[B]\-\-cache\-directory=\f[R] option or
4547 the \f[B]mkosi.cache/\f[R] directory.
4548 This form of caching relies on the distribution\[cq]s package manager,
4549 and caches distribution packages (RPM, deb, \&...)
4550 after they are downloaded, but before they are unpacked.
4551 .IP "2." 3
4552 If the incremental build mode is enabled with
4553 \f[B]\-\-incremental=yes\f[R], cached copies of the final image and
4554 build overlay are made immediately before the build sources are copied
4555 in (for the build overlay) or the artifacts generated by
4556 \f[B]mkosi.build\f[R] are copied in (in case of the final image).
4557 This form of caching allows bypassing the time\-consuming package
4558 unpacking step of the distribution package managers, but is only
4559 effective if the list of packages to use remains stable, but the build
4560 sources and its scripts change regularly.
4561 Note that this cache requires manual flushing: whenever the package list
4562 is modified the cached images need to be explicitly removed before the
4563 next re\-build, using the \f[B]\-f\f[R] switch.
4564 .IP "3." 3
4565 Finally, between multiple builds the build artifact directory may be
4566 shared, using the \f[B]mkosi.builddir/\f[R] directory.
4567 This directory allows build systems such as Meson to reuse already
4568 compiled sources from a previous built, thus speeding up the build
4569 process of a \f[B]mkosi.build\f[R] build script.
4570 .PP
4571 The package cache and incremental mode are unconditionally useful.
4572 The final cache only apply to uses of \f[B]mkosi\f[R] with a source tree
4573 and build script.
4574 When all three are enabled together turn\-around times for complete
4575 image builds are minimal, as only changed source files need to be
4576 recompiled.
4577 .SH TOOLS TREES
4578 Tools trees are a secondary image that mkosi can use to build the actual
4579 images.
4580 This is useful to make image builds more reproducible, but also allows
4581 to use newer tooling, that is not yet available in the host distribution
4582 running mkosi.
4583 .PP
4584 Tools trees can be provided via the \f[B]ToolsTree=\f[R] option, the
4585 \f[B]mkosi.tools\f[R] directory or built automatically by mkosi if set
4586 to \f[B]ToolsTree=yes\f[R].
4587 For most use cases setting it is sufficient to use the default tools
4588 trees and the use of a tools tree is recommended.
4589 .PP
4590 Fully custom tools trees can be built like any other mkosi image, but
4591 mkosi provides a builtin include providing the default tools tree
4592 packages:
4593 .IP
4594 .EX
4595 mkosi \-\-include=mkosi\-tools \-\-format=directory
4596 .EE
4597 .PP
4598 Tools trees, including default tools trees, can be further customized
4599 via the different \f[B]ToolsTree*=\f[R] variables as well as the
4600 \f[B]mkosi.tools.conf\f[R] configuration file or directory.
4601 The output format for tools trees cannot currently be changed via
4602 configuration files.
4603 .PP
4604 The following table shows for which distributions default tools tree
4605 packages are defined and which packages are included in those default
4606 tools trees:
4607 .PP
4608 .TS
4609 tab(@);
4610 lw(18.8n) cw(6.0n) cw(6.0n) cw(6.0n) cw(4.5n) cw(6.0n) cw(4.5n) cw(7.5n) cw(10.5n).
4611 T{
4612 T}@T{
4613 Fedora
4614 T}@T{
4615 CentOS
4616 T}@T{
4617 Debian
4618 T}@T{
4619 Kali
4620 T}@T{
4621 Ubuntu
4622 T}@T{
4623 Arch
4624 T}@T{
4625 openSUSE
4626 T}@T{
4627 postmarketOS
4628 T}
4629 _
4630 T{
4631 \f[B]acl\f[R]
4632 T}@T{
4633 ✓
4634 T}@T{
4635 ✓
4636 T}@T{
4637 ✓
4638 T}@T{
4639 ✓
4640 T}@T{
4641 ✓
4642 T}@T{
4643 ✓
4644 T}@T{
4645 ✓
4646 T}@T{
4647 ✓
4648 T}
4649 T{
4650 \f[B]apt\f[R]
4651 T}@T{
4652 ✓
4653 T}@T{
4654 ✓
4655 T}@T{
4656 ✓
4657 T}@T{
4658 ✓
4659 T}@T{
4660 ✓
4661 T}@T{
4662 ✓
4663 T}@T{
4664 T}@T{
4665 T}
4666 T{
4667 \f[B]archlinux\-keyring\f[R]
4668 T}@T{
4669 ✓
4670 T}@T{
4671 ✓
4672 T}@T{
4673 ✓
4674 T}@T{
4675 ✓
4676 T}@T{
4677 ✓
4678 T}@T{
4679 ✓
4680 T}@T{
4681 T}@T{
4682 T}
4683 T{
4684 \f[B]attr\f[R]
4685 T}@T{
4686 ✓
4687 T}@T{
4688 ✓
4689 T}@T{
4690 ✓
4691 T}@T{
4692 ✓
4693 T}@T{
4694 ✓
4695 T}@T{
4696 ✓
4697 T}@T{
4698 ✓
4699 T}@T{
4700 ✓
4701 T}
4702 T{
4703 \f[B]bash\f[R]
4704 T}@T{
4705 ✓
4706 T}@T{
4707 ✓
4708 T}@T{
4709 ✓
4710 T}@T{
4711 ✓
4712 T}@T{
4713 ✓
4714 T}@T{
4715 ✓
4716 T}@T{
4717 ✓
4718 T}@T{
4719 ✓
4720 T}
4721 T{
4722 \f[B]btrfs\-progs\f[R]
4723 T}@T{
4724 ✓
4725 T}@T{
4726 ✓
4727 T}@T{
4728 ✓
4729 T}@T{
4730 ✓
4731 T}@T{
4732 ✓
4733 T}@T{
4734 ✓
4735 T}@T{
4736 ✓
4737 T}@T{
4738 ✓
4739 T}
4740 T{
4741 \f[B]ca\-certificates\f[R]
4742 T}@T{
4743 ✓
4744 T}@T{
4745 ✓
4746 T}@T{
4747 ✓
4748 T}@T{
4749 ✓
4750 T}@T{
4751 ✓
4752 T}@T{
4753 ✓
4754 T}@T{
4755 ✓
4756 T}@T{
4757 ✓
4758 T}
4759 T{
4760 \f[B]coreutils\f[R]
4761 T}@T{
4762 ✓
4763 T}@T{
4764 ✓
4765 T}@T{
4766 ✓
4767 T}@T{
4768 ✓
4769 T}@T{
4770 ✓
4771 T}@T{
4772 ✓
4773 T}@T{
4774 ✓
4775 T}@T{
4776 ✓
4777 T}
4778 T{
4779 \f[B]cpio\f[R]
4780 T}@T{
4781 ✓
4782 T}@T{
4783 ✓
4784 T}@T{
4785 ✓
4786 T}@T{
4787 ✓
4788 T}@T{
4789 ✓
4790 T}@T{
4791 ✓
4792 T}@T{
4793 ✓
4794 T}@T{
4795 ✓
4796 T}
4797 T{
4798 \f[B]createrepo_c\f[R]
4799 T}@T{
4800 ✓
4801 T}@T{
4802 ✓
4803 T}@T{
4804 ✓
4805 T}@T{
4806 ✓
4807 T}@T{
4808 ✓
4809 T}@T{
4810 ✓
4811 T}@T{
4812 ✓
4813 T}@T{
4814 ✓
4815 T}
4816 T{
4817 \f[B]curl\f[R]
4818 T}@T{
4819 ✓
4820 T}@T{
4821 ✓
4822 T}@T{
4823 ✓
4824 T}@T{
4825 ✓
4826 T}@T{
4827 ✓
4828 T}@T{
4829 ✓
4830 T}@T{
4831 ✓
4832 T}@T{
4833 ✓
4834 T}
4835 T{
4836 \f[B]debian\-keyring\f[R]
4837 T}@T{
4838 ✓
4839 T}@T{
4840 ✓
4841 T}@T{
4842 ✓
4843 T}@T{
4844 ✓
4845 T}@T{
4846 ✓
4847 T}@T{
4848 ✓
4849 T}@T{
4850 T}@T{
4851 ✓
4852 T}
4853 T{
4854 \f[B]diffutils\f[R]
4855 T}@T{
4856 ✓
4857 T}@T{
4858 ✓
4859 T}@T{
4860 ✓
4861 T}@T{
4862 ✓
4863 T}@T{
4864 ✓
4865 T}@T{
4866 ✓
4867 T}@T{
4868 ✓
4869 T}@T{
4870 ✓
4871 T}
4872 T{
4873 \f[B]distribution\-gpg\-keys\f[R]
4874 T}@T{
4875 ✓
4876 T}@T{
4877 ✓
4878 T}@T{
4879 ✓
4880 T}@T{
4881 ✓
4882 T}@T{
4883 T}@T{
4884 ✓
4885 T}@T{
4886 ✓
4887 T}@T{
4888 ✓
4889 T}
4890 T{
4891 \f[B]dnf\f[R]
4892 T}@T{
4893 ✓
4894 T}@T{
4895 ✓
4896 T}@T{
4897 ✓
4898 T}@T{
4899 ✓
4900 T}@T{
4901 ✓
4902 T}@T{
4903 ✓
4904 T}@T{
4905 ✓
4906 T}@T{
4907 ✓
4908 T}
4909 T{
4910 \f[B]dosfstools\f[R]
4911 T}@T{
4912 ✓
4913 T}@T{
4914 ✓
4915 T}@T{
4916 ✓
4917 T}@T{
4918 ✓
4919 T}@T{
4920 ✓
4921 T}@T{
4922 ✓
4923 T}@T{
4924 ✓
4925 T}@T{
4926 ✓
4927 T}
4928 T{
4929 \f[B]e2fsprogs\f[R]
4930 T}@T{
4931 ✓
4932 T}@T{
4933 ✓
4934 T}@T{
4935 ✓
4936 T}@T{
4937 ✓
4938 T}@T{
4939 ✓
4940 T}@T{
4941 ✓
4942 T}@T{
4943 ✓
4944 T}@T{
4945 ✓
4946 T}
4947 T{
4948 \f[B]edk2\-ovmf\f[R]
4949 T}@T{
4950 ✓
4951 T}@T{
4952 ✓
4953 T}@T{
4954 ✓
4955 T}@T{
4956 ✓
4957 T}@T{
4958 ✓
4959 T}@T{
4960 ✓
4961 T}@T{
4962 ✓
4963 T}@T{
4964 ✓
4965 T}
4966 T{
4967 \f[B]erofs\-utils\f[R]
4968 T}@T{
4969 ✓
4970 T}@T{
4971 ✓
4972 T}@T{
4973 ✓
4974 T}@T{
4975 ✓
4976 T}@T{
4977 ✓
4978 T}@T{
4979 ✓
4980 T}@T{
4981 ✓
4982 T}@T{
4983 ✓
4984 T}
4985 T{
4986 \f[B]findutils\f[R]
4987 T}@T{
4988 ✓
4989 T}@T{
4990 ✓
4991 T}@T{
4992 ✓
4993 T}@T{
4994 ✓
4995 T}@T{
4996 ✓
4997 T}@T{
4998 ✓
4999 T}@T{
5000 ✓
5001 T}@T{
5002 ✓
5003 T}
5004 T{
5005 \f[B]git\f[R]
5006 T}@T{
5007 ✓
5008 T}@T{
5009 ✓
5010 T}@T{
5011 ✓
5012 T}@T{
5013 ✓
5014 T}@T{
5015 ✓
5016 T}@T{
5017 ✓
5018 T}@T{
5019 ✓
5020 T}@T{
5021 ✓
5022 T}
5023 T{
5024 \f[B]grep\f[R]
5025 T}@T{
5026 ✓
5027 T}@T{
5028 ✓
5029 T}@T{
5030 ✓
5031 T}@T{
5032 ✓
5033 T}@T{
5034 ✓
5035 T}@T{
5036 ✓
5037 T}@T{
5038 ✓
5039 T}@T{
5040 ✓
5041 T}
5042 T{
5043 \f[B]grub\-tools\f[R]
5044 T}@T{
5045 ✓
5046 T}@T{
5047 ✓
5048 T}@T{
5049 ✓
5050 T}@T{
5051 ✓
5052 T}@T{
5053 ✓
5054 T}@T{
5055 ✓
5056 T}@T{
5057 T}@T{
5058 T}
5059 T{
5060 \f[B]jq\f[R]
5061 T}@T{
5062 ✓
5063 T}@T{
5064 ✓
5065 T}@T{
5066 ✓
5067 T}@T{
5068 ✓
5069 T}@T{
5070 ✓
5071 T}@T{
5072 ✓
5073 T}@T{
5074 ✓
5075 T}@T{
5076 ✓
5077 T}
5078 T{
5079 \f[B]kali\-archive\-keyring\f[R]
5080 T}@T{
5081 T}@T{
5082 T}@T{
5083 T}@T{
5084 ✓
5085 T}@T{
5086 T}@T{
5087 T}@T{
5088 T}@T{
5089 T}
5090 T{
5091 \f[B]kmod\f[R]
5092 T}@T{
5093 ✓
5094 T}@T{
5095 ✓
5096 T}@T{
5097 ✓
5098 T}@T{
5099 ✓
5100 T}@T{
5101 ✓
5102 T}@T{
5103 ✓
5104 T}@T{
5105 ✓
5106 T}@T{
5107 ✓
5108 T}
5109 T{
5110 \f[B]less\f[R]
5111 T}@T{
5112 ✓
5113 T}@T{
5114 ✓
5115 T}@T{
5116 ✓
5117 T}@T{
5118 ✓
5119 T}@T{
5120 ✓
5121 T}@T{
5122 ✓
5123 T}@T{
5124 ✓
5125 T}@T{
5126 ✓
5127 T}
5128 T{
5129 \f[B]mtools\f[R]
5130 T}@T{
5131 ✓
5132 T}@T{
5133 ✓
5134 T}@T{
5135 ✓
5136 T}@T{
5137 ✓
5138 T}@T{
5139 ✓
5140 T}@T{
5141 ✓
5142 T}@T{
5143 ✓
5144 T}@T{
5145 ✓
5146 T}
5147 T{
5148 \f[B]nano\f[R]
5149 T}@T{
5150 ✓
5151 T}@T{
5152 ✓
5153 T}@T{
5154 ✓
5155 T}@T{
5156 ✓
5157 T}@T{
5158 ✓
5159 T}@T{
5160 ✓
5161 T}@T{
5162 ✓
5163 T}@T{
5164 ✓
5165 T}
5166 T{
5167 \f[B]opensc\f[R]
5168 T}@T{
5169 ✓
5170 T}@T{
5171 ✓
5172 T}@T{
5173 ✓
5174 T}@T{
5175 ✓
5176 T}@T{
5177 ✓
5178 T}@T{
5179 ✓
5180 T}@T{
5181 ✓
5182 T}@T{
5183 ✓
5184 T}
5185 T{
5186 \f[B]openssh\f[R]
5187 T}@T{
5188 ✓
5189 T}@T{
5190 ✓
5191 T}@T{
5192 ✓
5193 T}@T{
5194 ✓
5195 T}@T{
5196 ✓
5197 T}@T{
5198 ✓
5199 T}@T{
5200 ✓
5201 T}@T{
5202 ✓
5203 T}
5204 T{
5205 \f[B]openssl\f[R]
5206 T}@T{
5207 ✓
5208 T}@T{
5209 ✓
5210 T}@T{
5211 ✓
5212 T}@T{
5213 ✓
5214 T}@T{
5215 ✓
5216 T}@T{
5217 ✓
5218 T}@T{
5219 ✓
5220 T}@T{
5221 ✓
5222 T}
5223 T{
5224 \f[B]pkcs11\-provider\f[R]
5225 T}@T{
5226 ✓
5227 T}@T{
5228 ✓
5229 T}@T{
5230 ✓
5231 T}@T{
5232 ✓
5233 T}@T{
5234 ✓
5235 T}@T{
5236 ✓
5237 T}@T{
5238 ✓
5239 T}@T{
5240 ✓
5241 T}
5242 T{
5243 \f[B]perf\f[R]
5244 T}@T{
5245 ✓
5246 T}@T{
5247 ✓
5248 T}@T{
5249 ✓
5250 T}@T{
5251 ✓
5252 T}@T{
5253 T}@T{
5254 ✓
5255 T}@T{
5256 ✓
5257 T}@T{
5258 ✓
5259 T}
5260 T{
5261 \f[B]sed\f[R]
5262 T}@T{
5263 ✓
5264 T}@T{
5265 ✓
5266 T}@T{
5267 ✓
5268 T}@T{
5269 ✓
5270 T}@T{
5271 ✓
5272 T}@T{
5273 ✓
5274 T}@T{
5275 ✓
5276 T}@T{
5277 ✓
5278 T}
5279 T{
5280 \f[B]pacman\f[R]
5281 T}@T{
5282 ✓
5283 T}@T{
5284 ✓
5285 T}@T{
5286 ✓
5287 T}@T{
5288 ✓
5289 T}@T{
5290 ✓
5291 T}@T{
5292 ✓
5293 T}@T{
5294 T}@T{
5295 ✓
5296 T}
5297 T{
5298 \f[B]p11\-kit\f[R]
5299 T}@T{
5300 ✓
5301 T}@T{
5302 ✓
5303 T}@T{
5304 ✓
5305 T}@T{
5306 ✓
5307 T}@T{
5308 ✓
5309 T}@T{
5310 ✓
5311 T}@T{
5312 ✓
5313 T}@T{
5314 ✓
5315 T}
5316 T{
5317 \f[B]policycoreutils\f[R]
5318 T}@T{
5319 ✓
5320 T}@T{
5321 ✓
5322 T}@T{
5323 ✓
5324 T}@T{
5325 ✓
5326 T}@T{
5327 ✓
5328 T}@T{
5329 T}@T{
5330 ✓
5331 T}@T{
5332 ✓
5333 T}
5334 T{
5335 \f[B]qemu\f[R]
5336 T}@T{
5337 ✓
5338 T}@T{
5339 ✓
5340 T}@T{
5341 ✓
5342 T}@T{
5343 ✓
5344 T}@T{
5345 ✓
5346 T}@T{
5347 ✓
5348 T}@T{
5349 ✓
5350 T}@T{
5351 ✓
5352 T}
5353 T{
5354 \f[B]sbsigntools\f[R]
5355 T}@T{
5356 ✓
5357 T}@T{
5358 ✓
5359 T}@T{
5360 ✓
5361 T}@T{
5362 ✓
5363 T}@T{
5364 ✓
5365 T}@T{
5366 ✓
5367 T}@T{
5368 ✓
5369 T}@T{
5370 ✓
5371 T}
5372 T{
5373 \f[B]socat\f[R]
5374 T}@T{
5375 ✓
5376 T}@T{
5377 ✓
5378 T}@T{
5379 ✓
5380 T}@T{
5381 ✓
5382 T}@T{
5383 ✓
5384 T}@T{
5385 ✓
5386 T}@T{
5387 ✓
5388 T}@T{
5389 ✓
5390 T}
5391 T{
5392 \f[B]squashfs\-tools\f[R]
5393 T}@T{
5394 ✓
5395 T}@T{
5396 ✓
5397 T}@T{
5398 ✓
5399 T}@T{
5400 ✓
5401 T}@T{
5402 ✓
5403 T}@T{
5404 ✓
5405 T}@T{
5406 ✓
5407 T}@T{
5408 ✓
5409 T}
5410 T{
5411 \f[B]strace\f[R]
5412 T}@T{
5413 ✓
5414 T}@T{
5415 ✓
5416 T}@T{
5417 ✓
5418 T}@T{
5419 ✓
5420 T}@T{
5421 ✓
5422 T}@T{
5423 ✓
5424 T}@T{
5425 ✓
5426 T}@T{
5427 ✓
5428 T}
5429 T{
5430 \f[B]swtpm\f[R]
5431 T}@T{
5432 ✓
5433 T}@T{
5434 ✓
5435 T}@T{
5436 ✓
5437 T}@T{
5438 ✓
5439 T}@T{
5440 ✓
5441 T}@T{
5442 ✓
5443 T}@T{
5444 ✓
5445 T}@T{
5446 ✓
5447 T}
5448 T{
5449 \f[B]systemd\f[R]
5450 T}@T{
5451 ✓
5452 T}@T{
5453 ✓
5454 T}@T{
5455 ✓
5456 T}@T{
5457 ✓
5458 T}@T{
5459 ✓
5460 T}@T{
5461 ✓
5462 T}@T{
5463 ✓
5464 T}@T{
5465 ✓
5466 T}
5467 T{
5468 \f[B]ukify\f[R]
5469 T}@T{
5470 ✓
5471 T}@T{
5472 ✓
5473 T}@T{
5474 ✓
5475 T}@T{
5476 ✓
5477 T}@T{
5478 ✓
5479 T}@T{
5480 ✓
5481 T}@T{
5482 ✓
5483 T}@T{
5484 ✓
5485 T}
5486 T{
5487 \f[B]tar\f[R]
5488 T}@T{
5489 ✓
5490 T}@T{
5491 ✓
5492 T}@T{
5493 ✓
5494 T}@T{
5495 ✓
5496 T}@T{
5497 ✓
5498 T}@T{
5499 ✓
5500 T}@T{
5501 ✓
5502 T}@T{
5503 ✓
5504 T}
5505 T{
5506 \f[B]ubuntu\-keyring\f[R]
5507 T}@T{
5508 ✓
5509 T}@T{
5510 ✓
5511 T}@T{
5512 ✓
5513 T}@T{
5514 ✓
5515 T}@T{
5516 ✓
5517 T}@T{
5518 ✓
5519 T}@T{
5520 T}@T{
5521 T}
5522 T{
5523 \f[B]util\-linux\f[R]
5524 T}@T{
5525 ✓
5526 T}@T{
5527 ✓
5528 T}@T{
5529 ✓
5530 T}@T{
5531 ✓
5532 T}@T{
5533 ✓
5534 T}@T{
5535 ✓
5536 T}@T{
5537 ✓
5538 T}@T{
5539 ✓
5540 T}
5541 T{
5542 \f[B]virtiofsd\f[R]
5543 T}@T{
5544 ✓
5545 T}@T{
5546 ✓
5547 T}@T{
5548 ✓
5549 T}@T{
5550 ✓
5551 T}@T{
5552 ✓
5553 T}@T{
5554 ✓
5555 T}@T{
5556 ✓
5557 T}@T{
5558 ✓
5559 T}
5560 T{
5561 \f[B]virt\-firmware\f[R]
5562 T}@T{
5563 ✓
5564 T}@T{
5565 ✓
5566 T}@T{
5567 ✓
5568 T}@T{
5569 ✓
5570 T}@T{
5571 ✓
5572 T}@T{
5573 ✓
5574 T}@T{
5575 ✓
5576 T}@T{
5577 ✓
5578 T}
5579 T{
5580 \f[B]xfsprogs\f[R]
5581 T}@T{
5582 ✓
5583 T}@T{
5584 ✓
5585 T}@T{
5586 ✓
5587 T}@T{
5588 ✓
5589 T}@T{
5590 ✓
5591 T}@T{
5592 ✓
5593 T}@T{
5594 ✓
5595 T}@T{
5596 ✓
5597 T}
5598 T{
5599 \f[B]xz\f[R]
5600 T}@T{
5601 ✓
5602 T}@T{
5603 ✓
5604 T}@T{
5605 ✓
5606 T}@T{
5607 ✓
5608 T}@T{
5609 ✓
5610 T}@T{
5611 ✓
5612 T}@T{
5613 ✓
5614 T}@T{
5615 ✓
5616 T}
5617 T{
5618 \f[B]zstd\f[R]
5619 T}@T{
5620 ✓
5621 T}@T{
5622 ✓
5623 T}@T{
5624 ✓
5625 T}@T{
5626 ✓
5627 T}@T{
5628 ✓
5629 T}@T{
5630 ✓
5631 T}@T{
5632 ✓
5633 T}@T{
5634 ✓
5635 T}
5636 T{
5637 \f[B]zypper\f[R]
5638 T}@T{
5639 ✓
5640 T}@T{
5641 T}@T{
5642 ✓
5643 T}@T{
5644 ✓
5645 T}@T{
5646 ✓
5647 T}@T{
5648 ✓
5649 T}@T{
5650 ✓
5651 T}@T{
5652 T}
5653 .TE
5654 .SH BUILDING MULTIPLE IMAGES
5655 If the \f[B]mkosi.images/\f[R] directory exists, \f[B]mkosi\f[R] will
5656 load individual subimage configurations from it and build each of them.
5657 Image configurations can be either directories containing
5658 \f[B]mkosi\f[R] configuration files or regular files with the
5659 \f[B].conf\f[R] extension.
5660 .PP
5661 When image configurations are found in \f[B]mkosi.images/\f[R],
5662 \f[B]mkosi\f[R] will build the images specified in the
5663 \f[B]Dependencies=\f[R] setting of the main image and all of their
5664 dependencies (or all of them if no images were explicitly configured
5665 using \f[B]Dependencies=\f[R] in the main image configuration).
5666 To add dependencies between subimages, the \f[B]Dependencies=\f[R]
5667 setting can be used as well.
5668 Subimages are always built before the main image.
5669 .PP
5670 When images are defined, \f[B]mkosi\f[R] will first read the main image
5671 configuration (configuration outside of the \f[B]mkosi.images/\f[R]
5672 directory), followed by the image specific configuration.
5673 .PP
5674 Several \[lq]multiversal\[rq] settings apply to the default tools tree
5675 and to the main image and cannot be configured separately outside of the
5676 main image:
5677 .IP \[bu] 2
5678 \f[B]RepositoryKeyCheck=\f[R]
5679 .IP \[bu] 2
5680 \f[B]RepositoryKeyFetch=\f[R]
5681 .IP \[bu] 2
5682 \f[B]SourceDateEpoch=\f[R]
5683 .IP \[bu] 2
5684 \f[B]CacheOnly=\f[R]
5685 .IP \[bu] 2
5686 \f[B]WorkspaceDirectory=\f[R]
5687 .IP \[bu] 2
5688 \f[B]PackageCacheDirectory=\f[R]
5689 .IP \[bu] 2
5690 \f[B]BuildSources=\f[R]
5691 .IP \[bu] 2
5692 \f[B]BuildSourcesEphemeral=\f[R]
5693 .IP \[bu] 2
5694 \f[B]ProxyClientCertificate=\f[R]
5695 .IP \[bu] 2
5696 \f[B]ProxyClientKey=\f[R]
5697 .IP \[bu] 2
5698 \f[B]ProxyExclude=\f[R]
5699 .IP \[bu] 2
5700 \f[B]ProxyPeerCertificate=\f[R]
5701 .IP \[bu] 2
5702 \f[B]ProxyUrl=\f[R]
5703 .PP
5704 Several \[lq]universal\[rq] settings apply to the main image and all its
5705 subimages and cannot be configured separately in subimages.
5706 The following settings are universal and cannot be configured in
5707 subimages:
5708 .IP \[bu] 2
5709 \f[B]Architecture=\f[R]
5710 .IP \[bu] 2
5711 \f[B]BuildDirectory=\f[R]
5712 .IP \[bu] 2
5713 \f[B]CacheDirectory=\f[R]
5714 .IP \[bu] 2
5715 \f[B]Distribution=\f[R]
5716 .IP \[bu] 2
5717 \f[B]ExtraSearchPaths=\f[R]
5718 .IP \[bu] 2
5719 \f[B]Incremental=\f[R]
5720 .IP \[bu] 2
5721 \f[B]LocalMirror=\f[R]
5722 .IP \[bu] 2
5723 \f[B]Mirror=\f[R]
5724 .IP \[bu] 2
5725 \f[B]OutputDirectory=\f[R]
5726 .IP \[bu] 2
5727 \f[B]OutputMode=\f[R]
5728 .IP \[bu] 2
5729 \f[B]PackageDirectories=\f[R]
5730 .IP \[bu] 2
5731 \f[B]Release=\f[R]
5732 .IP \[bu] 2
5733 \f[B]RepartOffline=\f[R]
5734 .IP \[bu] 2
5735 \f[B]Repositories=\f[R]
5736 .IP \[bu] 2
5737 \f[B]SandboxTrees=\f[R]
5738 .IP \[bu] 2
5739 \f[B]ToolsTree=\f[R]
5740 .IP \[bu] 2
5741 \f[B]ToolsTreeCertificates=\f[R]
5742 .IP \[bu] 2
5743 \f[B]UseSubvolumes=\f[R]
5744 .IP \[bu] 2
5745 \f[B]SecureBootCertificate=\f[R]
5746 .IP \[bu] 2
5747 \f[B]SecureBootCertificateSource=\f[R]
5748 .IP \[bu] 2
5749 \f[B]SecureBootKey=\f[R]
5750 .IP \[bu] 2
5751 \f[B]SecureBootKeySource=\f[R]
5752 .IP \[bu] 2
5753 \f[B]VerityCertificate=\f[R]
5754 .IP \[bu] 2
5755 \f[B]VerityCertificateSource=\f[R]
5756 .IP \[bu] 2
5757 \f[B]VerityKey=\f[R]
5758 .IP \[bu] 2
5759 \f[B]VerityKeySource=\f[R]
5760 .IP \[bu] 2
5761 \f[B]VolatilePackageDirectories=\f[R]
5762 .IP \[bu] 2
5763 \f[B]WithNetwork=\f[R]
5764 .IP \[bu] 2
5765 \f[B]WithTests\f[R]
5766 .PP
5767 There are also settings which are passed down to subimages but can be
5768 overridden.
5769 For these settings, values configured explicitly in the subimage will
5770 take priority over values configured on the CLI or in the main image
5771 config.
5772 Currently the following settings are passed down to subimages but can be
5773 overridden:
5774 .IP \[bu] 2
5775 \f[B]Profiles=\f[R]
5776 .IP \[bu] 2
5777 \f[B]ImageId=\f[R]
5778 .IP \[bu] 2
5779 \f[B]ImageVersion=\f[R]
5780 .IP \[bu] 2
5781 \f[B]SectorSize=\f[R]
5782 .IP \[bu] 2
5783 \f[B]CacheKey=\f[R]
5784 .IP \[bu] 2
5785 \f[B]BuildKey=\f[R]
5786 .IP \[bu] 2
5787 \f[B]CompressLevel=\f[R]
5788 .IP \[bu] 2
5789 \f[B]SignExpectedPcrKey=\f[R]
5790 .IP \[bu] 2
5791 \f[B]SignExpectedPcrKeySource=\f[R]
5792 .IP \[bu] 2
5793 \f[B]SignExpectedPcrCertificate=\f[R]
5794 .IP \[bu] 2
5795 \f[B]SignExpectedPcrCertificateSource=\f[R]
5796 .PP
5797 Additionally, there are various settings that can only be configured in
5798 the main image but which are not passed down to subimages:
5799 .IP \[bu] 2
5800 \f[B]MinimumVersion=\f[R]
5801 .IP \[bu] 2
5802 \f[B]PassEnvironment=\f[R]
5803 .IP \[bu] 2
5804 \f[B]ToolsTreeDistribution=\f[R]
5805 .IP \[bu] 2
5806 \f[B]ToolsTreeRelease=\f[R]
5807 .IP \[bu] 2
5808 \f[B]ToolsTreeProfiles=\f[R]
5809 .IP \[bu] 2
5810 \f[B]ToolsTreeMirror=\f[R]
5811 .IP \[bu] 2
5812 \f[B]ToolsTreeRepositories=\f[R]
5813 .IP \[bu] 2
5814 \f[B]ToolsTreeSandboxTrees=\f[R]
5815 .IP \[bu] 2
5816 \f[B]ToolsTreePackages=\f[R]
5817 .IP \[bu] 2
5818 \f[B]ToolsTreePackageDirectories=\f[R]
5819 .IP \[bu] 2
5820 \f[B]History=\f[R]
5821 .IP \[bu] 2
5822 Every setting in the \f[B][Runtime]\f[R] section
5823 .PP
5824 Images can refer to outputs of images they depend on.
5825 Specifically, for the following options, \f[B]mkosi\f[R] will only check
5826 whether the inputs exist just before building the image:
5827 .IP \[bu] 2
5828 \f[B]BaseTrees=\f[R]
5829 .IP \[bu] 2
5830 \f[B]ExtraTrees=\f[R]
5831 .IP \[bu] 2
5832 \f[B]Initrds=\f[R]
5833 .PP
5834 To refer to outputs of a image\[cq]s dependencies, simply configure any
5835 of these options with a relative path to the output to use in the output
5836 directory of the dependency.
5837 Or use the \f[B]%O\f[R] specifier to refer to the output directory.
5838 .PP
5839 A good example on how to build multiple images can be found in the \c
5840 .UR https://github.com/systemd/systemd/tree/main/mkosi/mkosi.images
5841 systemd
5842 .UE \c
5843 \ repository.
5844 .SH ENVIRONMENT VARIABLES
5845 .IP \[bu] 2
5846 \f[B]$MKOSI_LESS\f[R] overrides options for \f[B]less\f[R] when it is
5847 invoked by \f[B]mkosi\f[R] to page output.
5848 .IP \[bu] 2
5849 \f[B]$MKOSI_DNF\f[R] can be used to override the executable used as
5850 \f[B]dnf\f[R].
5851 This is particularly useful to select between \f[B]dnf\f[R] and
5852 \f[B]dnf5\f[R].
5853 .IP \[bu] 2
5854 \f[B]$EPEL_MIRROR\f[R] can be used to override the default mirror
5855 location used for the epel repositories when \f[B]Mirror=\f[R] is used.
5856 By default \f[B]mkosi\f[R] looks for the epel repositories in the
5857 \f[B]fedora\f[R] subdirectory of the parent directory of the mirror
5858 specified in \f[B]Mirror=\f[R].
5859 For example if the mirror is set to
5860 \f[B]https://mirror.net/centos\-stream\f[R] \f[B]mkosi\f[R] will look
5861 for the epel repositories in \f[B]https://mirror.net/fedora/epel\f[R].
5862 .IP \[bu] 2
5863 \f[B]SYSEXT_SCOPE\f[R] and \f[B]CONFEXT_SCOPE\f[R] can be used to
5864 override the default value of the respective
5865 \f[B]extension\-release\f[R] file when building a sysext or confext.
5866 By default the value is set to \f[B]initrd system portable\f[R].
5867 .SH EXAMPLES
5868 Create and run a raw \f[I]GPT\f[R] image with \f[I]ext4\f[R], as
5869 \f[B]image.raw\f[R]:
5870 .IP
5871 .EX
5872 # mkosi \-p systemd \-i boot
5873 .EE
5874 .PP
5875 Create and run a bootable \f[I]GPT\f[R] image, as \f[B]foobar.raw\f[R]:
5876 .IP
5877 .EX
5878 $ mkosi \-d fedora \-p kernel\-core \-p systemd \-p systemd\-boot \-p udev \-o foobar.raw
5879 # mkosi \-\-output foobar.raw boot
5880 $ mkosi \-\-output foobar.raw vm
5881 .EE
5882 .PP
5883 Create and run a \f[I]Fedora Linux\f[R] image in a plain directory:
5884 .IP
5885 .EX
5886 # mkosi \-\-distribution fedora \-\-format directory boot
5887 .EE
5888 .PP
5889 Create a compressed image \f[B]image.raw.xz\f[R] with SSH installed and
5890 add a checksum file:
5891 .IP
5892 .EX
5893 $ mkosi \-\-distribution fedora \-\-format disk \-\-checksum=yes \-\-compress\-output=yes \-\-package=openssh\-clients
5894 .EE
5895 .PP
5896 Inside the source directory of an \f[B]automake\f[R]\-based project,
5897 configure \f[B]mkosi\f[R] so that simply invoking \f[B]mkosi\f[R]
5898 without any parameters builds an OS image containing a built version of
5899 the project in its current state:
5900 .IP
5901 .EX
5902 $ cat >mkosi.conf <<EOF
5903 [Distribution]
5904 Distribution=fedora
5905
5906 [Output]
5907 Format=disk
5908
5909 [Content]
5910 Packages=kernel,systemd,systemd\-udev,openssh\-clients,httpd
5911 BuildPackages=make,gcc,libcurl\-devel
5912 EOF
5913 $ cat >mkosi.build <<EOF
5914 #!/bin/sh
5915
5916 if [ \[dq]$container\[dq] != \[dq]mkosi\[dq] ]; then
5917 exec mkosi\-chroot \[dq]$CHROOT_SCRIPT\[dq] \[dq]$\[at]\[dq]
5918 fi
5919
5920 cd $SRCDIR
5921 \&./autogen.sh
5922 \&./configure \-\-prefix=/usr
5923 make \-j \[ga]nproc\[ga]
5924 make install
5925 EOF
5926 $ chmod +x mkosi.build
5927 # mkosi \-i boot
5928 # systemd\-nspawn \-bi image.raw
5929 .EE
5930 .SS Different ways to boot with \f[B]vm\f[R]
5931 The easiest way to boot a virtual machine is to build an image with the
5932 required components and let \f[B]mkosi\f[R] call \f[B]qemu\f[R] with all
5933 the right options:
5934 .IP
5935 .EX
5936 $ mkosi \-d fedora \-p systemd\-udev,systemd\-boot,kernel\-core build
5937 $ mkosi \-d fedora vm
5938 \&...
5939 fedora login: root (automatic login)
5940 [root\[at]fedora \[ti]]#
5941 .EE
5942 .PP
5943 The default is to boot with a text console only.
5944 In this mode, messages from the boot loader, the kernel, and systemd,
5945 and later the \f[B]getty\f[R] login prompt and shell all use the same
5946 terminal.
5947 It is possible to switch between the \f[B]qemu\f[R] console and monitor
5948 by pressing \f[B]Ctrl\-a c\f[R].
5949 The \f[B]qemu\f[R] monitor may for example be used to inject special
5950 keys or shut down the machine quickly.
5951 Alternatively the machine can be shut down using \f[B]Ctrl\-a x\f[R].
5952 .PP
5953 To boot with a graphical window, add \f[B]\-\-console=gui\f[R]:
5954 .IP
5955 .EX
5956 $ mkosi \-d fedora \-\-console=gui qemu
5957 .EE
5958 .PP
5959 A kernel may be booted directly with \f[B]mkosi vm \-kernel ...
5960 \-initrd ...
5961 \-append \[aq]...\[aq]\f[R].
5962 This is a bit faster because no boot loader is used, and it is also
5963 easier to experiment with different kernels and kernel command lines.
5964 Note that despite the name, \f[B]qemu\f[R]\[cq]s \f[B]\-append\f[R]
5965 option replaces the default kernel command line embedded in the kernel
5966 and any previous \f[B]\-append\f[R] specifications.
5967 .PP
5968 The UKI is also copied into the output directory and may be booted
5969 directly:
5970 .IP
5971 .EX
5972 $ mkosi vm \-\- \-kernel mkosi.output/fedora\[ti]38/image.efi
5973 .EE
5974 .PP
5975 When booting using an external kernel, we don\[cq]t need the kernel
5976 \f[I]in\f[R] the image, but we would still want the kernel modules to be
5977 installed.
5978 .PP
5979 It is also possible to do a \f[I]direct kernel boot\f[R] into a boot
5980 loader, taking advantage of the fact that \f[B]systemd\-boot\f[R](7) is
5981 a valid UEFI binary:
5982 .IP
5983 .EX
5984 $ mkosi vm \-\- \-kernel /usr/lib/systemd/boot/efi/systemd\-bootx64.efi
5985 .EE
5986 .PP
5987 In this scenario, the kernel is loaded from the ESP in the image by
5988 \f[B]systemd\-boot\f[R].
5989 .SH REQUIREMENTS
5990 mkosi is packaged for various distributions: Debian, Kali, Ubuntu, Arch
5991 Linux, Fedora Linux, OpenMandriva, Gentoo, postmarketOS.
5992 Note that it has been a while since the last release and the packages
5993 shipped by distributions are very out of date.
5994 We currently recommend running \f[B]mkosi\f[R] from git until a new
5995 release happens.
5996 .PP
5997 mkosi requires a Linux kernel that provides \f[B]mount_setattr()\f[R]
5998 which was introduces in 5.12.
5999 .PP
6000 mkosi currently requires systemd 254 to build bootable disk images.
6001 .PP
6002 When not using distribution packages make sure to install the necessary
6003 dependencies.
6004 For example, on \f[I]Fedora Linux\f[R] you need:
6005 .IP
6006 .EX
6007 \f[I]# dnf install btrfs\-progs apt dosfstools mtools edk2\-ovmf e2fsprogs squashfs\-tools gnupg python3 tar xfsprogs xz zypper sbsigntools\f[R]
6008 .EE
6009 .PP
6010 On Debian/Kali/Ubuntu it might be necessary to install the
6011 \f[B]ubuntu\-keyring\f[R], \f[B]ubuntu\-archive\-keyring\f[R],
6012 \f[B]kali\-archive\-keyring\f[R] and/or
6013 \f[B]debian\-archive\-keyring\f[R] packages explicitly, in addition to
6014 \f[B]apt\f[R], depending on what kind of distribution images you want to
6015 build.
6016 .PP
6017 Note that the minimum required Python version is 3.9.
6018 .PP
6019 mkosi needs unrestricted abilities to create and act within namespaces.
6020 Some distros restrict creation of, or capabilities within, user
6021 namespaces, which breaks mkosi.
6022 .PP
6023 For information about Ubuntu, that implements such restrictions using
6024 AppArmor, see
6025 https://ubuntu.com/blog/ubuntu\-23\-10\-restricted\-unprivileged\-user\-namespaces.
6026 For other systems, try researching the
6027 \f[B]kernel.unprivileged_userns_clone\f[R] or
6028 \f[B]user.max.user_namespace\f[R] sysctls.
6029 .PP
6030 For Ubuntu systems, you can remove the restrictions for \f[B]mkosi\f[R]
6031 by adapting this snippet to point to your \f[B]mkosi\f[R] binary,
6032 copying it to \f[B]/etc/apparmor.d/resolved.path.to.mkosi\f[R], and then
6033 running \f[B]systemctl reload apparmor\f[R]:
6034 .IP
6035 .EX
6036 abi <abi/4.0>,
6037
6038 include <tunables/global>
6039
6040 /resolved/path/to/mkosi flags=(default_allow) {
6041 userns,
6042 }
6043 .EE
6044 .SH FREQUENTLY ASKED QUESTIONS (FAQ)
6045 .IP \[bu] 2
6046 Why does \f[B]mkosi vm\f[R] with KVM not work on Debian/Kali/Ubuntu?
6047 .RS 2
6048 .PP
6049 While other distributions are OK with allowing access to
6050 \f[B]/dev/kvm\f[R], on Debian/Kali/Ubuntu this is only allowed for users
6051 in the \f[B]kvm\f[R] group.
6052 Because \f[B]mkosi\f[R] unshares a user namespace when running
6053 unprivileged, even if the calling user was in the kvm group, when
6054 \f[B]mkosi\f[R] unshares the user namespace to run unprivileged, it
6055 loses access to the \f[B]kvm\f[R] group and by the time we start
6056 \f[B]qemu\f[R] we don\[cq]t have access to \f[B]/dev/kvm\f[R] anymore.
6057 As a workaround, you can change the permissions of the device nodes to
6058 \f[B]0666\f[R] which is sufficient to make KVM work unprivileged.
6059 To persist these settings across reboots, copy
6060 \f[B]/usr/lib/tmpfiles.d/static\-nodes\-permissions.conf\f[R] to
6061 \f[B]/etc/tmpfiles.d/static\-nodes\-permissions.conf\f[R] and change the
6062 mode of \f[B]/dev/kvm\f[R] from \f[B]0660\f[R] to \f[B]0666\f[R].
6063 .RE
6064 .IP \[bu] 2
6065 How do I add a regular user to an image?
6066 .RS 2
6067 .PP
6068 You can use the following snippet in a post\-installation script:
6069 .IP
6070 .EX
6071 useradd \-\-create\-home \-\-user\-group $USER \-\-password \[dq]$(openssl passwd \-stdin \-6 <$USER_PASSWORD_FILE)\[dq]
6072 .EE
6073 .PP
6074 Note that from systemd v256 onwards, if enabled,
6075 \f[B]systemd\-homed\-firstboot.service\f[R] will prompt to create a
6076 regular user on first boot if there are no regular users.
6077 .RE
6078 .IP \[bu] 2
6079 Why do I see failures to chown files when building images?
6080 .RS 2
6081 .PP
6082 When not running as root, your user is not able to change ownership of
6083 files to arbitrary owners.
6084 Various distributions still ship files in their packages that are not
6085 owned by the root user.
6086 When not running as root, mkosi maps the current user to root when
6087 invoking package managers, which means that changing ownership to root
6088 will work but changing ownership to any other user or group will fail.
6089 .PP
6090 Note that chown calls are only suppressed when running package managers,
6091 but not when running scripts.
6092 If this is required, e.g.\ for a build script, you can set the
6093 \f[B]MKOSI_CHROOT_SUPPRESS_CHOWN\f[R] variable to a true value
6094 (\f[B]1\f[R], \f[B]yes\f[R], \f[B]true\f[R]) to suppress chown calls in
6095 \f[B]mkosi\-chroot\f[R] and \f[B].chroot\f[R] scripts.
6096 .PP
6097 If this behavior causes applications running in your image to misbehave,
6098 you can consider running \f[B]mkosi\f[R] as root which avoids this
6099 problem.
6100 Alternatively, if running \f[B]mkosi\f[R] as root is not desired, you
6101 can use \f[B]unshare \-\-map\-auto \-\-map\-current\-user \-\-setuid 0
6102 \-\-setgid 0\f[R] to become root in a user namespace with more than one
6103 user assuming the UID/GID mappings in \f[B]/etc/subuid\f[R] and
6104 \f[B]/etc/subgid\f[R] are configured correctly.
6105 Note that running mkosi as root or with \f[B]unshare\f[R] means that all
6106 output files produced by \f[B]mkosi\f[R] will not be owned by your
6107 current user anymore.
6108 .PP
6109 Note that for systemd services that need directories in \f[B]/var\f[R]
6110 owned by the service user and group, an alternative to shipping these
6111 directories in packages or creating them via systemd\-tmpfiles is to use
6112 \f[B]StateDirectory=\f[R], \f[B]CacheDirectory=\f[R] or
6113 \f[B]LogsDirectory=\f[R] in the service file which instructs systemd to
6114 create the directory when it first starts the service.
6115 .PP
6116 Alternatively, the \f[B]z\f[R] or \f[B]Z\f[R] directives for
6117 \f[B]systemd\-tmpfiles\f[R] can be used to chown various directories and
6118 files to their owning user when the system first boots up.
6119 .RE
6120 .IP \[bu] 2
6121 Why does \f[B]portablectl inspect <image>\f[R]/\f[B]systemd\-dissect
6122 <image>\f[R] say my portable service isn\[cq]t one?
6123 .RS 2
6124 .PP
6125 \f[B]systemd\-dissect\f[R] and\f[B]portablectl inspect\f[R] check for
6126 \f[B]PORTABLE_PREFIXES=\f[R] in \f[B]os\-release\f[R] and if the key is
6127 missing, will fail to recognise a portable service as one, showing ✗
6128 under \f[I]Use as\f[R] for in the case of \f[B]systemd\-dissect\f[R] or
6129 \f[B]n/a\f[R] under \f[I]Portable Service\f[R] for
6130 \f[B]portablectl\f[R].
6131 .PP
6132 Since there is no good default to set for this key and the generated
6133 portable service images will still attach properly, even when the key is
6134 not set, \f[B]mkosi\f[R] doesn\[cq]t set one.
6135 .PP
6136 You can set \f[B]PORTABLE_PREFIXES=\f[R] in the \f[B]os\-release\f[R]
6137 file yourself in a postinst script.
6138 .RE
6139 .SH REFERENCES
6140 .IP \[bu] 2
6141 \c
6142 .UR https://github.com/systemd/mkosi/
6143 Primary mkosi git repository on GitHub
6144 .UE \c
6145 .IP \[bu] 2
6146 \c
6147 .UR https://0pointer.net/blog/mkosi-a-tool-for-generating-os-images.html
6148 mkosi \[em] A Tool for Generating OS Images
6149 .UE \c
6150 \ introductory blog post by Lennart Poettering
6151 .IP \[bu] 2
6152 \c
6153 .UR https://lwn.net/Articles/726655/
6154 The mkosi OS generation tool
6155 .UE \c
6156 \ story on LWN
6157 .SH SEE ALSO
6158 \f[B]systemd\-nspawn\f[R](1), \f[B]systemd\-repart\f[R](8),
6159 \f[B]dnf\f[R](8)