From: Zbigniew Jędrzejewski-Szmek Date: Wed, 24 Nov 2021 15:10:02 +0000 (+0100) Subject: man: rebuild the man page X-Git-Tag: v11~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bb3d7bb0d4e51d5dbc706ab2ae14b5dbf0e333b7;p=thirdparty%2Fmkosi.git man: rebuild the man page --- diff --git a/man/mkosi.1 b/man/mkosi.1 index 8ac41f92b..f7b3c66d9 100644 --- a/man/mkosi.1 +++ b/man/mkosi.1 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pandoc 2.14.0.2 +.\" Automatically generated by Pandoc 2.14.0.3 .\" .TH "mkosi" "1" "2016-" "" "" .hy @@ -210,13 +210,13 @@ build script? -------exists-----> copy . | . | . | . v . | . copy . - | . extra trees . - | . (mkosi.extra/) . + | . build sources . + | . (./) . | . | . | . v . | . copy . - | . build sources . - | . (./) . + | . extra trees . + | . (mkosi.extra/) . | . | . | . v . | . run . @@ -256,18 +256,24 @@ build script? -------exists-----> copy . . . | . . v . . copy - . . extra trees - . . (mkosi.extra/) + . . build results . . | . . v . . copy - . . build results + . . extra trees + . . (mkosi.extra/) . . | . . v . . run . . postinstall script . . (mkosi.postinst final) . . | + . . v + . . | + . . perform cleanup + . . (remove files, packages, + . . package metadata) + . . | .--------------------------------------------------\[aq] | . . v . . @@ -306,8 +312,10 @@ either \[lq]1\[rq], \[lq]yes\[rq], or \[lq]true\[rq] to enable, or 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]mageia\f[R], \f[C]centos\f[R], \f[C]clear\f[R], \f[C]photon\f[R], -\f[C]openmandriva\f[R]. +\f[C]mageia\f[R], \f[C]centos\f[R], \f[C]centos_epel\f[R], +\f[C]clear\f[R], \f[C]photon\f[R], \f[C]openmandriva\f[R], +\f[C]rocky\f[R], \f[C]rocky_epel\f[R], \f[C]alma\f[R], +\f[C]alma_epel\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]--release=\f[B]\f[R], \f[B]\f[CB]-r\f[B]\f[R] @@ -334,13 +342,16 @@ e.g.\ \[lq]!repo-url\[rq] to remove just one specific repository. For Arch Linux, additional repositories must be passed in the form \f[C]::\f[R] (e.g.\ \f[C]myrepo::https://myrepo.net\f[R]). .TP -\f[B]\f[CB]UseHostRepositories=\f[B]\f[R], \f[B]\f[CB]--use-host-repositories=\f[B]\f[R] +\f[B]\f[CB]UseHostRepositories=\f[B]\f[R], \f[B]\f[CB]--use-host-repositories\f[B]\f[R] This option is only applicable for dnf-based distributions: -\f[I]CentOS\f[R], \f[I]Fedora Linux\f[R], \f[I]Mageia\f[R], \f[I]Photon\f[R], and \f[I]OpenMandriva\f[R]. -Allows use of the host's existing dnf repositories. -By default, a hardcoded set of default dnf repositories is generated and used. -Use \f[C]--repositories=\f[R] to identify a custom set of repositories to -be enabled and used for the build. +\f[I]CentOS\f[R], \f[I]Fedora Linux\f[R], \f[I]Mageia\f[R], +\f[I]Photon\f[R], \f[I]Rocky Linux\f[R], \f[I]Alma Linux\f[R] and +\f[I]OpenMandriva\f[R]. +Allows use of the host\[cq]s existing dnf repositories. +By default, a hardcoded set of default dnf repositories is generated and +used. +Use \f[C]--repositories=\f[R] to identify a custom set of repositories +to be enabled and used for the build. .TP \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. @@ -531,11 +542,27 @@ 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] -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 +Add a \[lq]Verity\[rq] integrity partition to the image. +Takes a boolean or the special value \f[C]signed\f[R], and defaults to +disabled. +If enabled, the root partition (or \f[C]/usr/\f[R] partition, in case +\f[C]UsrOnly=\f[R] is enabled) is protected with \f[C]dm-verity\f[R] +against offline modification, the verification data is placed in an additional GPT partition. Implies \f[C]ReadOnly=yes\f[R]. +If this is enabled, the Verity root hash is written to an output file +with \f[C].roothash\f[R] or \f[C].usrhash\f[R] suffix. +If set to \f[C]signed\f[R], Verity is also enabled, but the resulting +root hash is then also signed (in PKCS#7 format) with the signature key +configured with \f[C]SecureBootKey=\f[R]. +Or in other words: the SecureBoot key pair is then used to both sign the +kernel, if that is enabled, and the root/\f[C]/usr/\f[R] file system. +This signature is then stored in an additional output file with the +\f[C].roothash.p7s\f[R] or \f[C].usrhash.p7s\f[R] suffix in DER format. +It is also written to an additional partition in the image. +The latter allows generating self-contained signed disk images, +implementing the Verity provisions described in the Discoverable +Partitions Specification (https://systemd.io/DISCOVERABLE_PARTITIONS). .TP \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. @@ -604,7 +631,7 @@ This accepts a freeform string that shall be used to identify the image with. If set the default output file will be named after it (possibly suffixed with the version). -If this option is used the root, \f[C]/usr/\f[R] and verity partitions +If this option is used the root, \f[C]/usr/\f[R] and Verity partitions in the image will have their labels set to this (possibly suffixed by the image version). The identifier is also passed via the \f[C]$IMAGE_ID\f[R] to any build @@ -652,10 +679,10 @@ 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]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. +If running on a SELinux-enabled system (Fedora Linux, CentOS, Rocky +Linux, Alma Linux), 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 @@ -684,7 +711,7 @@ implemented for all distributions. \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. +Takes a comma separated list of package specifications. This option may be used multiple times in which case the specified package lists are combined. Packages specified this way will be installed both in the development @@ -692,12 +719,27 @@ 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. +The types and syntax of \[lq]package specifications\[rq] that are +allowed depend on the package installer (e.g.\ \f[C]dnf\f[R] or +\f[C]yum\f[R] for \f[C]rpm\f[R]-based distros or \f[C]apt\f[R] for +\f[C]deb\f[R]-based distros), but may include package names, package +names with version and/or architecture, package name globs, paths to +packages in the file system, package groups, and virtual provides, +including file paths. To remove a package e.g.\ added by a \f[C]mkosi.default\f[R] 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]. +Example: when using an distro that uses \f[C]dnf\f[R], +\f[C]Packages=meson libfdisk-devel.i686 git-* prebuilt/rpms/systemd-249-rc1.local.rpm /usr/bin/ld \[at]development-tools python3dist(mypy)\f[R] +would install the \f[C]meson\f[R] package (in the latest version), the +32-bit version of the \f[C]libfdisk-devel\f[R] package, all available +packages that start with the \f[C]git-\f[R] prefix, a \f[C]systemd\f[R] +rpm from the local file system, one of the packages that provides +\f[C]/usr/bin/ld\f[R], the packages in the \[lq]Development Tools\[rq] +group, and the package that contains the \f[C]mypy\f[R] python module. .TP \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. @@ -755,20 +797,26 @@ 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]CleanPackageMetadata=\f[B]\f[R], \f[B]\f[CB]--clean-package-metadata=\f[B]\f[R] +Enable/disable removal of package manager databases, caches, and logs at +the end of installation. +Can be specifed as true, false, or \[lq]\f[C]auto\f[R]\[rq] (the +default). +With \[lq]\f[C]auto\f[R]\[rq], files will be removed if the respective +package manager executable is \f[I]not\f[R] present at the end of the +installation. +.TP \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]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. -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 -the \[lq]Files\[rq] section below). +\f[B]\f[CB]RemovePackages=\f[B]\f[R], \f[B]\f[CB]--remove-package=\f[B]\f[R] +Takes a comma-separated list of package specifications for removal, in +the same format as \f[C]Packages=\f[R]. +The removal will be performed as one of the last steps. +This step is skipped if \f[C]CleanPackageMetadata=no\f[R] is used. +This option is currently only implemented for distributions using +\f[C]dnf\f[R]. .TP \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 @@ -866,6 +914,18 @@ 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]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. +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 +the \[lq]Files\[rq] section below). +Specify an empty value to disable automatic detection. +.TP \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. @@ -876,6 +936,7 @@ 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. +Specify an empty value to disable automatic detection. .TP \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 @@ -886,6 +947,7 @@ 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. +Specify an empty value to disable automatic detection. .TP \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 @@ -897,6 +959,7 @@ 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. +Specify an empty value to disable automatic detection. .TP \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 @@ -954,6 +1017,19 @@ 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. .SS [Partitions] Section .TP +\f[B]\f[CB]BaseImage=\f[B]\f[R], \f[B]\f[CB]--base-image=\f[B]\f[R] +Use the specified directory or file system image as the base image, and +create the output image that consists only of changes from this base. +The base image is attached as the lower file system in an overlayfs +structure, and the output filesystem becomes the upper layer, initially +empty. +Thus files that are not modified compared to the base image are not +present in the output image. +This option may be used to create systemd \[lq]system extensions\[rq] or +portable services. +See https://systemd.io/PORTABLE_SERVICES/#extension-images for more +information. +.TP \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], @@ -1068,6 +1144,21 @@ location, suffixed with \f[C].pub\f[R] (as done by If this option is not present, \f[C]mkosi\f[R] generates a new key pair automatically. .TP +\f[B]\f[CB]SshAgent=\f[B]\f[R], \f[B]\f[CB]--ssh-agent=\f[B]\f[R] +If specified as a path, use the given socket to connect to the ssh agent +when building an image and when connecting via \f[C]mkosi ssh\f[R] +instead of hard-coding a key. +If specified as \f[C]true\f[R], \f[C]$SSH_AUTH_SOCK\f[R] will be parsed +instead (hint: use \f[C]sudo\f[R] with \f[C]-E\f[R]). +The keys listed by \f[C]ssh-add -L\f[R] will be installed as authorized +keys in the built image. +The \f[C]ssh\f[R] invocation done by \f[C]mkosi ssh\f[R] will inherit +\f[C]$SSH_AUTH_SOCK\f[R] for authentication purposes. +.TP +\f[B]\f[CB]SshPort=\f[B]\f[R], \f[B]\f[CB]--ssh-port=\f[B]\f[R] +In the image, sshd will be configured to listen on this port. +\f[C]mkosi ssh\f[R] will connect to this port. +.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 @@ -1130,6 +1221,12 @@ 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]--debug=\f[B]\f[R] +Enable additional debugging output. +Takes a comma-separated list of arguments specifying the area of +interest. +Pass any invalid value (e.g.\ empty) to list currently accepted values. +.TP \f[B]\f[CB]--version\f[B]\f[R] Show package version. .TP @@ -1166,6 +1263,12 @@ operating systems: \f[I]Photon\f[R] .IP \[bu] 2 \f[I]OpenMandriva\f[R] +.IP \[bu] 2 +\f[I]Rocky Linux\f[R] +.IP \[bu] 2 +\f[I]Alma Linux\f[R] +.IP \[bu] 2 +\f[I]Gentoo\f[R] .PP In theory, any distribution may be used on the host for building images containing any other distribution, as long as the necessary tools are @@ -1180,7 +1283,10 @@ Any distro that packages \f[C]pacstrap\f[R] may be used to build Any distribution that packages \f[C]zypper\f[R] may be used to build \f[I]openSUSE\f[R] images. Any distribution that packages \f[C]yum\f[R] (or the newer replacement -\f[C]dnf\f[R]) may be used to build \f[I]CentOS\f[R] images. +\f[C]dnf\f[R]) may be used to build \f[I]CentOS\f[R], \f[I]Rocky +Linux\f[R], or \f[I]Alma Linux\f[R] images. +Any distribution that packages \f[C]emerge\f[R] may be used to build +\f[I]Gentoo\f[R] images. .PP Currently, \f[I]Fedora Linux\f[R] packages all relevant tools as of Fedora 28. @@ -1233,8 +1339,8 @@ The \f[B]\f[CB]mkosi.default\f[B]\f[R] file provides the default configuration for the image building process. For example, it may specify the distribution to use (\f[C]fedora\f[R], \f[C]ubuntu\f[R], \f[C]debian\f[R], \f[C]arch\f[R], \f[C]opensuse\f[R], -\f[C]mageia\f[R], \f[C]openmandriva\f[R]) for the image, or additional -distribution packages to install. +\f[C]mageia\f[R], \f[C]openmandriva\f[R], \f[C]gentoo\f[R]) for the +image, or additional distribution packages to install. Note that all options encoded in this configuration file may also be set on the command line, and this file is hence little more than a way to make sure invoking \f[C]mkosi\f[R] without further parameters in your @@ -1686,7 +1792,7 @@ Hostname=image .SH REQUIREMENTS .PP mkosi is packaged for various distributions: Debian, Ubuntu, Arch Linux, -Fedora Linux, OpenMandriva. +Fedora Linux, OpenMandriva, Gentoo. It is usually easiest to use the distribution package. .PP The current version requires systemd 233 (or actually, systemd-nspawn of