-.\"t
.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "mkosi" "1" "2016-" "" ""
the result.
.IP \[bu] 2
Optionally, build a local project\[cq]s \f[I]source\f[R] tree in the
-image and add the result to the generated image (see below).
+image and add the result to the generated image.
.IP \[bu] 2
Optionally, share \f[I]RPM\f[R]/\f[I]DEB\f[R] package cache between
multiple runs, in order to optimize build speeds.
By default images are created without all files marked as documentation
in the packages, on distributions where the package manager supports
this.
-Use the \f[C]--with-docs\f[R] flag to build an image with docs added.
+Use the \f[C]WithDocs=yes\f[R] flag to build an image with docs added.
.SS Command Line Verbs
.PP
The following command line verbs are known:
.TP
\f[B]\f[CB]build\f[B]\f[R]
This builds the image, based on the settings passed in on the command
-line or read from a \f[C]mkosi.default\f[R] file, see below.
+line or read from a \f[C]mkosi.default\f[R] file.
This verb is the default if no verb is explicitly specified.
This command must be executed as \f[C]root\f[R].
Any arguments passed after \f[C]build\f[R] are passed as arguments to
Similar to \f[C]boot\f[R] but uses \f[C]qemu\f[R] to boot up the image,
i.e.\ instead of container virtualization VM virtualization is used.
This verb is only supported on images that contain a boot loader,
-i.e.\ those built with \f[C]--bootable\f[R] (see below).
+i.e.\ those built with \f[C]Bootable=yes\f[R] (see below).
This command must be executed as \f[C]root\f[R] unless the image already
exists and \f[C]-f\f[R] is not specified.
.TP
\f[B]\f[CB]ssh\f[B]\f[R]
-When the image is built with the \f[C]--ssh\f[R] option, this command
+When the image is built with the \f[C]Ssh=yes\f[R] option, this command
connects to a booted (\f[C]boot\f[R], \f[C]qemu\f[R] verbs) container/VM
via SSH.
Make sure to run \f[C]mkosi ssh\f[R] with the same config as
.TP
\f[B]\f[CB]bump\f[B]\f[R]
Determines the current image version string (as configured with
-\f[C]--image-version=\f[R]/\f[C]ImageVersion=\f[R]), increases its last
+\f[C]ImageVersion=\f[R]/\f[C]--image-version=\f[R]), increases its last
dot-separated component by one and writes the resulting version string
to \f[C]mkosi.version\f[R].
This is useful for implementing a simple versioning scheme: each time
. .
\f[R]
.fi
-.SS Command Line Parameters
+.SS Configuration Settings
.PP
-The following command line parameters are understood.
-Note that many of these parameters can also be set in the
-\f[C]mkosi.default\f[R] file, for details see the table below.
-.TP
-\f[B]\f[CB]--distribution=\f[B]\f[R], \f[B]\f[CB]-d\f[B]\f[R]
+The following settings can be set through configuration files (the
+syntax with \f[C]SomeSetting=value\f[R]) and on the command line (the
+syntax with \f[C]--some-setting=value\f[R]).
+For some command line parameters, a single-letter shortcut is also
+allowed.
+In the configuration files, the setting must be in the appropriate
+section, so the settings are grouped by section below.
+.PP
+Command line options that take no argument are shown without \[lq]=\[rq]
+in their long version.
+In the config files, they should be specified with a boolean argument:
+either \[lq]1\[rq], \[lq]yes\[rq], or \[lq]true\[rq] to enable, or
+\[lq]0\[rq], \[lq]no\[rq], \[lq]false\[rq] to disable.
+.SS [Distribution] Section
+.TP
+\f[B]\f[CB]Distribution=\f[B]\f[R], \f[B]\f[CB]--distribution=\f[B]\f[R], \f[B]\f[CB]-d\f[B]\f[R]
The distribution to install in the image.
Takes one of the following arguments: \f[C]fedora\f[R],
\f[C]debian\f[R], \f[C]ubuntu\f[R], \f[C]arch\f[R], \f[C]opensuse\f[R],
\f[C]openmandriva\f[R].
If not specified, defaults to the distribution of the host.
.TP
-\f[B]\f[CB]--release=\f[B]\f[R], \f[B]\f[CB]-r\f[B]\f[R]
+\f[B]\f[CB]Release=\f[B]\f[R], \f[B]\f[CB]--release=\f[B]\f[R], \f[B]\f[CB]-r\f[B]\f[R]
The release of the distribution to install in the image.
The precise syntax of the argument this takes depends on the
distribution used, and is either a numeric string (in case of Fedora
Linux, CentOS, \&..., e.g.\ \f[C]29\f[R]), or a distribution version
name (in case of Debian, Ubuntu, \&..., e.g.\ \f[C]artful\f[R]).
-If neither this option, not \f[C]--distribution=\f[R] is specified,
+If neither this option, nor \f[C]Distribution=\f[R] is specified,
defaults to the distribution version of the host.
If the distribution is specified, defaults to a recent version of it.
.TP
-\f[B]\f[CB]--mirror=\f[B]\f[R], \f[B]\f[CB]-m\f[B]\f[R]
+\f[B]\f[CB]Mirror=\f[B]\f[R], \f[B]\f[CB]--mirror=\f[B]\f[R], \f[B]\f[CB]-m\f[B]\f[R]
The mirror to use for downloading the distribution packages.
Expects a mirror URL as argument.
.TP
-\f[B]\f[CB]--repositories=\f[B]\f[R]
+\f[B]\f[CB]Repositories=\f[B]\f[R], \f[B]\f[CB]--repositories=\f[B]\f[R]
Additional package repositories to use during installation.
Expects one or more URLs as argument, separated by commas.
This option may be used multiple times, in which case the list of
For Arch Linux, additional repositories must be passed in the form
\f[C]<name>::<url>\f[R] (e.g.\ \f[C]myrepo::https://myrepo.net\f[R]).
.TP
-\f[B]\f[CB]--architecture=\f[B]\f[R]
+\f[B]\f[CB]Architecture=\f[B]\f[R], \f[B]\f[CB]--architecture=\f[B]\f[R]
The architecture to build the image for.
Note that this currently only works for architectures compatible with
the host\[cq]s architecture.
+.SS [Output] Section
.TP
-\f[B]\f[CB]--format=\f[B]\f[R], \f[B]\f[CB]-t\f[B]\f[R]
+\f[B]\f[CB]Format=\f[B]\f[R], \f[B]\f[CB]--format=\f[B]\f[R], \f[B]\f[CB]-t\f[B]\f[R]
The image format type to generate.
One of \f[C]directory\f[R] (for generating OS images inside a local
directory), \f[C]subvolume\f[R] (similar, but as a btrfs subvolume),
\f[C]plain_squashfs\f[R] (a plain squashfs file system without a
partition table).
.TP
-\f[B]\f[CB]--manifest-format=\f[B]\f[R]
+\f[B]\f[CB]ManifestFormat=\f[B]\f[R], \f[B]\f[CB]--manifest-format=\f[B]\f[R]
The manifest format type or types to generate.
A comma-delimited list consisting of \f[C]json\f[R] (the standard JSON
output format that describes the packages installed),
\f[C]changelog\f[R] (a human-readable text format designed for diffing).
Defaults to \f[C]json\f[R].
.TP
-\f[B]\f[CB]--output=\f[B]\f[R], \f[B]\f[CB]-o\f[B]\f[R]
+\f[B]\f[CB]Output=\f[B]\f[R], \f[B]\f[CB]--output=\f[B]\f[R], \f[B]\f[CB]-o\f[B]\f[R]
Path for the output image file to generate.
Takes a relative or absolute path where the generated image will be
placed.
-If neither this option nor \f[C]--output-dir=\f[R] is used (see below),
-the image is generated under the name \f[C]image\f[R], but its name
-suffixed with an appropriate file suffix (e.g.\ \f[C]image.raw.xz\f[R]
-in case \f[C]gpt_ext4\f[R] is used in combination with \f[C]xz\f[R]
+If neither this option nor \f[C]OutputDirectory=\f[R] is used, the image
+is generated under the name \f[C]image\f[R], but its name suffixed with
+an appropriate file suffix (e.g.\ \f[C]image.raw.xz\f[R] in case
+\f[C]gpt_ext4\f[R] is used in combination with \f[C]xz\f[R]
compression).
-If the \f[C]--image-id=\f[R] option is configured it is used instead of
+If the \f[C]ImageId=\f[R] option is configured it is used instead of
\f[C]image\f[R] in the default output name.
-If an image version is specified (via
-\f[C]--image-version=\f[R]/\f[C]ImageVersion=\f[R]) it is included in
-the default name, e.g.\ a specified image version of \f[C]7.8\f[R] might
-result in an image file name of \f[C]image_7.8.raw.xz\f[R].
-.TP
-\f[B]\f[CB]--output-split-root=\f[B]\f[R], \f[B]\f[CB]--output-split-verity=\f[B]\f[R], \f[B]\f[CB]--output-split-kernel=\f[B]\f[R]
-Path for the split-out output image files to generate, if the
-\f[C]--split-artifacts\f[R] option is used (see below).
-If unspecified the relevant split artifact files will be named like the
-main image, but a \f[C].root\f[R], \f[C].verity\f[R], \f[C].efi\f[R]
-suffix is inserted (which is possibly in turn suffixed by \f[C].xz\f[R],
-if that is enabled).
-.TP
-\f[B]\f[CB]--output-dir=\f[B]\f[R], \f[B]\f[CB]-O\f[B]\f[R]
+If an image version is specified via \f[C]ImageVersion=\f[R], it is
+included in the default name, e.g.\ a specified image version of
+\f[C]7.8\f[R] might result in an image file name of
+\f[C]image_7.8.raw.xz\f[R].
+.TP
+\f[B]\f[CB]OutputSplitRoot=\f[B]\f[R], \f[B]\f[CB]--output-split-root=\f[B]\f[R], \f[B]\f[CB]OutputSplitVerify=\f[B]\f[R], \f[B]\f[CB]--output-split-verity=\f[B]\f[R], \f[B]\f[CB]OutputSplitKernel=\f[B]\f[R], \f[B]\f[CB]--output-split-kernel=\f[B]\f[R]
+Paths for the split-out output image files, when
+\f[C]SplitArtifacts=yes\f[R] is used.
+If unspecified, the relevant split artifact files will be named like the
+main image, but with \f[C].root\f[R], \f[C].verity\f[R], and
+\f[C].efi\f[R] suffixes inserted (and in turn possibly suffixed by
+compression suffix, if compression is enabled).
+.TP
+\f[B]\f[CB]OutputDirectory=\f[B]\f[R], \f[B]\f[CB]--output-dir=\f[B]\f[R], \f[B]\f[CB]-O\f[B]\f[R]
Path to a directory where to place all generated artifacts (i.e.\ the
-\f[C]SHA256SUMS\f[R] file and similar).
-If this is not specified and a directory \f[C]mkosi.output/\f[R] exists
-in the local directory it is automatically used for this purpose.
-If this is not specified and such a directory does not exist, all output
-artifacts are placed adjacent to the output image file.
-.TP
-\f[B]\f[CB]--workspace-dir=\f[B]\f[R]
+generated image when an output path is not given, \f[C]SHA256SUMS\f[R]
+file, etc.).
+If this is not specified and the directory \f[C]mkosi.output/\f[R]
+exists in the local directory, it is automatically used for this
+purpose.
+If the setting is not used and \f[C]mkosi.output/\f[R] does not exist,
+all output artifacts are placed adjacent to the output image file.
+.TP
+\f[B]\f[CB]WorkspaceDirectory=\f[B]\f[R], \f[B]\f[CB]--workspace-dir=\f[B]\f[R]
Path to a directory where to store data required temporarily while
building the image.
-This directory should have enough space to store a full OS image, though
-in most modes the actually used disk space is smaller.
-If not specified, and \f[C]mkosi.workspace/\f[R] exists, it is used for
-this purpose.
-If it doesn\[cq]t exist and \f[C]$TMPDIR\f[R] is set, the specified
-directory is used.
-If that\[cq]s not set either, \f[C]/var/tmp/\f[R] is used.
-The data in the directory is removed automatically after each build.
-It\[cq]s safe to manually remove the contents of this directories should
+This directory should have enough space to store the full OS image,
+though in most modes the actually used disk space is smaller.
+If not specified, and \f[C]mkosi.workspace/\f[R] exists in the local
+directory, it is used for this purpose.
+Otherwise, a subdirectory in the temporary storage area is used
+(\f[C]$TMPDIR\f[R] if set, \f[C]/var/tmp/\f[R] otherwise).
+The data in this directory is removed automatically after each build.
+It\[cq]s safe to manually remove the contents of this directory should
an \f[C]mkosi\f[R] invocation be aborted abnormally (for example, due to
reboot/power failure).
If the \f[C]btrfs\f[R] output modes are selected this directory must be
backed by \f[C]btrfs\f[R] too.
.TP
-\f[B]\f[CB]--force\f[B]\f[R], \f[B]\f[CB]-f\f[B]\f[R]
+\f[B]\f[CB]Force=\f[B]\f[R], \f[B]\f[CB]--force\f[B]\f[R], \f[B]\f[CB]-f\f[B]\f[R]
Replace the output file if it already exists, when building an image.
By default when building an image and an output artifact already exists
\f[C]mkosi\f[R] will refuse operation.
-Specify \f[C]-f\f[R] to delete all build artifacts from a previous run
-before re-building the image.
-If incremental builds are enabled (see below), specifying this option
-twice will ensure the intermediary cache files are removed, too, before
-the re-build is initiated.
-If a package cache is used (see below), specifying this option thrice
-will ensure the package cache is removed too, before the re-build is
-initiated.
-For the \f[C]clean\f[R] operation \f[C]-f\f[R] has a slightly different
+Specify this option once to delete all build artifacts from a previous
+run before re-building the image.
+If incremental builds are enabled, specifying this option twice will
+ensure the intermediary cache files are removed, too, before the
+re-build is initiated.
+If a package cache is used (also see the \[lq]Files\[rq] section below),
+specifying this option thrice will ensure the package cache is removed
+too, before the re-build is initiated.
+For the \f[C]clean\f[R] operation this option has a slightly different
effect: by default the verb will only remove build artifacts from a
previous run, when specified once the incremental cache files are
deleted too, and when specified twice the package cache is also removed.
+.PP
.TP
-\f[B]\f[CB]--gpt-first-lba\f[B]\f[R]
+\f[B]\f[CB]GPTFirstLBA=\f[B]\f[R], \f[B]\f[CB]--gpt-first-lba=\f[B]\f[R]
Override the first usable LBA (Logical Block Address) within the GPT
header.
-This defaults to \f[C]2048\f[R] which is actually the desired value.
+This defaults to \f[C]2048\f[R], which is actually the desired value.
However, some tools, e.g.\ the \f[C]prl_disk_tool\f[R] utility from the
Parallels virtualization suite require this to be set to \f[C]34\f[R],
otherwise they might fail to resize the disk image and/or partitions
inside it.
.TP
-\f[B]\f[CB]--bootable\f[B]\f[R], \f[B]\f[CB]-b\f[B]\f[R]
+\f[B]\f[CB]Bootable=\f[B]\f[R], \f[B]\f[CB]--bootable\f[B]\f[R], \f[B]\f[CB]-b\f[B]\f[R]
Generate a bootable image.
By default this will generate an image bootable on UEFI systems.
-Use \f[C]--boot-protocols=\f[R] to select support for a different boot
+Use \f[C]BootProtocols=\f[R] to select support for a different boot
protocol.
.TP
-\f[B]\f[CB]--boot-protocols=\f[B]\f[R]
+\f[B]\f[CB]BootProtocols=\f[B]\f[R], \f[B]\f[CB]--boot-protocols=\f[B]\f[R]
Pick one or more boot protocols to support when generating a bootable
-image, as enabled with \f[C]--bootable\f[R] above.
+image, as enabled with \f[C]Bootable=\f[R].
Takes a comma-separated list of \f[C]uefi\f[R] or \f[C]bios\f[R].
May be specified more than once in which case the specified lists are
merged.
Use \[lq]!*\[rq] to remove all previously added protocols or
\[lq]!protocol\[rq] to remove one protocol.
.TP
-\f[B]\f[CB]--kernel-command-line=\f[B]\f[R]
+\f[B]\f[CB]KernelCommandLine=\f[B]\f[R], \f[B]\f[CB]--kernel-command-line=\f[B]\f[R]
Use the specified kernel command line when building bootable images.
By default command line arguments get appended.
To remove all arguments from the current list pass \[lq]!*\[rq].
\[lq]console=ttyS0 rw\[rq] to the kernel in any case.
Just adding \[lq]console=ttyS0 rw\[rq] would append these two arguments
to the kernel command line created by lower priority configuration files
-or previous \f[C]--kernel-command-line\f[R] command line arguments.
+or previous \f[C]KernelCommandLine=\f[R] command line arguments.
.TP
-\f[B]\f[CB]--secure-boot\f[B]\f[R]
-Sign the resulting kernel/initrd image for UEFI SecureBoot
+\f[B]\f[CB]SecureBoot=\f[B]\f[R], \f[B]\f[CB]--secure-boot\f[B]\f[R]
+Sign the resulting kernel/initrd image for UEFI SecureBoot.
.TP
-\f[B]\f[CB]--secure-boot-key=\f[B]\f[R]
+\f[B]\f[CB]SecureBootKey=\f[B]\f[R], \f[B]\f[CB]--secure-boot-key=\f[B]\f[R]
Path to the PEM file containing the secret key for signing the UEFI
-kernel image, if \f[C]--secure-boot\f[R] is used.
+kernel image, if \f[C]SecureBoot=\f[R] is used.
.TP
-\f[B]\f[CB]--secure-boot-certificate=\f[B]\f[R]
+\f[B]\f[CB]SecureBootCertificate=\f[B]\f[R], \f[B]\f[CB]--secure-boot-certificate=\f[B]\f[R]
Path to the X.509 file containing the certificate for the signed UEFI
-kernel image, if \f[C]--secure-boot\f[R] is used.
+kernel image, if \f[C]SecureBoot=\f[R] is used.
.TP
-\f[B]\f[CB]--secure-boot-common-name=\f[B]\f[R]
+\f[B]\f[CB]SecureBootCommonName=\f[B]\f[R], \f[B]\f[CB]--secure-boot-common-name=\f[B]\f[R]
Common name to be used when generating SecureBoot keys via mkosi\[cq]s
\f[C]genkey\f[R] command.
Defaults to \f[C]mkosi of %u\f[R], where \f[C]%u\f[R] expands to the
username of the user invoking mkosi.
.TP
-\f[B]\f[CB]--secure-boot-valid-days=\f[B]\f[R]
+\f[B]\f[CB]SecureBootValidDays=\f[B]\f[R], \f[B]\f[CB]--secure-boot-valid-days=\f[B]\f[R]
Number of days that the keys should remain valid when generating
SecureBoot keys via mkosi\[cq]s \f[C]genkey\f[R] command.
Defaults to two years (730 days).
.TP
-\f[B]\f[CB]--read-only\f[B]\f[R]
+\f[B]\f[CB]ReadOnly=\f[B]\f[R], \f[B]\f[CB]--read-only\f[B]\f[R]
Make root file system read-only.
Only applies to \f[C]gpt_ext4\f[R], \f[C]gpt_xfs\f[R],
-\f[C]gpt_btrfs\f[R], \f[C]subvolume\f[R] output formats, and implied on
-\f[C]gpt_squashfs\f[R] and \f[C]plain_squashfs\f[R].
+\f[C]gpt_btrfs\f[R], \f[C]subvolume\f[R] output formats, and is implied
+on \f[C]gpt_squashfs\f[R] and \f[C]plain_squashfs\f[R].
.TP
-\f[B]\f[CB]--minimize\f[B]\f[R]
+\f[B]\f[CB]Minimize=\f[B]\f[R], \f[B]\f[CB]--minimize\f[B]\f[R]
Attempt to make the resulting root file system as small as possible by
removing free space from the file system.
Only supported for \f[C]gpt_ext4\f[R] and \f[C]gpt_btrfs\f[R].
disk space but is not perfect and generally leaves some free space.
For btrfs the results are optimal and no free space is left.
.TP
-\f[B]\f[CB]--encrypt\f[B]\f[R]
+\f[B]\f[CB]Encrypt=\f[B]\f[R], \f[B]\f[CB]--encrypt\f[B]\f[R]
Encrypt all partitions in the file system or just the root file system.
Takes either \f[C]all\f[R] or \f[C]data\f[R] as argument.
-If \f[C]all\f[R] the root, \f[C]/home\f[R] and \f[C]/srv\f[R] file
+If \f[C]all\f[R], the root, \f[C]/home\f[R] and \f[C]/srv\f[R] file
systems will be encrypted using dm-crypt/LUKS (with its default
settings).
-If \f[C]data\f[R] the root file system will be left unencrypted, but
+If \f[C]data\f[R], the root file system will be left unencrypted, but
\f[C]/home\f[R] and \f[C]/srv\f[R] will be encrypted.
The passphrase to use is read from the \f[C]mkosi.passphrase\f[R] file
-in the current working directory (see below).
+in the current working directory.
Note that the UEFI System Partition (ESP) containing the boot loader and
kernel to boot is never encrypted since it needs to be accessible by the
firmware.
.TP
-\f[B]\f[CB]--verity\f[B]\f[R]
+\f[B]\f[CB]Verity=\f[B]\f[R], \f[B]\f[CB]--verity\f[B]\f[R]
Add an \[lq]Verity\[rq] integrity partition to the image.
If enabled, the root partition is protected with \f[C]dm-verity\f[R]
against off-line modification, the verification data is placed in an
additional GPT partition.
-Implies \f[C]--read-only\f[R].
+Implies \f[C]ReadOnly=yes\f[R].
.TP
-\f[B]\f[CB]--compress-fs=\f[B]\f[R]
+\f[B]\f[CB]CompressFs=\f[B]\f[R], \f[B]\f[CB]--compress-fs=\f[B]\f[R]
Enable or disable internal compression in the file system.
Only applies to output formats with squashfs or btrfs.
Takes one of \f[C]zlib\f[R], \f[C]lzo\f[R], \f[C]zstd\f[R],
In case of the \f[C]squashfs\f[R] output formats compression is implied,
but this option may be used to select the algorithm.
.TP
-\f[B]\f[CB]--compress-output=\f[B]\f[R]
+\f[B]\f[CB]CompressOutput=\f[B]\f[R], \f[B]\f[CB]--compress-output=\f[B]\f[R]
Configure compression for the resulting image or archive.
The argument can be either a boolean or a compression algorithm
(\f[C]xz\f[R], \f[C]zstd\f[R]).
verbs are not available when this option is used.
Implied for \f[C]tar\f[R] and \f[C]cpio\f[R].
.TP
-\f[B]\f[CB]--compress=\f[B]\f[R]
+\f[B]\f[CB]Compress=\f[B]\f[R], \f[B]\f[CB]--compress=\f[B]\f[R]
Enable compression.
-Using this option is equivalent to either \f[C]--compress-fs=\f[R] or
-\f[C]--compress-output=\f[R]; the appropriate type of compression is
+Using this option is equivalent to either \f[C]CompressFs=\f[R] or
+\f[C]CompressOutput=\f[R]; the appropriate type of compression is
selected automatically.
.TP
-\f[B]\f[CB]--mksquashfs=\f[B]\f[R]
+\f[B]\f[CB]Mksquashfs=\f[B]\f[R], \f[B]\f[CB]--mksquashfs=\f[B]\f[R]
Set the path to the \f[C]mksquashfs\f[R] executable to use.
This is useful in case the parameters for the tool shall be augmented,
as the tool may be replaced by a script invoking it with the right
parameters, this way.
.TP
-\f[B]\f[CB]--qcow2\f[B]\f[R]
+\f[B]\f[CB]QCow2=\f[B]\f[R], \f[B]\f[CB]--qcow2\f[B]\f[R]
Encode the resulting image as QEMU QCOW2 image.
This only applies to \f[C]gpt_ext4\f[R], \f[C]gpt_xfs\f[R],
\f[C]gpt_btrfs\f[R], \f[C]gpt_squashfs\f[R].
This means the \f[C]shell\f[R] and \f[C]boot\f[R] verbs are not
available when this option is used, however \f[C]qemu\f[R] will work.
.TP
-\f[B]\f[CB]--hostname=\f[B]\f[R]
+\f[B]\f[CB]Hostname=\f[B]\f[R], \f[B]\f[CB]--hostname=\f[B]\f[R]
Set the image\[cq]s hostname to the specified name.
.TP
-\f[B]\f[CB]--image-version=\f[B]\f[R]
+\f[B]\f[CB]ImageVersion=\f[B]\f[R], \f[B]\f[CB]--image-version=\f[B]\f[R]
Configure the image version.
This accepts any string, but it is recommended to specify a series of
dot separated components.
\f[C]/etc/os-release\f[R] or similar, in particular the
\f[C]IMAGE_VERSION=\f[R] field of it).
.TP
-\f[B]\f[CB]--image-id=\f[B]\f[R]
+\f[B]\f[CB]ImageId=\f[B]\f[R], \f[B]\f[CB]--image-id=\f[B]\f[R]
Configure the image identifier.
This accepts a freeform string that shall be used to identify the image
with.
\f[C]/etc/os-release\f[R] or similar, in particular the
\f[C]IMAGE_ID=\f[R] field of it).
.TP
-\f[B]\f[CB]--without-unified-kernel-images\f[B]\f[R]
+\f[B]\f[CB]WithUnifiedKernelImages=\f[B]\f[R], \f[B]\f[CB]--without-unified-kernel-images\f[B]\f[R]
If specified, mkosi does not build unified kernel images and instead
installs kernels with a separate initrd and boot loader config to the
efi or bootloader partition.
.TP
-\f[B]\f[CB]--hostonly-initrd\f[B]\f[R]
+\f[B]\f[CB]HostonlyInitrd=\f[B]\f[R], \f[B]\f[CB]--hostonly-initrd\f[B]\f[R]
If specified, mkosi will run the tool to create the initrd such that a
non-generic initrd is created that will only be able to run on the
system mkosi is run on.
Linux and this option translates to enabling dracut\[cq]s hostonly
option.
.TP
-\f[B]\f[CB]--usr-only\f[B]\f[R]
+\f[B]\f[CB]UsrOnly=\f[B]\f[R], \f[B]\f[CB]--usr-only\f[B]\f[R]
If specified, \f[C]mkosi\f[R] will only add the \f[C]/usr/\f[R]
directory tree (instead of the whole root file system) to the image.
This is useful for fully stateless systems that come up pristine on
file system, but where \f[C]systemd-repart\f[R] adds one on the first
boot.
.TP
-\f[B]\f[CB]--split-artifacts\f[B]\f[R]
+\f[B]\f[CB]SplitArtifacts=\f[B]\f[R], \f[B]\f[CB]--split-artifacts\f[B]\f[R]
If specified and building an image with a partition table, also write
out the root file system partition, its Verity partition (if configured)
and the generated unified kernel (if configured) into separate output
shall be augmented with a new version of a root or \f[C]/usr\f[R]
partition along with its Verity partition and unified kernel.
.TP
-\f[B]\f[CB]--no-chown\f[B]\f[R]
+\f[B]\f[CB]NoChown=\f[B]\f[R], \f[B]\f[CB]--no-chown\f[B]\f[R]
By default, if \f[C]mkosi\f[R] is run inside a \f[C]sudo\f[R]
environment all generated artifacts have their UNIX user/group ownership
changed to the user which invoked \f[C]sudo\f[R].
With this option this may be turned off and all generated files are
owned by \f[C]root\f[R].
.TP
-\f[B]\f[CB]--tar-strip-selinux-context\f[B]\f[R]
+\f[B]\f[CB]TarStripSELinuxContext=\f[B]\f[R], \f[B]\f[CB]--tar-strip-selinux-context\f[B]\f[R]
If running on a SELinux-enabled system (Fedora Linux, CentOS), files
inside the container are tagged with SELinux context extended attributes
(\f[C]xattrs\f[R]), which may interfere with host SELinux rules in
building or further container import stages.
This option strips SELinux context attributes from the resulting tar
archive.
+.SS [Content] Section
.TP
-\f[B]\f[CB]--incremental\f[B]\f[R], \f[B]\f[CB]-i\f[B]\f[R]
-Enable incremental build mode.
-This only applies if the two-phase \f[C]mkosi.build\f[R] build script
-logic is used.
-In this mode, a copy of the OS image is created immediately after all OS
-packages are unpacked but before the \f[C]mkosi.build\f[R] script is
-invoked in the development container.
-Similarly, a copy of the final image is created immediately before the
-build artifacts from the \f[C]mkosi.build\f[R] script are copied in.
-On subsequent invocations of \f[C]mkosi\f[R] with the \f[C]-i\f[R]
-switch these cached images may be used to skip the OS package unpacking,
-thus drastically speeding up repetitive build times.
-Note that when this is used and a pair of cached incremental images
-exists they are not automatically regenerated, even if options such as
-\f[C]--packages=\f[R] are modified.
-In order to force rebuilding of these cached images, combine
-\f[C]-i\f[R] with \f[C]-ff\f[R] to ensure cached images are first
-removed and then re-created.
-.TP
-\f[B]\f[CB]--base-packages\f[B]\f[R]
+\f[B]\f[CB]BasePackages=\f[B]\f[R], \f[B]\f[CB]--base-packages\f[B]\f[R]
+Takes a boolean or the special value \f[C]conditional\f[R].
If true, automatically install packages to ensure basic functionality,
as appropriate for the given image type.
For example, \f[C]systemd\f[R] is always included,
\f[C]systemd-udev\f[R] and \f[C]dracut\f[R] if the image is bootable,
and so on.
-If false, only packages specified with
-\f[C]--package\f[R]/\f[C]Packages\f[R] will be installed.
+If false, only packages specified with \f[C]Packages=\f[R] will be
+installed.
If \f[C]conditional\f[R], the list of packages to install will be
extended with boolean dependencies (c.f.
https://rpm.org/user_doc/boolean_dependencies.html), to install specific
This feature depends on support in the package manager, so it is not
implemented for all distributions.
.TP
-\f[B]\f[CB]--package=\f[B]\f[R], \f[B]\f[CB]-p\f[B]\f[R]
+\f[B]\f[CB]Packages=\f[B]\f[R], \f[B]\f[CB]--package=\f[B]\f[R], \f[B]\f[CB]-p\f[B]\f[R]
Install the specified distribution packages (i.e.\ RPM, DEB, \&...) in
the image.
Takes a comma separated list of packages.
This option may be used multiple times in which case the specified
-package list is combined.
+package lists are combined.
Packages specified this way will be installed both in the development
-and the final image (see below).
-Use \f[C]--build-package=\f[R] (see below) to specify packages that
-shall only be used for the image generated in the build image, but that
-shall not appear in the final image.
+and the final image.
+Use \f[C]BuildPackages=\f[R] to specify packages that shall only be used
+for the image generated in the build image, but that shall not appear in
+the final image.
To remove a package e.g.\ added by a \f[C]mkosi.default\f[R]
-configuration file prepend the package name with a ! letter.
+configuration file prepend the package name with \f[C]!\f[R].
For example -p \[lq]!apache2\[rq] would remove the apache2 package.
To replace the apache2 package by the httpd package just add -p
\[lq]!apache2,httpd\[rq] to the command line arguments.
To remove all packages use \[lq]!*\[rq].
.TP
-\f[B]\f[CB]--with-docs\f[B]\f[R]
+\f[B]\f[CB]WithDocs=\f[B]\f[R], \f[B]\f[CB]--with-docs\f[B]\f[R]
Include documentation in the image built.
By default if the underlying distribution package manager supports it
documentation is not included in the image built.
The \f[C]$WITH_DOCS\f[R] environment variable passed to the
\f[C]mkosi.build\f[R] script indicates whether this option was used or
-not, see below.
+not.
.TP
-\f[B]\f[CB]--without-tests\f[B]\f[R], \f[B]\f[CB]-T\f[B]\f[R]
-If set the \f[C]$WITH_TESTS\f[R] environment variable is set to
-\f[C]0\f[R] when the \f[C]mkosi.build\f[R] script is invoked.
+\f[B]\f[CB]WithTests=\f[B]\f[R], \f[B]\f[CB]--without-tests\f[B]\f[R], \f[B]\f[CB]-T\f[B]\f[R]
+If set to false (or when the command-line option is used), the
+\f[C]$WITH_TESTS\f[R] environment variable is set to \f[C]0\f[R] when
+the \f[C]mkosi.build\f[R] script is invoked.
This is supposed to be used by the build script to bypass any unit or
integration tests that are normally run during the source build process.
Note that this option has no effect unless the \f[C]mkosi.build\f[R]
build script honors it.
.TP
-\f[B]\f[CB]--cache=\f[B]\f[R]
+\f[B]\f[CB]Cache=\f[B]\f[R], \f[B]\f[CB]--cache=\f[B]\f[R]
Takes a path to a directory to use as package cache for the distribution
package manager used.
If this option is not used, but a \f[C]mkosi.cache/\f[R] directory is
-found in the local directory it is automatically used for this purpose
-(also see below).
+found in the local directory it is automatically used for this purpose.
The directory configured this way is mounted into both the development
and the final image while the package manager is running.
.TP
-\f[B]\f[CB]--extra-tree=\f[B]\f[R]
-Takes a path to a directory to copy on top of the OS tree the package
-manager generated.
-Use this to override any default configuration files shipped with the
-distribution.
-If this option is not used, but the \f[C]mkosi.extra/\f[R] directory is
-found in the local directory it is automatically used for this purpose
-(also see below).
-Instead of a directory a \f[C]tar\f[R] file may be specified too.
-In this case it is unpacked into the OS tree before the package manager
-is invoked.
-This mode of operation allows setting permissions and file ownership
-explicitly, in particular for projects stored in a version control
-system such as \f[C]git\f[R] which does retain full file ownership and
-access mode metadata for committed files.
-If a tar file \f[C]mkosi.extra.tar\f[R] is found in the local directory
-it automatically used for this purpose.
-.TP
-\f[B]\f[CB]--skeleton-tree=\f[B]\f[R]
+\f[B]\f[CB]SkeletonTree=\f[B]\f[R], \f[B]\f[CB]--skeleton-tree=\f[B]\f[R]
Takes a path to a directory to copy into the OS tree before invoking the
package manager.
Use this to insert files and directories into the OS tree before the
package manager installs any packages.
If this option is not used, but the \f[C]mkosi.skeleton/\f[R] directory
is found in the local directory it is automatically used for this
-purpose (also see below).
-As with the extra tree logic above, instead of a directory a
-\f[C]tar\f[R] file may be used too, and \f[C]mkosi.skeleton.tar\f[R] is
-automatically used.
+purpose (also see the \[lq]Files\[rq] section below).
+Instead of a directory, a tar file may be provided.
+In this case it is unpacked into the OS tree before the package manager
+is invoked.
+This mode of operation allows setting permissions and file ownership
+explicitly, in particular for projects stored in a version control
+system such as \f[C]git\f[R] which retain full file ownership and access
+mode metadata for committed files.
+If the tar file \f[C]mkosi.skeleton.tar\f[R] is found in the local
+directory it will be automatically used for this purpose.
+.TP
+\f[B]\f[CB]ExtraTree=\f[B]\f[R], \f[B]\f[CB]--extra-tree=\f[B]\f[R]
+Takes a path to a directory to copy on top of the OS tree the package
+manager generated.
+Use this to override any default configuration files shipped with the
+distribution.
+If this option is not used, but the \f[C]mkosi.extra/\f[R] directory is
+found in the local directory it is automatically used for this purpose
+(also see the \[lq]Files\[rq] section below).
+As with the skeleton tree logic above, instead of a directory, a tar
+file may be provided too.
+\f[C]mkosi.skeleton.tar\f[R] will be automatically used if found in the
+local directory.
.TP
-\f[B]\f[CB]--remove-files=\f[B]\f[R]
+\f[B]\f[CB]RemoveFiles=\f[B]\f[R], \f[B]\f[CB]--remove-files=\f[B]\f[R]
Takes a comma-separated list of globs.
Files in the image matching the globs will be purged at the end.
.TP
-\f[B]\f[CB]--build-script=\f[B]\f[R]
+\f[B]\f[CB]BuildScript=\f[B]\f[R], \f[B]\f[CB]--build-script=\f[B]\f[R]
Takes a path to an executable that is used as build script for this
image.
If this option is used the build process will be two-phased instead of
-single-phased (see below).
+single-phased.
The specified script is copied onto the development image and executed
inside an \f[C]systemd-nspawn\f[R] container environment.
If this option is not used, but the \f[C]mkosi.build\f[R] file found in
the local directory it is automatically used for this purpose (also see
-below).
+the \[lq]Files\[rq] section below).
.TP
-\f[B]\f[CB]--environment=\f[B]\f[R]
+\f[B]\f[CB]Environment=\f[B]\f[R], \f[B]\f[CB]--environment=\f[B]\f[R]
Adds variables to the environment that the
build/prepare/postinstall/finalize scripts are executed with.
Takes a space-separated list of variable assignments or just variable
If the same variable is set twice, the later setting overrides the
earlier one.
.TP
-\f[B]\f[CB]--build-sources=\f[B]\f[R]
-Takes a path of a source tree to copy into the development image, if a
+\f[B]\f[CB]BuildSources=\f[B]\f[R], \f[B]\f[CB]--build-sources=\f[B]\f[R]
+Takes a path to a source tree to copy into the development image, if the
build script is used.
This only applies if a build script is used, and defaults to the local
directory.
-Use \f[C]--source-file-transfer=\f[R] to configure how the files are
+Use \f[C]SourceFileTransfer=\f[R] to configure how the files are
transferred from the host to the container image.
.TP
-\f[B]\f[CB]--build-dir=\f[B]\f[R]
+\f[B]\f[CB]BuildDirectory=\f[B]\f[R], \f[B]\f[CB]--build-dir=\f[B]\f[R]
Takes a path of a directory to use as build directory for build systems
that support out-of-tree builds (such as Meson).
The directory used this way is shared between repeated builds, and
\f[C]$BUILDDIR\f[R] environment variable.
If this option is not specified, but a directory
\f[C]mkosi.builddir/\f[R] exists in the local directory it is
-automatically used for this purpose (also see below).
+automatically used for this purpose (also see the \[lq]Files\[rq]
+section below).
.TP
-\f[B]\f[CB]--include-directory\f[B]\f[R]
+\f[B]\f[CB]IncludeDirectory=\f[B]\f[R], \f[B]\f[CB]--include-directory=\f[B]\f[R]
Takes a path of a directory to use as the include directory.
This directory is mounted at \f[C]/usr/include\f[R] when building the
-build image and when running the build script.
+build image and running the build script.
This means all include files installed to \f[C]/usr/include\f[R] will be
stored in this directory.
This is useful to make include files available on the host system for
use by language servers to provide code completion.
If this option is not specified, but a directory
\f[C]mkosi.includedir/\f[R] exists in the local directory, it is
-automatically used for this purpose (also see below).
+automatically used for this purpose (also see the \[lq]Files\[rq]
+section below).
.TP
-\f[B]\f[CB]--install-directory\f[B]\f[R]
+\f[B]\f[CB]InstallDirectory=\f[B]\f[R], \f[B]\f[CB]--install-directory=\f[B]\f[R]
Takes a path of a directory to use as the install directory.
The directory used this way is shared between builds and allows the
build system to not have to reinstall files that were already installed
\f[C]$DESTDIR\f[R] environment variable.
If this option is not specified, but a directory
\f[C]mkosi.installdir\f[R] exists in the local directory, it is
-automatically used for this purpose (also see below).
+automatically used for this purpose (also see the \[lq]Files\[rq]
+section below).
.TP
-\f[B]\f[CB]--build-package=\f[B]\f[R]
-Similar to \f[C]--package=\f[R], but configures packages to install only
+\f[B]\f[CB]BuildPackages=\f[B]\f[R], \f[B]\f[CB]--build-package=\f[B]\f[R]
+Similar to \f[C]Packages=\f[R], but configures packages to install only
in the first phase of the build, into the development image.
This option should be used to list packages containing header files,
compilers, build systems, linkers and other build tools the
\f[C]mkosi.build\f[R] script requires to operate.
Note that packages listed here are only included in the image created
during the first phase of the build, and are absent in the final image.
-use \f[C]--package=\f[R] to list packages that shall be included in
-both.
+Use \f[C]Packages=\f[R] to list packages that shall be included in both.
Packages are appended to the list.
Packages prefixed with \[lq]!\[rq] are removed from the list.
\[lq]!*\[rq] removes all packages from the list.
.TP
-\f[B]\f[CB]--skip-final-phase=\f[B]\f[R]
+\f[B]\f[CB]Password=\f[B]\f[R], \f[B]\f[CB]--password=\f[B]\f[R]
+Set the password of the \f[C]root\f[R] user.
+By default the \f[C]root\f[R] account is locked.
+If this option is not used, but a file \f[C]mkosi.rootpw\f[R] exists in
+the local directory, the root password is automatically read from it.
+.TP
+\f[B]\f[CB]PasswordIsHashed=\f[B]\f[R], \f[B]\f[CB]--password-is-hashed\f[B]\f[R]
+Indicate that the password supplied for the \f[C]root\f[R] user has
+already been hashed, so that the string supplied with
+\f[C]Password=\f[R] or \f[C]mkosi.rootpw\f[R] will be written to
+\f[C]/etc/shadow\f[R] literally.
+.TP
+\f[B]\f[CB]Autologin=\f[B]\f[R], \f[B]\f[CB]--autologin\f[B]\f[R]
+Enable autologin for the \f[C]root\f[R] user on \f[C]/dev/pts/0\f[R]
+(nspawn), \f[C]/dev/tty1\f[R] (QEMU) and \f[C]/dev/ttyS0\f[R] (QEMU with
+\f[C]QemuHeadless=yes\f[R]) by patching \f[C]/etc/pam.d/login\f[R].
+.TP
+\f[B]\f[CB]SkipFinalPhase=\f[B]\f[R], \f[B]\f[CB]--skip-final-phase=\f[B]\f[R]
Causes the (second) final image build stage to be skipped.
This is useful in combination with a build script, for when you care
about the artifacts that were created locally in \f[C]$BUILDDIR\f[R],
but ultimately plan to discard the final image.
.TP
-\f[B]\f[CB]--prepare-script=\f[B]\f[R]
+\f[B]\f[CB]PrepareScript=\f[B]\f[R], \f[B]\f[CB]--prepare-script=\f[B]\f[R]
Takes a path to an executable that is invoked inside the image right
after installing the software packages.
It is the last step before the image is cached (if incremental mode is
environment, and thus does not have access to host resources.
If this option is not used, but an executable script
\f[C]mkosi.prepare\f[R] is found in the local directory, it is
-automatically used for this purpose (also see below).
+automatically used for this purpose.
.TP
-\f[B]\f[CB]--postinst-script=\f[B]\f[R]
+\f[B]\f[CB]PostInstallationScript=\f[B]\f[R], \f[B]\f[CB]--postinst-script=\f[B]\f[R]
Takes a path to an executable that is invoked inside the final image
right after copying in the build artifacts generated in the first phase
of the build.
environment, and thus does not have access to host resources.
If this option is not used, but an executable \f[C]mkosi.postinst\f[R]
is found in the local directory, it is automatically used for this
-purpose (also see below).
+purpose.
.TP
-\f[B]\f[CB]--finalize-script=\f[B]\f[R]
+\f[B]\f[CB]FinalizeScript=\f[B]\f[R], \f[B]\f[CB]--finalize-script=\f[B]\f[R]
Takes a path to an executable that is invoked outside the final image
right after copying in the build artifacts generated in the first phase
of the build, and after having executed the \f[C]mkosi.postinst\f[R]
-script (see above).
+script (see \f[C]PostInstallationScript=\f[R]).
This script is invoked directly in the host environment, and hence has
full access to the host\[cq]s resources.
If this option is not used, but an executable \f[C]mkosi.finalize\f[R]
is found in the local directory, it is automatically used for this
-purpose (also see below).
+purpose.
.TP
-\f[B]\f[CB]--source-file-transfer=\f[B]\f[R]
+\f[B]\f[CB]SourceFileTransfer=\f[B]\f[R], \f[B]\f[CB]--source-file-transfer=\f[B]\f[R]
Configures how the source file tree (as configured with
-\f[C]--build-sources=\f[R]) is transferred into the container image
-during the first phase of the build.
+\f[C]BuildSources=\f[R]) is transferred into the container image during
+the first phase of the build.
Takes one of \f[C]copy-all\f[R] (to copy all files from the source
tree), \f[C]copy-git-cached\f[R] (to copy only those files
\f[C]git-ls-files --cached\f[R] lists), \f[C]copy-git-others\f[R] (to
\f[C]copy-git-cached\f[R], except it also includes the \f[C].git/\f[R]
directory.
.TP
-\f[B]\f[CB]--source-file-transfer-final=\f[B]\f[R]
-Same as \f[C]--source-file-transfer\f[R] but for the final image instead
+\f[B]\f[CB]SourceFileTransferFinal=\f[B]\f[R], \f[B]\f[CB]--source-file-transfer-final=\f[B]\f[R]
+Same as \f[C]SourceFileTransfer=\f[R], but for the final image instead
of the build image.
-Takes the same values as \f[C]--source-file-transfer\f[R] except
+Takes the same values as \f[C]SourceFileFransfer=\f[R] except
\f[C]mount\f[R].
By default, sources are not copied into the final image.
.TP
-\f[B]\f[CB]--source-resolve-symlinks\f[B]\f[R]
+\f[B]\f[CB]SourceResolveSymlinks=\f[B]\f[R], \f[B]\f[CB]--source-resolve-symlinks\f[B]\f[R]
If given, any symbolic links in the source file tree are resolved and
the file contents are copied to the build image.
If not given, they are left as symbolic links.
-This only applies if \f[C]--source-file-transfer\f[R] is
+This only applies if \f[C]SourceFileTransfer=\f[R] is
\f[C]copy-all\f[R].
Defaults to leaving them as symbolic links.
.TP
-\f[B]\f[CB]--source-resolve-symlinks-final\f[B]\f[R]
-Same as \f[C]--source-resolve-symlinks\f[R] but for the final image
+\f[B]\f[CB]SourceResolveSymlinksFinal=\f[B]\f[R], \f[B]\f[CB]--source-resolve-symlinks-final\f[B]\f[R]
+Same as \f[C]SourceResolveSymlinks=\f[R], but for the final image
instead of the build image.
.TP
-\f[B]\f[CB]--with-network\f[B]\f[R]
-Enables network connectivity while the build script
+\f[B]\f[CB]WithNetwork=\f[B]\f[R], \f[B]\f[CB]--with-network\f[B]\f[R]
+When true, enables network connectivity while the build script
\f[C]mkosi.build\f[R] is invoked.
By default, the build script runs with networking turned off.
The \f[C]$WITH_NETWORK\f[R] environment variable is passed to the
\f[C]mkosi.build\f[R] build script indicating whether the build is done
-with or without this option.
-If specified as \f[C]--with-network=never\f[R] the package manager is
-instructed not to contact the network for updating package data.
+with or without network.
+If specified as \f[C]never\f[R], the package manager is instructed not
+to contact the network for updating package data.
This provides a minimal level of reproducibility, as long as the package
data cache is already fully populated.
.TP
-\f[B]\f[CB]--settings=\f[B]\f[R]
+\f[B]\f[CB]Settings=\f[B]\f[R], \f[B]\f[CB]--settings=\f[B]\f[R]
Specifies a \f[C].nspawn\f[R] settings file for \f[C]systemd-nspawn\f[R]
to use in the \f[C]boot\f[R] and \f[C]shell\f[R] verbs, and to place
next to the generated image file.
This is useful to configure the \f[C]systemd-nspawn\f[R] environment
when the image is run.
If this setting is not used but an \f[C]mkosi.nspawn\f[R] file found in
-the local directory it is automatically used for this purpose (also see
-below).
+the local directory it is automatically used for this purpose.
+.SS [Partitions] Section
.TP
-\f[B]\f[CB]--root-size=\f[B]\f[R]
+\f[B]\f[CB]RootSize=\f[B]\f[R], \f[B]\f[CB]--root-size=\f[B]\f[R]
Takes a size in bytes for the root file system.
The specified numeric value may be suffixed with \f[C]K\f[R],
\f[C]M\f[R], \f[C]G\f[R] to indicate kilo-, mega- and gigabytes (all to
\f[C]gpt_btrfs\f[R].
Defaults to 3G.
.TP
-\f[B]\f[CB]--esp-size=\f[B]\f[R]
-Similar, and configures the size of the UEFI System Partition (ESP).
-This is only relevant if the \f[C]--bootable\f[R] option is used to
+\f[B]\f[CB]ESPSize=\f[B]\f[R], \f[B]\f[CB]--esp-size=\f[B]\f[R]
+Similar to \f[C]RootSize=\f[R], configures the size of the UEFI System
+Partition (ESP).
+This is only relevant if the \f[C]Bootable=\f[R] option is used to
generate a bootable image.
-Defaults to 256M.
+Defaults to 256 MB.
.TP
-\f[B]\f[CB]--swap-size=\f[B]\f[R]
-Similar, and configures the size of a swap partition on the image.
-If omitted no swap partition is created.
+\f[B]\f[CB]SwapSize=\f[B]\f[R], \f[B]\f[CB]--swap-size=\f[B]\f[R]
+Similar to \f[C]RootSize=\f[R], configures the size of a swap partition
+on the image.
+If omitted, no swap partition is created.
.TP
-\f[B]\f[CB]--home-size=\f[B]\f[R]
-Similar, and configures the size of the \f[C]/home\f[R] partition.
-If omitted no separate \f[C]/home\f[R] partition is created.
+\f[B]\f[CB]HomeSize=\f[B]\f[R], \f[B]\f[CB]--home-size=\f[B]\f[R]
+Similar to \f[C]RootSize=\f[R], configures the size of the
+\f[C]/home\f[R] partition.
+If omitted, no separate \f[C]/home\f[R] partition is created.
.TP
-\f[B]\f[CB]--srv-size=\f[B]\f[R]
-Similar, and configures the size of the \f[C]/srv\f[R] partition.
-If omitted no separate \f[C]/srv\f[R] partition is created.
+\f[B]\f[CB]SrvSize=\f[B]\f[R], \f[B]\f[CB]--srv-size=\f[B]\f[R]
+Similar to \f[C]RootSize=\f[R], configures the size of the
+\f[C]/srv\f[R] partition.
+If omitted, no separate \f[C]/srv\f[R] partition is created.
+.SS [Validation] Section
.TP
-\f[B]\f[CB]--checksum\f[B]\f[R]
+\f[B]\f[CB]Checksum=\f[B]\f[R], \f[B]\f[CB]--checksum\f[B]\f[R]
Generate a \f[C]SHA256SUMS\f[R] file of all generated artifacts after
the build is complete.
.TP
-\f[B]\f[CB]--sign\f[B]\f[R]
+\f[B]\f[CB]Sign=\f[B]\f[R], \f[B]\f[CB]--sign\f[B]\f[R]
Sign the generated \f[C]SHA256SUMS\f[R] using \f[C]gpg\f[R] after
completion.
.TP
-\f[B]\f[CB]--key=\f[B]\f[R]
+\f[B]\f[CB]Key=\f[B]\f[R], \f[B]\f[CB]--key=\f[B]\f[R]
Select the \f[C]gpg\f[R] key to use for signing \f[C]SHA256SUMS\f[R].
-This key is required to exist in the \f[C]gpg\f[R] keyring already.
+This key must be already present in the \f[C]gpg\f[R] keyring.
.TP
-\f[B]\f[CB]--bmap\f[B]\f[R]
+\f[B]\f[CB]BMap=\f[B]\f[R], \f[B]\f[CB]--bmap\f[B]\f[R]
Generate a \f[C]bmap\f[R] file for usage with \f[C]bmaptool\f[R] from
the generated image file.
+.SS [Host] Section
.TP
-\f[B]\f[CB]--password=\f[B]\f[R]
-Set the password of the \f[C]root\f[R] user.
-By default the \f[C]root\f[R] account is locked.
-If this option is not used but a file \f[C]mkosi.rootpw\f[R] exists in
-the local directory the root password is automatically read from it.
+\f[B]\f[CB]ExtraSearchPaths=\f[B]\f[R], \f[B]\f[CB]--extra-search-paths=\f[B]\f[R]
+List of colon-separated paths to look for tools in, before using the
+regular \f[C]$PATH\f[R] search path.
.TP
-\f[B]\f[CB]--password-is-hashed\f[B]\f[R]
-Indicate that the password supplied for the \f[C]root\f[R] user has
-already been hashed, so that the string supplied with
-\f[C]--password\f[R] or \f[C]mkosi.rootpw\f[R] will be written to
-\f[C]/etc/shadow\f[R] literally.
+\f[B]\f[CB]QemuHeadless=\f[B]\f[R], \f[B]\f[CB]--qemu-headless=\f[B]\f[R]
+When used with the \f[C]build\f[R] verb, this option adds
+\f[C]console=ttyS0\f[R] to the image\[cq]s kernel command line and sets
+the terminal type of the serial console in the image to the terminal
+type of the host (more specifically, the value of the \f[C]$TERM\f[R]
+environment variable passed to mkosi).
+This makes sure that all terminal features such as colors and shortcuts
+still work as expected when connecting to the qemu VM over the serial
+console (for example via \f[C]-nographic\f[R]).
+When used with the \f[C]qemu\f[R] verb, this option adds the
+\f[C]-nographic\f[R] option to \f[C]qemu\f[R]\[cq]s command line so qemu
+starts a headless vm and connects to its serial console from the current
+terminal instead of launching the VM in a separate window.
+.TP
+\f[B]\f[CB]QemuSmp=\f[B]\f[R], \f[B]\f[CB]--qemu-smp=\f[B]\f[R]
+When used with the \f[C]qemu\f[R] verb, this options sets
+\f[C]qemu\f[R]\[cq]s \f[C]-smp\f[R] argument which controls the number
+of guest\[cq]s CPUs.
+Defaults to \f[C]2\f[R].
.TP
-\f[B]\f[CB]--autologin\f[B]\f[R]
-Enable autologin for the \f[C]root\f[R] user on pts/0 (nspawn), tty1
-(QEMU) and ttyS0 (QEMU with \f[C]--qemu-headless\f[R]) by patching
-\f[C]/etc/pam.d/login\f[R].
+\f[B]\f[CB]QemuMem=\f[B]\f[R], \f[B]\f[CB]--qemu-mem=\f[B]\f[R]
+When used with the \f[C]qemu\f[R] verb, this options sets
+\f[C]qemu\f[R]\[cq]s \f[C]-m\f[R] argument which controls the amount of
+guest\[cq]s RAM.
+Defaults to \f[C]1G\f[R].
.TP
-\f[B]\f[CB]--extra-search-paths=\f[B]\f[R]
-List of colon-separated paths to look for tools in, before using the
-regular \f[C]$PATH\f[R] search path.
+\f[B]\f[CB]NetworkVeth=\f[B]\f[R], \f[B]\f[CB]--network-veth\f[B]\f[R]
+When used with the boot or qemu verbs, this option creates a virtual
+ethernet link between the host and the container/VM.
+The host interface is automatically picked up by systemd-networkd as
+documented in systemd-nspawn\[cq]s man page:
+https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-n
+.TP
+\f[B]\f[CB]Ephemeral=\f[B]\f[R], \f[B]\f[CB]--ephemeral\f[B]\f[R]
+When used with the \f[C]shell\f[R], \f[C]boot\f[R], or \f[C]qemu\f[R]
+verbs, this option runs the specified verb on a temporary snapshot of
+the output image that is removed immediately when the container
+terminates.
+Taking the temporary snapshot is more efficient on file systems that
+support subvolume snapshots or `reflinks' natively (\[lq]btrfs\[rq] or
+new \[lq]xfs\[rq]) than on more traditional file systems that do not
+(\[lq]ext4\[rq]).
+.TP
+\f[B]\f[CB]Ssh=\f[B]\f[R], \f[B]\f[CB]--ssh\f[B]\f[R]
+If specified, installs and enables \f[C]sshd\f[R] in the final image and
+generates a SSH keypair and adds the public key to root\[cq]s
+\f[C]authorized_keys\f[R] in the final image.
+The private key is stored in mkosi\[cq]s output directory.
+When building with this option and running the image using
+\f[C]mkosi boot\f[R] or \f[C]mkosi qemu\f[R], the \f[C]mkosi ssh\f[R]
+command can be used to connect to the container/VM via SSH.
+.TP
+\f[B]\f[CB]SshKey=\f[B]\f[R], \f[B]\f[CB]--ssh-key=\f[B]\f[R]
+If specified, use the given private key when connecting to the guest
+machine via \f[C]mkosi ssh\f[R].
+This requires the public key counterpart to be present in the same
+location, suffixed with \f[C].pub\f[R] (as done by
+\f[C]ssh-keygen\f[R]).
+If this option is not present, \f[C]mkosi\f[R] generates a new key pair
+automatically.
+.TP
+\f[B]\f[CB]SshTimeout=\f[B]\f[R], \f[B]\f[CB]--ssh-timeout=\f[B]\f[R]
+When used with the \f[C]ssh\f[R] verb, \f[C]mkosi\f[R] will attempt to
+retry the SSH connection up to given timeout (in seconds) in case it
+fails.
+This option is useful mainly in scripted environments where the
+\f[C]qemu\f[R] and \f[C]ssh\f[R] verbs are used in a quick succession
+and the veth device might not get enough time to configure itself.
+.SS Commandline-only Options
+.PP
+Those settings cannot be configured in the configuration files.
.TP
\f[B]\f[CB]--directory=\f[B]\f[R], \f[B]\f[CB]-C\f[B]\f[R]
Takes a path to a directory.
If specified, overrides the directory the \f[C]--all\f[R] logic
described above looks for settings files in.
If unspecified, defaults to \f[C]mkosi.files/\f[R] in the current
-working directory (see above).
+working directory.
+.TP
+\f[B]\f[CB]--incremental\f[B]\f[R], \f[B]\f[CB]-i\f[B]\f[R]
+Enable incremental build mode.
+This only applies if the two-phase \f[C]mkosi.build\f[R] build script
+logic is used.
+In this mode, a copy of the OS image is created immediately after all OS
+packages are unpacked but before the \f[C]mkosi.build\f[R] script is
+invoked in the development container.
+Similarly, a copy of the final image is created immediately before the
+build artifacts from the \f[C]mkosi.build\f[R] script are copied in.
+On subsequent invocations of \f[C]mkosi\f[R] with the \f[C]-i\f[R]
+switch these cached images may be used to skip the OS package unpacking,
+thus drastically speeding up repetitive build times.
+Note that when this is used and a pair of cached incremental images
+exists they are not automatically regenerated, even if options such as
+\f[C]Packages=\f[R] are modified.
+In order to force rebuilding of these cached images, combine
+\f[C]-i\f[R] with \f[C]-ff\f[R] to ensure cached images are first
+removed and then re-created.
.TP
\f[B]\f[CB]--version\f[B]\f[R]
Show package version.
\f[B]\f[CB]--help\f[B]\f[R], \f[B]\f[CB]-h\f[B]\f[R]
Show brief usage information.
.TP
-\f[B]\f[CB]--qemu-headless=\f[B]\f[R]
-When used with the build verb, this option adds \f[C]console=ttyS0\f[R]
-to the image\[cq]s kernel command line and sets the terminal type of the
-serial console in the image to the terminal type of the host (more
-specifically, the value of the TERM environment variable passed to
-mkosi).
-This makes sure that all terminal features such as colors and shortcuts
-still work as expected when connecting to the qemu VM over the serial
-console (for example via \f[C]-nographic\f[R]).
-.PP
-When used with the qemu verb, this option adds the \f[C]-nographic\f[R]
-option to qemu\[cq]s command line so qemu starts a headless vm and
-connects to its serial console from the current terminal instead of
-launching the VM in a separate window.
-.TP
-\f[B]\f[CB]--qemu-smp=\f[B]\f[R]
-When used with the qemu verb, this options sets the qemu\[cq]s
-\f[C]-smp\f[R] argument which controls the number of guest\[cq]s CPUs.
-Defaults to \f[C]2\f[R].
-.TP
-\f[B]\f[CB]--qemu-mem=\f[B]\f[R]
-When used with the qemu verb, this options sets the qemu\[cq]s
-\f[C]-m\f[R] argument which controls the amount of guest\[cq]s RAM.
-Defaults to \f[C]1G\f[R].
-.TP
-\f[B]\f[CB]--network-veth\f[B]\f[R]
-When used with the boot or qemu verbs, this option creates a virtual
-ethernet link between the host and the container/VM.
-The host interface is automatically picked up by systemd-networkd as
-documented in systemd-nspawn\[cq]s man page:
-https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#-n
-.TP
-\f[B]\f[CB]--ephemeral\f[B]\f[R]
-When used with the shell, boot or qemu verbs, this option runs the
-specified verb on a temporary snapshot of the output image that is
-removed immediately when the container terminates.
-Taking the temporary snapshot is more efficient on file systems that
-support subvolume snapshots or `reflinks' natively (\[lq]btrfs\[rq] or
-new \[lq]xfs\[rq]) than on more traditional file systems that do not
-(\[lq]ext4\[rq]).
-.TP
-\f[B]\f[CB]--ssh\f[B]\f[R]
-If specified, installs and enables sshd in the final image and generates
-a SSH keypair and adds the public key to root\[cq]s authorized keys in
-the final image.
-The private key is stored in mkosi\[cq]s output directory.
-When building with this option and running the image using
-\f[C]mkosi boot\f[R] or \f[C]mkosi qemu\f[R], the \f[C]mkosi ssh\f[R]
-command can be used to connect to the container/VM via SSH.
-.TP
-\f[B]\f[CB]--ssh-key=\f[B]\f[R]
-If specified, use the given private key when connecting to the guest
-machine via \f[C]mkosi ssh\f[R].
-This requires the public key counterpart to be present at the same
-location, suffixed with \f[C].pub\f[R] (as done by
-\f[C]ssh-keygen\f[R]).
-If this option is not present \f[C]mkosi\f[R] generates a new key pair
-automatically.
-.TP
-\f[B]\f[CB]--ssh-timeout=\f[B]\f[R]
-When used with the ssh verb, \f[C]mkosi\f[R] will attempt to retry the
-SSH connection up to given timeout (in seconds) in case it fails.
-This option is useful mainly in scripted environments where the qemu and
-ssh verbs are used in a quick succession and the veth device might not
-get enough time to configure itself.
-.TP
\f[B]\f[CB]--auto-bump\f[B]\f[R], \f[B]\f[CB]-B\f[B]\f[R]
If specified, after each successful build the the version is bumped in a
fashion equivalent to the \f[C]bump\f[R] verb, in preparation for the
next build.
This is useful for simple, linear version management: each build in a
series will have a version number one higher then the previous one.
-.SS Command Line Parameters and their Settings File Counterparts
-.PP
-Most command line parameters may also be placed in an
-\f[C]mkosi.default\f[R] settings file (or any other file
-\f[C]--default=\f[R] is used on).
-The following table shows which command lines parameters correspond with
-which settings file options.
-.PP
-.TS
-tab(@);
-l l l.
-T{
-Command Line Parameter
-T}@T{
-\f[C]mkosi.default\f[R] section
-T}@T{
-\f[C]mkosi.default\f[R] setting
-T}
-_
-T{
-\f[C]--distribution=\f[R], \f[C]-d\f[R]
-T}@T{
-\f[C][Distribution]\f[R]
-T}@T{
-\f[C]Distribution=\f[R]
-T}
-T{
-\f[C]--release=\f[R], \f[C]-r\f[R]
-T}@T{
-\f[C][Distribution]\f[R]
-T}@T{
-\f[C]Release=\f[R]
-T}
-T{
-\f[C]--repositories=\f[R]
-T}@T{
-\f[C][Distribution]\f[R]
-T}@T{
-\f[C]Repositories=\f[R]
-T}
-T{
-\f[C]--mirror=\f[R], \f[C]-m\f[R]
-T}@T{
-\f[C][Distribution]\f[R]
-T}@T{
-\f[C]Mirror=\f[R]
-T}
-T{
-\f[C]--architecture=\f[R]
-T}@T{
-\f[C][Distribution]\f[R]
-T}@T{
-\f[C]Architecture=\f[R]
-T}
-T{
-\f[C]--format=\f[R], \f[C]-t\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]Format=\f[R]
-T}
-T{
-\f[C]--manifest-format=\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]ManifestFormat=\f[R]
-T}
-T{
-\f[C]--output=\f[R], \f[C]-o\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]Output=\f[R]
-T}
-T{
-\f[C]--output-split-root=\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]OutputSplitRoot=\f[R]
-T}
-T{
-\f[C]--output-split-verity=\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]OutputSplitVerity=\f[R]
-T}
-T{
-\f[C]--output-split-kernel=\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]OutputSplitKernel=\f[R]
-T}
-T{
-\f[C]--output-dir=\f[R], \f[C]-O\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]OutputDirectory=\f[R]
-T}
-T{
-\f[C]--force\f[R], \f[C]-f\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]Force=\f[R]
-T}
-T{
-\f[C]--bootable\f[R], \f[C]-b\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]Bootable=\f[R]
-T}
-T{
-\f[C]--boot-protocols=\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]BootProtocols=\f[R]
-T}
-T{
-\f[C]--gpt-first-lba=\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]GPTFirstLBA=\f[R]
-T}
-T{
-\f[C]--kernel-command-line=\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]KernelCommandLine=\f[R]
-T}
-T{
-\f[C]--secure-boot\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]SecureBoot=\f[R]
-T}
-T{
-\f[C]--secure-boot-key=\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]SecureBootKey=\f[R]
-T}
-T{
-\f[C]--secure-boot-certificate=\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]SecureBootCertificate=\f[R]
-T}
-T{
-\f[C]--secure-boot-valid-days=\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]SecureBootValidDays=\f[R]
-T}
-T{
-\f[C]--secure-boot-common-name=\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]SecureBootCommonName=\f[R]
-T}
-T{
-\f[C]--read-only\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]ReadOnly=\f[R]
-T}
-T{
-\f[C]--encrypt=\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]Encrypt=\f[R]
-T}
-T{
-\f[C]--verity=\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]Verity=\f[R]
-T}
-T{
-\f[C]--compress=\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]Compress=\f[R]
-T}
-T{
-\f[C]--compress-fs=\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]CompressFs=\f[R]
-T}
-T{
-\f[C]--compress-output=\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]CompressOutput=\f[R]
-T}
-T{
-\f[C]--mksquashfs=\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]Mksquashfs=\f[R]
-T}
-T{
-\f[C]--qcow2\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]QCow2=\f[R]
-T}
-T{
-\f[C]--no-chown\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]NoChown=\f[R]
-T}
-T{
-\f[C]--tar-strip-selinux-context\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]TarStripSELinuxContext=\f[R]
-T}
-T{
-\f[C]--hostname=\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]Hostname=\f[R]
-T}
-T{
-\f[C]--image-version=\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]ImageVersion=\f[R]
-T}
-T{
-\f[C]--image-id=\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]ImageId=\f[R]
-T}
-T{
-\f[C]--without-unified-kernel-images\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]WithUnifiedKernelImages=\f[R]
-T}
-T{
-\f[C]--hostonly-initrd\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]HostonlyInitrd=\f[R]
-T}
-T{
-\f[C]--usr-only\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]UsrOnly=\f[R]
-T}
-T{
-\f[C]--split-artifacts\f[R]
-T}@T{
-\f[C][Output]\f[R]
-T}@T{
-\f[C]SplitArtifacts=\f[R]
-T}
-T{
-\f[C]--base-packages=\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]BasePackages=\f[R]
-T}
-T{
-\f[C]--package=\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]Packages=\f[R]
-T}
-T{
-\f[C]--with-docs\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]WithDocs=\f[R]
-T}
-T{
-\f[C]--without-tests\f[R], \f[C]-T\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]WithTests=\f[R]
-T}
-T{
-\f[C]--cache=\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]Cache=\f[R]
-T}
-T{
-\f[C]--extra-tree=\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]ExtraTrees=\f[R]
-T}
-T{
-\f[C]--skeleton-tree=\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]SkeletonTrees=\f[R]
-T}
-T{
-\f[C]--remove-files=\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]RemoveFiles=\f[R]
-T}
-T{
-\f[C]--build-script=\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]BuildScript=\f[R]
-T}
-T{
-\f[C]--environment=\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]Environment=\f[R]
-T}
-T{
-\f[C]--build-sources=\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]BuildSources=\f[R]
-T}
-T{
-\f[C]--source-file-transfer=\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]SourceFileTransfer=\f[R]
-T}
-T{
-\f[C]--source-file-transfer-final=\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]SourceFileTransferFinal=\f[R]
-T}
-T{
-\f[C]--source-resolve-symlinks\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]SourceResolveSymlinks=\f[R]
-T}
-T{
-\f[C]--source-resolve-symlinks-final\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]SourceResolveSymlinksFinal=\f[R]
-T}
-T{
-\f[C]--build-directory=\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]BuildDirectory=\f[R]
-T}
-T{
-\f[C]--include-directory=\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]IncludeDirectory=\f[R]
-T}
-T{
-\f[C]--install-directory=\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]InstallDirectory=\f[R]
-T}
-T{
-\f[C]--build-packages=\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]BuildPackages=\f[R]
-T}
-T{
-\f[C]--skip-final-phase=\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]SkipFinalPhase=\f[R]
-T}
-T{
-\f[C]--prepare-script=\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]PrepareScript=\f[R]
-T}
-T{
-\f[C]--postinst-script=\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]PostInstallationScript=\f[R]
-T}
-T{
-\f[C]--finalize-script=\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]FinalizeScript=\f[R]
-T}
-T{
-\f[C]--with-network\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]WithNetwork=\f[R]
-T}
-T{
-\f[C]--settings=\f[R]
-T}@T{
-\f[C][Packages]\f[R]
-T}@T{
-\f[C]NSpawnSettings=\f[R]
-T}
-T{
-\f[C]--root-size=\f[R]
-T}@T{
-\f[C][Partitions]\f[R]
-T}@T{
-\f[C]RootSize=\f[R]
-T}
-T{
-\f[C]--esp-size=\f[R]
-T}@T{
-\f[C][Partitions]\f[R]
-T}@T{
-\f[C]ESPSize=\f[R]
-T}
-T{
-\f[C]--swap-size=\f[R]
-T}@T{
-\f[C][Partitions]\f[R]
-T}@T{
-\f[C]SwapSize=\f[R]
-T}
-T{
-\f[C]--home-size=\f[R]
-T}@T{
-\f[C][Partitions]\f[R]
-T}@T{
-\f[C]HomeSize=\f[R]
-T}
-T{
-\f[C]--srv-size=\f[R]
-T}@T{
-\f[C][Partitions]\f[R]
-T}@T{
-\f[C]SrvSize=\f[R]
-T}
-T{
-\f[C]--checksum\f[R]
-T}@T{
-\f[C][Validation]\f[R]
-T}@T{
-\f[C]CheckSum=\f[R]
-T}
-T{
-\f[C]--sign\f[R]
-T}@T{
-\f[C][Validation]\f[R]
-T}@T{
-\f[C]Sign=\f[R]
-T}
-T{
-\f[C]--key=\f[R]
-T}@T{
-\f[C][Validation]\f[R]
-T}@T{
-\f[C]Key=\f[R]
-T}
-T{
-\f[C]--bmap\f[R]
-T}@T{
-\f[C][Validation]\f[R]
-T}@T{
-\f[C]BMap=\f[R]
-T}
-T{
-\f[C]--password=\f[R]
-T}@T{
-\f[C][Validation]\f[R]
-T}@T{
-\f[C]Password=\f[R]
-T}
-T{
-\f[C]--password-is-hashed\f[R]
-T}@T{
-\f[C][Validation]\f[R]
-T}@T{
-\f[C]PasswordIsHashed=\f[R]
-T}
-T{
-\f[C]--autologin\f[R]
-T}@T{
-\f[C][Validation]\f[R]
-T}@T{
-\f[C]Autologin=\f[R]
-T}
-T{
-\f[C]--extra-search-paths=\f[R]
-T}@T{
-\f[C][Host]\f[R]
-T}@T{
-\f[C]ExtraSearchPaths=\f[R]
-T}
-T{
-\f[C]--qemu-headless\f[R]
-T}@T{
-\f[C][Host]\f[R]
-T}@T{
-\f[C]QemuHeadless=\f[R]
-T}
-T{
-\f[C]--qemu-smp\f[R]
-T}@T{
-\f[C][Host]\f[R]
-T}@T{
-\f[C]QemuSmp=\f[R]
-T}
-T{
-\f[C]--qemu-mem\f[R]
-T}@T{
-\f[C][Host]\f[R]
-T}@T{
-\f[C]QemuMem=\f[R]
-T}
-T{
-\f[C]--network-veth\f[R]
-T}@T{
-\f[C][Host]\f[R]
-T}@T{
-\f[C]NetworkVeth=\f[R]
-T}
-T{
-\f[C]--ephemeral\f[R]
-T}@T{
-\f[C][Host]\f[R]
-T}@T{
-\f[C]Ephemeral=\f[R]
-T}
-T{
-\f[C]--ssh\f[R]
-T}@T{
-\f[C][Host]\f[R]
-T}@T{
-\f[C]Ssh=\f[R]
-T}
-T{
-\f[C]--ssh-key=\f[R]
-T}@T{
-\f[C][Host]\f[R]
-T}@T{
-\f[C]SshKey=\f[R]
-T}
-T{
-\f[C]--ssh-timeout=\f[R]
-T}@T{
-\f[C][Host]\f[R]
-T}@T{
-\f[C]SshTimeout=\f[R]
-T}
-.TE
-.PP
-Command line options that take no argument are not suffixed with a
-\f[C]=\f[R] in their long version in the table above.
-In the \f[C]mkosi.default\f[R] file they are modeled as boolean option
-that take either \f[C]1\f[R], \f[C]yes\f[R], \f[C]true\f[R] for
-enabling, and \f[C]0\f[R], \f[C]no\f[R], \f[C]false\f[R] for disabling.
.SS Supported distributions
.PP
Images may be created containing installations of the following
systemd-nspawn -bD image
\f[R]
.fi
-.SH FILES
+.SH Files
.PP
To make it easy to build images for development versions of your
projects, mkosi can read configuration data from the local directory,
multi-line assignments: any line with initial whitespace is considered a
continuation line of the line before.
Command-line arguments, as shown in the help description, have to be
-included in a configuration block (e.g.\ \[lq]\f[C][Packages]\f[R]\[rq])
-corresponding to the argument group
-(e.g.\ \[lq]\f[C]Packages\f[R]\[rq]), and the argument gets converted as
-follows: \[lq]\f[C]--with-network\f[R]\[rq] becomes
+included in a configuration block (e.g.\ \[lq]\f[C][Content]\f[R]\[rq])
+corresponding to the argument group (e.g.\ \[lq]\f[C]Content\f[R]\[rq]),
+and the argument gets converted as follows:
+\[lq]\f[C]--with-network\f[R]\[rq] becomes
\[lq]\f[C]WithNetwork=yes\f[R]\[rq].
For further details see the table above.
.RE
otherwise a version of an image built earlier might be included in a
later build, which is usually not intended.
An alternative to excluding these built images via \f[C].gitignore\f[R]
-entries is to use the \f[C]mkosi.output/\f[R] directory (see below),
-which is an easy way to exclude all build artifacts.
+entries is to use the \f[C]mkosi.output/\f[R] directory, which is an
+easy way to exclude all build artifacts.
.PP
The \f[C]$MKOSI_DEFAULT\f[R] environment variable will be set inside of
this script so that you know which \f[C]mkosi.default\f[R] (if any) was
minimal and contains only those packages necessary at runtime, but
avoiding those necessary at build-time.
.PP
-Note that only the package cache \f[C]mkosi.cache/\f[R] (see below) is
-shared between the two phases.
+Note that only the package cache \f[C]mkosi.cache/\f[R] is shared
+between the two phases.
The distribution package manager is executed exactly once in each phase,
always starting from a directory tree that is populated with
\f[C]mkosi.skeleton\f[R] but nothing else.
downloaded, but before they are unpacked.
.IP "2." 3
If an \f[C]mkosi.build\f[R] script is used, by enabling incremental
-build mode with \f[C]--incremental\f[R] (see above) a cached copy of the
+build mode with \f[C]--incremental\f[R], a cached copy of the
development and final images can be made immediately before the build
sources are copied in (for the development image) or the artifacts
generated by \f[C]mkosi.build\f[R] are copied in (in case of the final
.IP \[bu] 2
\f[C]$WITH_DOCS\f[R] is either \f[C]0\f[R] or \f[C]1\f[R] depending on
whether a build without or with installed documentation was requested
-(see \f[C]--with-docs\f[R] above).
+(\f[C]WithDocs=yes\f[R]).
The build script should suppress installation of any package
documentation to \f[C]$DESTDIR\f[R] in case \f[C]$WITH_DOCS\f[R] is set
to \f[C]0\f[R].
.IP \[bu] 2
\f[C]$WITH_TESTS\f[R] is either \f[C]0\f[R]or \f[C]1\f[R] depending on
whether a build without or with running the test suite was requested
-(see \f[C]--without-tests\f[R] above).
+(\f[C]WithTests=no\f[R]).
The build script should avoid running any unit or integration tests in
case \f[C]$WITH_TESTS\f[R] is \f[C]0\f[R].
.IP \[bu] 2
\f[C]$WITH_NETWORK\f[R] is either \f[C]0\f[R]or \f[C]1\f[R] depending on
-whether a build without or with networking is being executed (see
-\f[C]--with-network\f[R] above).
+whether a build without or with networking is being executed
+(\f[C]WithNetwork=no\f[R]).
The build script should avoid any network communication in case
\f[C]$WITH_NETWORK\f[R] is \f[C]0\f[R].
.SH EXAMPLES
Format=gpt_btrfs
Bootable=yes
-[Packages]
+[Content]
Packages=openssh-clients,httpd
BuildPackages=make,gcc,libcurl-devel
EOF
projects / thirdparty / mkosi.git / commitdiff
