Debian Codegraph @

upstream/debian-unstable/man1/mkosi.1

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