Adding upstream version 4.23.0.upstream/4.23.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 493 insertions, 77 deletions

diff --git a/upstream/debian-unstable/man1/mkosi.1 b/upstream/debian-unstable/man1/mkosi.1
index 4e8f1e7c..20a68bef 100644
--- a/upstream/debian-unstable/man1/mkosi.1
+++ b/upstream/debian-unstable/man1/mkosi.1
@@ -32,6 +32,8 @@ mkosi \[em] Build Bespoke OS Images
 .PP
 \f[V]mkosi [options\&...] qemu [qemu parameters\&...]\f[R]
 .PP
+\f[V]mkosi [options\&...] vmspawn [vmspawn settings\&...]\f[R]
+.PP
 \f[V]mkosi [options\&...] ssh [command line\&...]\f[R]
 .PP
 \f[V]mkosi [options\&...] journalctl [command line\&...]\f[R]
@@ -103,6 +105,15 @@ For cpio images a kernel can also be provided by passing the
 Any arguments specified after the \f[V]qemu\f[R] verb are appended to
 the \f[V]qemu\f[R] invocation.
 .TP
+\f[V]vmspawn\f[R]
+Similar to \f[V]boot\f[R], but uses \f[V]systemd-vmspawn\f[R] to boot up
+the image, i.e.
+instead of container virtualization virtual machine virtualization is
+used.
+This verb is only supported for disk and directory type images.
+Any arguments specified after the \f[V]vmspawn\f[R] verb are appended to
+the \f[V]systemd-vmspawn\f[R] invocation.
+.TP
 \f[V]ssh\f[R]
 When the image is built with the \f[V]Ssh=yes\f[R] option, this command
 connects to a booted virtual machine (\f[V]qemu\f[R]) via SSH.
@@ -212,7 +223,7 @@ project located in a specific directory.
 \f[V]--debug=\f[R]
 Enable additional debugging output.
 .TP
-\f[V]--debug-shell=\f[R]
+\f[V]--debug-shell\f[R]
 When executing a command in the image fails, mkosi will start an
 interactive shell in the image allowing further debugging.
 .TP
@@ -339,20 +350,21 @@ the CLI.
 .PP
 To conditionally include configuration files, the \f[V][Match]\f[R]
 section can be used.
-Matches can use a pipe symbol (\f[V]|\f[R]) after the equals sign
-(\f[V]\&...=|\&...\f[R]), which causes the match to become a triggering
-match.
+A \f[V][Match]\f[R] section consists of invididual conditions.
+Conditions can use a pipe symbol (\f[V]|\f[R]) after the equals sign
+(\f[V]\&...=|\&...\f[R]), which causes the condition to become a
+triggering condition.
 The config file will be included if the logical AND of all
-non-triggering matches and the logical OR of all triggering matches is
-satisfied.
-To negate the result of a match, prefix the argument with an exclamation
-mark.
+non-triggering conditions and the logical OR of all triggering
+conditions is satisfied.
+To negate the result of a condition, prefix the argument with an
+exclamation mark.
 If an argument is prefixed with the pipe symbol and an exclamation mark,
 the pipe symbol must be passed first, and the exclamation second.
 .PP
-Note that \f[V][Match]\f[R] settings match against the current values of
-specific settings, and do not take into account changes made to the
-setting in configuration files that have not been parsed yet.
+Note that \f[V][Match]\f[R] conditions compare against the current
+values of specific settings, and do not take into account changes made
+to the setting in configuration files that have not been parsed yet.
 Also note that matching against a setting and then changing its value
 afterwards in a different config file may lead to unexpected results.
 .PP
@@ -365,7 +377,7 @@ The \f[V][Match]\f[R] sections of files in \f[V]mkosi.conf.d/\f[R] and
 If there are multiple \f[V][Match]\f[R] sections in the same
 configuration file, each of them has to be satisfied in order for the
 configuration file to be included.
-Specifically, triggering matches only apply to the current
+Specifically, triggering conditions only apply to the current
 \f[V][Match]\f[R] section and are reset between multiple
 \f[V][Match]\f[R] sections.
 As an example, the following will only match if the output format is one
@@ -384,6 +396,41 @@ Architecture=|arm64
 \f[R]
 .fi
 .PP
+The \f[V][TriggerMatch]\f[R] section can be used to indicate triggering
+match sections.
+These are identical to triggering conditions except they apply to the
+entire match section instead of just a single condition.
+As an example, the following will match if the distribution is
+\f[V]debian\f[R] and the release is \f[V]bookworm\f[R] or if the
+distribution is \f[V]ubuntu\f[R] and the release is \f[V]focal\f[R].
+.IP
+.nf
+\f[C]
+[TriggerMatch]
+Distribution=debian
+Release=bookworm
+
+[TriggerMatch]
+Distribution=ubuntu
+Release=focal
+\f[R]
+.fi
+.PP
+The semantics of conditions in \f[V][TriggerMatch]\f[R] sections is the
+same as in \f[V][Match]\f[R], i.e.\ all normal conditions are joined by
+a logical AND and all triggering conditions are joined by a logical OR.
+When mixing \f[V][Match]\f[R] and \f[V][TriggerMatch]\f[R] sections, a
+match is achieved when all \f[V][Match]\f[R] sections match and at least
+one \f[V][TriggerMatch]\f[R] section matches.
+No match sections are valued as true.
+Logically this means:
+.IP
+.nf
+\f[C]
+(⋀ᵢ Matchᵢ) ∧ (⋁ᵢ TriggerMatchᵢ)
+\f[R]
+.fi
+.PP
 Command line options that take no argument are shown without \f[V]=\f[R]
 in their long version.
 In the config files, they should be specified with a boolean argument:
@@ -616,6 +663,12 @@ which case the configuration is included after parsing all the other
 configuration files.
 Note that each path containing extra configuration is only parsed once,
 even if included more than once with \f[V]Include=\f[R].
+The builtin configs for the mkosi default initrd and default tools tree
+can be included by including the literal value \f[V]mkosi-initrd\f[R]
+and \f[V]mkosi-tools\f[R] respectively.
+Note: Include names starting with either of the literals
+\f[V]mkosi-\f[R] or \f[V]contrib-\f[R] are reserved for use by mkosi
+itself.
 .TP
 \f[V]InitrdInclude=\f[R], \f[V]--initrd-include=\f[R]
 Same as \f[V]Include=\f[R], but the extra configuration files or
@@ -789,10 +842,15 @@ This can be used to enable the EPEL repos for CentOS or different
 components of the Debian/Ubuntu repositories.
 .TP
 \f[V]CacheOnly=\f[R], \f[V]--cache-only=\f[R]
-If specified, the package manager is instructed not to contact the
-network for updating package data.
+Takes one of \f[V]none\f[R], \f[V]metadata\f[R] or \f[V]always\f[R].
+If \f[V]always\f[R], the package manager is instructed not to contact
+the network.
 This provides a minimal level of reproducibility, as long as the package
 cache is already fully populated.
+If set to \f[V]metadata\f[R], the package manager can still download
+packages, but we won\[cq]t sync the repository metadata.
+If set to \f[V]none\f[R], the repository metadata is synced and packages
+can be downloaded during the build.
 .TP
 \f[V]PackageManagerTrees=\f[R], \f[V]--package-manager-tree=\f[R]
 This option mirrors the above \f[V]SkeletonTrees=\f[R] option and
@@ -870,6 +928,11 @@ verbs are not available when this option is used.
 Implied for \f[V]tar\f[R], \f[V]cpio\f[R], \f[V]uki\f[R], and
 \f[V]esp\f[R].
 .TP
+\f[V]CompressLevel=\f[R], \f[V]--compress-level=\f[R]
+Configure the compression level to use.
+Takes an integer.
+The possible values depend on the compression being used.
+.TP
 \f[V]OutputDirectory=\f[R], \f[V]--output-dir=\f[R], \f[V]-O\f[R]
 Path to a directory where to place all generated artifacts.
 If this is not specified and the directory \f[V]mkosi.output/\f[R]
@@ -889,11 +952,18 @@ an \f[V]mkosi\f[R] invocation be aborted abnormally (for example, due to
 reboot/power failure).
 .TP
 \f[V]CacheDirectory=\f[R], \f[V]--cache-dir=\f[R]
-Takes a path to a directory to use as package cache for the distribution
-package manager used.
+Takes a path to a directory to use as the incremental cache directory
+for the incremental images produced when the \f[V]Incremental=\f[R]
+option is enabled.
 If this option is not used, but a \f[V]mkosi.cache/\f[R] directory is
 found in the local directory it is automatically used for this purpose.
 .TP
+\f[V]PackageCacheDirectory=\f[R], \f[V]--package-cache-dir\f[R]
+Takes a path to a directory to use as the package cache directory for
+the distribution package manager used.
+If unset, a suitable directory in the user\[cq]s home directory or
+system is used.
+.TP
 \f[V]BuildDirectory=\f[R], \f[V]--build-dir=\f[R]
 Takes a path to a directory to use as the build directory for build
 systems that support out-of-tree builds (such as Meson).
@@ -1123,8 +1193,8 @@ scratch.
 Only extra packages are installed on top of the ones already installed
 in the base trees.
 Note that for this to work properly, the base image still needs to
-contain the package manager metadata (see
-\f[V]CleanPackageMetadata=\f[R]).
+contain the package manager metadata by setting
+\f[V]CleanPackageMetadata=no\f[R] (see \f[V]CleanPackageMetadata=\f[R]).
 Instead of a directory, a tar file or a disk image may be provided.
 In this case it is unpacked into the OS tree.
 This mode of operation allows setting permissions and file ownership
@@ -1185,13 +1255,18 @@ Takes a comma-separated list of globs.
 Files in the image matching the globs will be purged at the end.
 .TP
 \f[V]CleanPackageMetadata=\f[R], \f[V]--clean-package-metadata=\f[R]
-Enable/disable removal of package manager databases at the end of
-installation.
+Enable/disable removal of package manager databases and repository
+metadata at the end of installation.
 Can be specified as \f[V]true\f[R], \f[V]false\f[R], or \f[V]auto\f[R]
 (the default).
-With \f[V]auto\f[R], files will be removed if the respective package
-manager executable is \f[I]not\f[R] present at the end of the
-installation.
+With \f[V]auto\f[R], package manager databases and repository metadata
+will be removed if the respective package manager executable is
+\f[I]not\f[R] present at the end of the installation.
+.TP
+\f[V]SyncScripts=\f[R], \f[V]--sync-script=\f[R]
+Takes a comma-separated list of paths to executables that are used as
+the sync scripts for this image.
+See the \f[B]Scripts\f[R] section for more information.
 .TP
 \f[V]PrepareScripts=\f[R], \f[V]--prepare-script=\f[R]
 Takes a comma-separated list of paths to executables that are used as
@@ -1231,7 +1306,7 @@ Disabled by default.
 Configures whether changes to source directories (The working directory
 and configured using \f[V]BuildSources=\f[R]) are persisted.
 If enabled, all source directories will be reset to their original state
-after scripts finish executing.
+after scripts (except sync scripts) finish executing.
 .TP
 \f[V]Environment=\f[R], \f[V]--environment=\f[R]
 Adds variables to the environment that package managers and the
@@ -1350,6 +1425,25 @@ binaries again.
 Note that this option only takes effect when an image that is bootable
 on UEFI firmware is requested using other options (\f[V]Bootable=\f[R],
 \f[V]Bootloader=\f[R]).
+Note that when this option is enabled, mkosi will only install already
+signed bootloader binaries, kernel image files and unified kernel images
+as self-signed binaries would not be accepted by the signed version of
+shim.
+.TP
+\f[V]UnifiedKernelImages=\f[R], \f[V]--unified-kernel-images=\f[R]
+Specifies whether to use unified kernel images or not when
+\f[V]Bootloader=\f[R] is set to \f[V]systemd-boot\f[R] or
+\f[V]grub\f[R].
+Takes a boolean value or \f[V]auto\f[R].
+Defaults to \f[V]auto\f[R].
+If enabled, unified kernel images are always used and the build will
+fail if any components required to build unified kernel images are
+missing.
+If set to \f[V]auto\f[R], unified kernel images will be used if all
+necessary components are available.
+Otherwise Type 1 entries as defined by the Boot Loader Specification
+will be used instead.
+If disabled, Type 1 entries will always be used.
 .TP
 \f[V]Initrds=\f[R], \f[V]--initrd\f[R]
 Use user-provided initrd(s).
@@ -1365,8 +1459,16 @@ Takes a comma separated list of package specifications.
 This option may be used multiple times in which case the specified
 package lists are combined.
 .TP
+\f[V]MicrocodeHost=\f[R], \f[V]--microcode-host=\f[R]
+When set to true only include microcode for the host\[cq]s CPU in the
+image.
+.TP
 \f[V]KernelCommandLine=\f[R], \f[V]--kernel-command-line=\f[R]
 Use the specified kernel command line when building images.
+Defaults to \f[V]console=ttyS0\f[R].
+For \f[V]arm\f[R], \f[V]s390\f[R] and \f[V]ppc\f[R], \f[V]ttyS0\f[R] is
+replaced with \f[V]ttyAMA0\f[R], \f[V]ttysclp0\f[R] or \f[V]hvc0\f[R],
+respectively.
 .TP
 \f[V]KernelModulesInclude=\f[R], \f[V]--kernel-modules-include=\f[R]
 Takes a list of regex patterns that specify kernel modules to include in
@@ -1509,7 +1611,14 @@ Defaults to \f[V]yes\f[R].
 .TP
 \f[V]SecureBootKey=\f[R], \f[V]--secure-boot-key=\f[R]
 Path to the PEM file containing the secret key for signing the UEFI
-kernel image, if \f[V]SecureBoot=\f[R] is used.
+kernel image if \f[V]SecureBoot=\f[R] is used and PCR signatures when
+\f[V]SignExpectedPcr=\f[R] is also used.
+When \f[V]SecureBootKeySource=\f[R] is specified, the input type depends
+on the source.
+.TP
+\f[V]SecureBootKeySource=\f[R], \f[V]--secure-boot-key-source=\f[R]
+Source of \f[V]SecureBootKey=\f[R], to support OpenSSL engines.
+E.g.: \f[V]--secure-boot-key-source=engine:pkcs11\f[R]
 .TP
 \f[V]SecureBootCertificate=\f[R], \f[V]--secure-boot-certificate=\f[R]
 Path to the X.509 file containing the certificate for the signed UEFI
@@ -1525,6 +1634,12 @@ with sbsign being preferred if both are installed.
 \f[V]VerityKey=\f[R], \f[V]--verity-key=\f[R]
 Path to the PEM file containing the secret key for signing the verity
 signature, if a verity signature partition is added with systemd-repart.
+When \f[V]VerityKeySource=\f[R] is specified, the input type depends on
+the source.
+.TP
+\f[V]VerityKeySource=\f[R], \f[V]--verity-key-source=\f[R]
+Source of \f[V]VerityKey=\f[R], to support OpenSSL engines.
+E.g.: \f[V]--verity-key-source=engine:pkcs11\f[R]
 .TP
 \f[V]VerityCertificate=\f[R], \f[V]--verity-certificate=\f[R]
 Path to the X.509 file containing the certificate for signing the verity
@@ -1537,6 +1652,8 @@ kernel image.
 This option takes a boolean value or the special value \f[V]auto\f[R],
 which is the default, which is equal to a true value if the
 \f[V]systemd-measure\f[R] binary is in \f[V]PATH\f[R].
+Depends on \f[V]SecureBoot=\f[R] being enabled and key from
+\f[V]SecureBootKey=\f[R].
 .TP
 \f[V]Passphrase=\f[R], \f[V]--passphrase\f[R]
 Specify the path to a file containing the passphrase to use for LUKS
@@ -1646,35 +1763,35 @@ Defaults to \f[V]no\f[R].
 \f[V]QemuFirmware=\f[R], \f[V]--qemu-firmware=\f[R]
 When used with the \f[V]qemu\f[R] verb, this option specifies which
 firmware to use.
-Takes one of \f[V]uefi\f[R], \f[V]bios\f[R], \f[V]linux\f[R], or
-\f[V]auto\f[R].
+Takes one of \f[V]uefi\f[R], \f[V]uefi-secure-boot\f[R], \f[V]bios\f[R],
+\f[V]linux\f[R], or \f[V]auto\f[R].
 Defaults to \f[V]auto\f[R].
-When set to \f[V]uefi\f[R], the OVMF firmware is used.
+When set to \f[V]uefi\f[R], the OVMF firmware without secure boot
+support is used.
+When set to \f[V]uefi-secure-boot\f[R], the OVMF firmware with secure
+boot support is used.
 When set to \f[V]bios\f[R], the default SeaBIOS firmware is used.
 When set to \f[V]linux\f[R], direct kernel boot is used.
 See the \f[V]QemuKernel=\f[R] option for more details on which kernel
 image is used with direct kernel boot.
-When set to \f[V]auto\f[R], \f[V]linux\f[R] is used if a cpio image is
-being booted, \f[V]uefi\f[R] otherwise.
+When set to \f[V]auto\f[R], \f[V]uefi-secure-boot\f[R] is used if
+possible and \f[V]linux\f[R] otherwise.
 .TP
 \f[V]QemuFirmwareVariables=\f[R], \f[V]--qemu-firmware-variables=\f[R]
 When used with the \f[V]qemu\f[R] verb, this option specifies the path
 to the the firmware variables file to use.
 Currently, this option is only taken into account when the
-\f[V]uefi\f[R] firmware is used.
+\f[V]uefi\f[R] or \f[V]uefi-secure-boot\f[R] firmware is used.
 If not specified, mkosi will search for the default variables file and
 use that instead.
+When set to \f[V]microsoft\f[R], a firmware variables file with the
+Microsoft secure boot certificates already enrolled will be used.
+When set to \f[V]custom\f[R], the secure boot certificate from
+\f[V]SecureBootCertificate=\f[R] will be enrolled into the default
+firmware variables file.
 \f[V]virt-fw-vars\f[R] from the
 virt-firmware (https://gitlab.com/kraxel/virt-firmware) project can be
 used to customize OVMF variable files.
-Some distributions also provide variable files which already have
-Microsoft\[cq]s certificates for secure boot enrolled.
-For Fedora and Debian these are \f[V]OVMF_VARS.secboot.fd\f[R] and
-\f[V]OVMF_VARS_4M.ms.fd\f[R] under \f[V]/usr/share/OVMF\f[R]
-respectively.
-You can use \f[V]locate\f[R] and look under
-\f[V]/usr/share/qemu/firmware\f[R] for hints on where to find these
-files if your distribution ships them.
 .TP
 \f[V]QemuKernel=\f[R], \f[V]--qemu-kernel=\f[R]
 Set the kernel image to use for qemu direct kernel boot.
@@ -1701,7 +1818,18 @@ respectively.
 \f[V]directory\f[R] optionally specifies the directory in which to
 create the file backing the drive.
 \f[V]options\f[R] optionally specifies extra comma-delimited properties
-which are passed verbatime to qemu\[cq]s \f[V]-drive\f[R] option.
+which are passed verbatim to qemu\[cq]s \f[V]-drive\f[R] option.
+Example usage:
+.IP
+.nf
+\f[C]
+[Host]
+QemuDrives=btrfs:10G
+           ext4:20G
+QemuArgs=-device nvme,serial=btrfs,drive=btrfs
+         -device nvme,serial=ext4,drive=ext4
+\f[R]
+.fi
 .TP
 \f[V]QemuArgs=\f[R]
 Space-delimited list of additional arguments to pass when invoking qemu.
@@ -1736,8 +1864,8 @@ directories that allow the user running mkosi to remove them without
 needing privileges.
 .TP
 \f[V]ToolsTree=\f[R], \f[V]--tools-tree=\f[R]
-If specified, programs executed by mkosi are looked up inside the given
-tree instead of in the host system.
+If specified, programs executed by mkosi to build and boot an image are
+looked up inside the given tree instead of in the host system.
 Use this option to make image builds more reproducible by always using
 the same versions of programs to build the final image instead of
 whatever version is installed on the host system.
@@ -1773,6 +1901,21 @@ openSUSE
 T}
 _
 T{
+\f[V]acl\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
 \f[V]apt\f[R]
 T}@T{
 X
@@ -1800,6 +1943,21 @@ X
 T}@T{
 T}
 T{
+\f[V]attr\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
 \f[V]bash\f[R]
 T}@T{
 X
@@ -2051,6 +2209,66 @@ T}@T{
 X
 T}
 T{
+\f[V]findutils\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]git\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]grep\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]jq\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
 \f[V]kmod\f[R]
 T}@T{
 X
@@ -2141,6 +2359,21 @@ T}@T{
 X
 T}
 T{
+\f[V]sed\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
 \f[V]pacman\f[R]
 T}@T{
 X
@@ -2358,6 +2591,18 @@ T}@T{
 X
 T}
 T{
+\f[V]virt-firmware\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+T}@T{
+T}@T{
+X
+T}@T{
+T}
+T{
 \f[V]xfsprogs\f[R]
 T}@T{
 X
@@ -2432,6 +2677,12 @@ is used.
 Set the mirror to use for the default tools tree.
 By default, the default mirror for the tools tree distribution is used.
 .TP
+\f[V]ToolsTreeRepositories=\f[R], \f[V]--tools-tree-repository\f[R]
+Same as \f[V]Repositories=\f[R] but for the default tools tree.
+.TP
+\f[V]ToolsTreePackageManagerTrees=\f[R], \f[V]--tools-tree-package-manager-tree=\f[R]
+Same as \f[V]PackageManagerTrees=\f[R] but for the default tools tree.
+.TP
 \f[V]ToolsTreePackages=\f[R], \f[V]--tools-tree-packages=\f[R]
 Extra packages to install into the default tools tree.
 Takes a comma separated list of package specifications.
@@ -2473,6 +2724,22 @@ If enabled, practically unlimited scratch space is made available under
 Note that using this feature with \f[V]mkosi qemu\f[R] requires systemd
 v254 or newer in the guest.
 .TP
+\f[V]RuntimeNetwork=\f[R]: \f[V]--runtime-network=\f[R]
+Takes one of \f[V]user\f[R], \f[V]interface\f[R] or \f[V]none\f[R].
+Defaults to \f[V]user\f[R].
+Specifies the networking to set up when booting the image.
+\f[V]user\f[R] sets up usermode networking.
+\f[V]interface\f[R] sets up a virtual network connection between the
+host and the image.
+This translates to a veth interface for \f[V]mkosi shell\f[R] and
+\f[V]mkosi boot\f[R] and a tap interface for \f[V]mkosi qemu\f[R] and
+\f[V]mkosi vmspawn\f[R].
+Note that when using \f[V]interface\f[R], mkosi does not automatically
+configure the host interface.
+It is expected that a recent version of \f[V]systemd-networkd\f[R] is
+running on the host which will automatically configure the host
+interface of the link.
+.TP
 \f[V]SshKey=\f[R], \f[V]--ssh-key=\f[R]
 Path to the X509 private key in PEM format to use to connect to a
 virtual machine started with \f[V]mkosi qemu\f[R] and built with the
@@ -2576,10 +2843,6 @@ distributions:
 .IP \[bu] 2
 \f[I]Alma Linux\f[R]
 .IP \[bu] 2
-\f[I]Gentoo\f[R] (\f[B]Gentoo is experimental and unsupported.
-We make no guarantee that it will work at all and the core maintainers
-will generally not fix gentoo specific issues\f[R])
-.IP \[bu] 2
 \f[I]None\f[R] (\f[B]Requires the user to provide a pre-built
 rootfs\f[R])
 .PP
@@ -2648,61 +2911,67 @@ Then, for each image, we execute the following steps:
 .IP " 1." 4
 Copy package manager trees into the workspace
 .IP " 2." 4
-Copy base trees (\f[V]--base-tree=\f[R]) into the image
+Sync the package manager repository metadata
 .IP " 3." 4
-Copy skeleton trees (\f[V]mkosi.skeleton\f[R]) into image
+Copy base trees (\f[V]--base-tree=\f[R]) into the image
 .IP " 4." 4
-Install distribution and packages into image or use cache tree if
-available
+Reuse a cached image if one is available
 .IP " 5." 4
+Copy a snapshot of the package manager repository metadata into the
+image
+.IP " 6." 4
+Copy skeleton trees (\f[V]mkosi.skeleton\f[R]) into image
+.IP " 7." 4
+Install distribution and packages into image
+.IP " 8." 4
 Run prepare scripts on image with the \f[V]final\f[R] argument
 (\f[V]mkosi.prepare\f[R])
-.IP " 6." 4
+.IP " 9." 4
 Install build packages in overlay if any build scripts are configured
-.IP " 7." 4
+.IP "10." 4
 Run prepare scripts on overlay with the \f[V]build\f[R] argument if any
 build scripts are configured (\f[V]mkosi.prepare\f[R])
-.IP " 8." 4
+.IP "11." 4
 Cache the image if configured (\f[V]--incremental\f[R])
-.IP " 9." 4
+.IP "12." 4
 Run build scripts on image + overlay if any build scripts are configured
 (\f[V]mkosi.build\f[R])
-.IP "10." 4
+.IP "13." 4
 Finalize the build if the output format \f[V]none\f[R] is configured
-.IP "11." 4
+.IP "14." 4
 Copy the build scripts outputs into the image
-.IP "12." 4
+.IP "15." 4
 Copy the extra trees into the image (\f[V]mkosi.extra\f[R])
-.IP "13." 4
+.IP "16." 4
 Run post-install scripts (\f[V]mkosi.postinst\f[R])
-.IP "14." 4
+.IP "17." 4
 Write config files required for \f[V]Ssh=\f[R], \f[V]Autologin=\f[R] and
 \f[V]MakeInitrd=\f[R]
-.IP "15." 4
+.IP "18." 4
 Install systemd-boot and configure secure boot if configured
 (\f[V]--secure-boot\f[R])
-.IP "16." 4
+.IP "19." 4
 Run \f[V]systemd-sysusers\f[R]
-.IP "17." 4
+.IP "20." 4
 Run \f[V]systemd-tmpfiles\f[R]
-.IP "18." 4
+.IP "21." 4
 Run \f[V]systemctl preset-all\f[R]
-.IP "19." 4
+.IP "22." 4
 Run \f[V]depmod\f[R]
-.IP "20." 4
+.IP "23." 4
 Run \f[V]systemd-firstboot\f[R]
-.IP "21." 4
+.IP "24." 4
 Run \f[V]systemd-hwdb\f[R]
-.IP "22." 4
+.IP "25." 4
 Remove packages and files (\f[V]RemovePackages=\f[R],
 \f[V]RemoveFiles=\f[R])
-.IP "23." 4
+.IP "26." 4
 Run SELinux relabel is a SELinux policy is installed
-.IP "24." 4
+.IP "27." 4
 Run finalize scripts (\f[V]mkosi.finalize\f[R])
-.IP "25." 4
+.IP "28." 4
 Generate unified kernel image if configured to do so
-.IP "26." 4
+.IP "29." 4
 Generate final output format
 .SH Scripts
 .PP
@@ -2720,6 +2989,16 @@ in the current working directory.
 \f[V]$SRCDIR\f[R] is set to point to the current working directory.
 The following scripts are supported:
 .IP \[bu] 2
+If \f[B]\f[VB]mkosi.sync\f[B]\f[R] (\f[V]SyncScripts=\f[R]) exists, it
+is executed before the image is built.
+This script may be used to update various sources that are used to build
+the image.
+One use case is to run \f[V]git pull\f[R] on various source repositories
+before building the image.
+Specifically, the \f[V]BuildSourcesEphemeral=\f[R] setting does not
+apply to sync scripts, which means sync scripts can be used to update
+build sources even if \f[V]BuildSourcesEphemeral=\f[R] is enabled.
+.IP \[bu] 2
 If \f[B]\f[VB]mkosi.prepare\f[B]\f[R] (\f[V]PrepareScripts=\f[R])
 exists, it is first called with the \f[V]final\f[R] argument, right
 after the software packages are installed.
@@ -2774,6 +3053,18 @@ architecture of the host machine.
 See the documentation of \f[V]Architecture=\f[R] for possible values for
 this variable.
 .IP \[bu] 2
+\f[V]$DISTRIBUTION\f[R] contains the distribution from the
+\f[V]Distribution=\f[R] setting.
+.IP \[bu] 2
+\f[V]$RELEASE\f[R] contains the release from the \f[V]Release=\f[R]
+setting.
+.IP \[bu] 2
+\f[V]$PROFILE\f[R] contains the profile from the \f[V]Profile=\f[R]
+setting.
+.IP \[bu] 2
+\f[V]$CACHED=\f[R] is set to \f[V]1\f[R] if a cached image is available,
+\f[V]0\f[R] otherwise.
+.IP \[bu] 2
 \f[V]$CHROOT_SCRIPT\f[R] contains the path to the running script
 relative to the image root directory.
 The primary usecase for this variable is in combination with the
@@ -2847,16 +3138,23 @@ in the user namespace that mkosi is running in.
 These can be used in combination with \f[V]setpriv\f[R] to run commands
 as the user that invoked mkosi (e.g.
 \f[V]setpriv --reuid=$MKOSI_UID --regid=$MKOSI_GID --clear-groups <command>\f[R])
+.IP \[bu] 2
+\f[V]$MKOSI_CONFIG\f[R] is a file containing a json summary of the
+settings of the current image.
+This file can be parsed inside scripts to gain access to all settings
+for the current image.
 .PP
 Consult this table for which script receives which environment
 variables:
 .PP
 .TS
 tab(@);
-lw(16.5n) lw(13.4n) lw(11.8n) lw(14.2n) lw(14.2n).
+lw(14.3n) lw(9.5n) lw(11.6n) lw(10.2n) lw(12.2n) lw(12.2n).
 T{
 Variable
 T}@T{
+\f[V]mkosi.sync\f[R]
+T}@T{
 \f[V]mkosi.prepare\f[R]
 T}@T{
 \f[V]mkosi.build\f[R]
@@ -2867,7 +3165,22 @@ T}@T{
 T}
 _
 T{
-\f[V]$CHROOT_SCRIPT\f[R]
+\f[V]ARCHITECTURE\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]DISTRIBUTION\f[R]
+T}@T{
+X
 T}@T{
 X
 T}@T{
@@ -2878,7 +3191,56 @@ T}@T{
 X
 T}
 T{
-\f[V]$SRCDIR\f[R]
+\f[V]RELEASE\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]PROFILE\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]CACHED\f[R]
+T}@T{
+X
+T}@T{
+T}@T{
+T}@T{
+T}@T{
+T}
+T{
+\f[V]CHROOT_SCRIPT\f[R]
+T}@T{
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}
+T{
+\f[V]SRCDIR\f[R]
+T}@T{
+X
 T}@T{
 X
 T}@T{
@@ -2891,6 +3253,7 @@ T}
 T{
 \f[V]CHROOT_SRCDIR\f[R]
 T}@T{
+T}@T{
 X
 T}@T{
 X
@@ -2900,7 +3263,8 @@ T}@T{
 X
 T}
 T{
-\f[V]$BUILDDIR\f[R]
+\f[V]BUILDDIR\f[R]
+T}@T{
 T}@T{
 T}@T{
 X
@@ -2911,6 +3275,7 @@ T{
 \f[V]CHROOT_BUILDDIR\f[R]
 T}@T{
 T}@T{
+T}@T{
 X
 T}@T{
 T}@T{
@@ -2919,6 +3284,7 @@ T{
 \f[V]DESTDIR\f[R]
 T}@T{
 T}@T{
+T}@T{
 X
 T}@T{
 T}@T{
@@ -2927,12 +3293,14 @@ T{
 \f[V]CHROOT_DESTDIR\f[R]
 T}@T{
 T}@T{
+T}@T{
 X
 T}@T{
 T}@T{
 T}
 T{
-\f[V]$OUTPUTDIR\f[R]
+\f[V]OUTPUTDIR\f[R]
+T}@T{
 T}@T{
 T}@T{
 X
@@ -2945,6 +3313,7 @@ T{
 \f[V]CHROOT_OUTPUTDIR\f[R]
 T}@T{
 T}@T{
+T}@T{
 X
 T}@T{
 X
@@ -2952,7 +3321,8 @@ T}@T{
 X
 T}
 T{
-\f[V]$BUILDROOT\f[R]
+\f[V]BUILDROOT\f[R]
+T}@T{
 T}@T{
 X
 T}@T{
@@ -2965,6 +3335,7 @@ T}
 T{
 \f[V]WITH_DOCS\f[R]
 T}@T{
+T}@T{
 X
 T}@T{
 X
@@ -2974,6 +3345,7 @@ T}
 T{
 \f[V]WITH_TESTS\f[R]
 T}@T{
+T}@T{
 X
 T}@T{
 X
@@ -2983,6 +3355,7 @@ T}
 T{
 \f[V]WITH_NETWORK\f[R]
 T}@T{
+T}@T{
 X
 T}@T{
 X
@@ -2992,6 +3365,7 @@ T}
 T{
 \f[V]SOURCE_DATE_EPOCH\f[R]
 T}@T{
+T}@T{
 X
 T}@T{
 X
@@ -3010,6 +3384,8 @@ T}@T{
 X
 T}@T{
 X
+T}@T{
+X
 T}
 T{
 \f[V]MKOSI_GID\f[R]
@@ -3021,6 +3397,21 @@ T}@T{
 X
 T}@T{
 X
+T}@T{
+X
+T}
+T{
+\f[V]MKOSI_CONFIG\f[R]
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
+T}@T{
+X
 T}
 .TE
 .PP
@@ -3064,6 +3455,13 @@ these commands operate on the image\[cq]s root directory with the
 configuration supplied by the user instead of on the host system.
 This means that from a script, you can do
 e.g.\ \f[V]dnf   install vim\f[R] to install vim into the image.
+.RS 2
+.PP
+Additionally, \f[V]mkosi-install\f[R], \f[V]mkosi-reinstall\f[R],
+\f[V]mkosi-upgrade\f[R] and \f[V]mkosi-remove\f[R] will invoke the
+corresponding operation of the package manager being used to built the
+image.
+.RE
 .IP \[bu] 2
 \f[V]mkosi-as-caller\f[R]: This script uses \f[V]setpriv\f[R] to switch
 from the user \f[V]root\f[R] in the user namespace used for various
@@ -3527,6 +3925,7 @@ Note that the minimum required Python version is 3.9.
 .SH Frequently Asked Questions (FAQ)
 .IP \[bu] 2
 Why does \f[V]mkosi qemu\f[R] with KVM not work on Debian/Ubuntu?
+.RS 2
 .PP
 While other distributions are OK with allowing access to
 \f[V]/dev/kvm\f[R], on Debian/Ubuntu this is only allowed for users in
@@ -3542,6 +3941,23 @@ To persist these settings across reboots, copy
 \f[V]/usr/lib/tmpfiles.d/static-nodes-permissions.conf\f[R] to
 \f[V]/etc/tmpfiles.d/static-nodes-permissions.conf\f[R] and change the
 mode of \f[V]/dev/kvm\f[R] from \f[V]0660\f[R] to \f[V]0666\f[R].
+.RE
+.IP \[bu] 2
+How do I add a regular user to an image?
+.RS 2
+.PP
+You can use the following snippet in a post-installation script:
+.IP
+.nf
+\f[C]
+useradd --create-home --user-group $USER --password \[dq]$(openssl passwd -stdin -6 <$USER_PASSWORD_FILE)\[dq]
+\f[R]
+.fi
+.PP
+Note that from systemd v256 onwards, if enabled,
+\f[V]systemd-homed-firstboot.service\f[R] will prompt to create a
+regular user on first boot if there are no regular users.
+.RE
 .SH REFERENCES
 .IP \[bu] 2
 Primary mkosi git repository on