Debian Codegraph @

upstream/debian-trixie/man1/mkosi.1

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