-.\" Automatically generated by Pandoc 2.14.0.2
+.\" Automatically generated by Pandoc 2.14.0.3
.\"
.TH "mkosi" "1" "2016-" "" ""
.hy
| . | .
| . v .
| . copy .
- | . extra trees .
- | . (mkosi.extra/) .
+ | . build sources .
+ | . (./) .
| . | .
| . v .
| . copy .
- | . build sources .
- | . (./) .
+ | . extra trees .
+ | . (mkosi.extra/) .
| . | .
| . v .
| . run .
. . |
. . 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 . .
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]
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]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.
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.
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
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
\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
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.
\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
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.
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
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
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
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],
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
\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
\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
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.
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
.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
projects / thirdparty / mkosi.git / commitdiff
