diff options
Diffstat (limited to 'upstream/fedora-rawhide/man1/mkosi.1')
| -rw-r--r-- | upstream/fedora-rawhide/man1/mkosi.1 | 1852 |
1 files changed, 0 insertions, 1852 deletions
diff --git a/upstream/fedora-rawhide/man1/mkosi.1 b/upstream/fedora-rawhide/man1/mkosi.1 deleted file mode 100644 index e32d7ccb..00000000 --- a/upstream/fedora-rawhide/man1/mkosi.1 +++ /dev/null @@ -1,1852 +0,0 @@ -.\" Automatically generated by Pandoc 2.14.0.3 -.\" -.TH "mkosi" "1" "2016-" "" "" -.hy -.SH NAME -.PP -mkosi \[em] Build Bespoke OS Images -.SH SYNOPSIS -.PP -\f[C]mkosi [options\&...] build\f[R] -.PP -\f[C]mkosi [options\&...] clean\f[R] -.PP -\f[C]mkosi [options\&...] summary\f[R] -.PP -\f[C]mkosi [options\&...] shell [command line\&...]\f[R] -.PP -\f[C]mkosi [options\&...] boot [nspawn settings\&...]\f[R] -.PP -\f[C]mkosi [options\&...] qemu\f[R] -.PP -\f[C]mkosi [options\&...] ssh\f[R] -.PP -\f[C]mkosi [options\&...] serve\f[R] -.PP -\f[C]mkosi [options\&...] bump\f[R] -.PP -\f[C]mkosi [options\&...] genkey\f[R] -.PP -\f[C]mkosi [options\&...] help\f[R] -.SH DESCRIPTION -.PP -\f[C]mkosi\f[R] is a tool for easily building customized OS images. -It\[cq]s a fancy wrapper around \f[C]dnf --installroot\f[R], -\f[C]debootstrap\f[R], \f[C]pacstrap\f[R] and \f[C]zypper\f[R] that may -generate disk images with a number of bells and whistles. -.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. -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 -the build script (if there is one). -.TP -\f[B]\f[CB]clean\f[B]\f[R] -Remove build artifacts generated on a previous build. -If combined with \f[C]-f\f[R], also removes incremental build cache -images. -If \f[C]-f\f[R] is specified twice, also removes any package cache. -.TP -\f[B]\f[CB]summary\f[B]\f[R] -Outputs a human-readable summary of all options used for building an -image. -This will parse the command line and \f[C]mkosi.default\f[R] file as it -would do on \f[C]build\f[R], but only output what it is configured for -and not actually build anything.\[ga] -.TP -\f[B]\f[CB]shell\f[B]\f[R] -This builds the image if it is not built yet, and then invokes -\f[C]systemd-nspawn\f[R] to acquire an interactive shell prompt in it. -If this verb is used an optional command line may be specified which is -then invoked in place of the shell in the container. -Combine this with \f[C]-f\f[R] in order to rebuild the image -unconditionally before acquiring the shell, see below. -This command must be executed as \f[C]root\f[R]. -.TP -\f[B]\f[CB]boot\f[B]\f[R] -Similar to \f[C]shell\f[R] but boots the image up using -\f[C]systemd-nspawn\f[R]. -If this verb is used an optional command line may be specified which is -passed as \[lq]kernel command line\[rq] to the init system in the image. -.TP -\f[B]\f[CB]qemu\f[B]\f[R] -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=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=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 -\f[C]mkosi build\f[R] was run with so that it has the necessary -information available to connect to the running container/VM via SSH. -.TP -\f[B]\f[CB]serve\f[B]\f[R] -This builds the image if it is not built yet, and then serves the output -directory (i.e.\ usually \f[C]mkosi.output/\f[R], see below) via a small -embedded HTTP server, listening on port 8081. -Combine with \f[C]-f\f[R] in order to rebuild the image unconditionally -before serving it. -This command is useful for testing network based acquisition of OS -images, for example via \f[C]machinectl pull-raw \&...\f[R] and -\f[C]machinectl pull-tar \&...\f[R]. -.TP -\f[B]\f[CB]bump\f[B]\f[R] -Determines the current image version string (as configured with -\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 -this verb is called the version is bumped in preparation for the -subsequent build. -Note that \f[C]--auto-bump\f[R]/\f[C]-B\f[R] may be used to -automatically bump the version after each successful build. -.TP -\f[B]\f[CB]genkey\f[B]\f[R] -Generate a pair of SecureBoot keys for usage with the -\f[C]SecureBootKey=\f[R]/\f[C]--secure-boot-key=\f[R] and -\f[C]SecureBootCertificate=\f[R]/\f[C]--secure-boot-certificate=\f[R] -options. -.TP -\f[B]\f[CB]help\f[B]\f[R] -This verb is equivalent to the \f[C]--help\f[R] switch documented below: -it shows a brief usage explanation. -.SS Execution flow -.PP -Execution flow for \f[C]mkosi build\f[R]. -Columns represent the execution context. -Default values/calls are shown in parentheses. -When building with \f[C]--incremental\f[R] mkosi creates a cache of the -distribution installation for both images if not already existing and -replaces the distribution installation in consecutive runs with data -from the cached one. -.IP -.nf -\f[C] - HOST . BUILD . FINAL - . IMAGE . IMAGE - . . - start . . - | . . - v . . -build script? -------exists-----> copy . - | . skeleton trees . - | . (mkosi.skeleton/) . - none . | . - | . v . - v . install . - skip . distribution, . - build image . packages and . - | . build packages, . - | . run . - | . prepare script . - | . (mkosi.prepare build) . - | . or if incremental . - | . use cached build image . - | . | . - | . v . - | . copy . - | . build sources . - | . (./) . - | . | . - | . v . - | . copy . - | . extra trees . - | . (mkosi.extra/) . - | . | . - | . v . - | . run . - | . postinstall script . - | . (mkosi.postinst build) . - | . | . - | .-------------------------\[aq] . - | | . . - | v . . - | run . . - | finalize script . . - |(mkosi.finalize build). . - | | . . - | \[aq]-------------------------. . - | . | . - | . v . - | . run . - | . build script . - | . (mkosi.build) . - | . | . - \[aq]-----------------------------------+------------------------. - . . | - . . v - . . copy - . . skeleton trees - . . (mkosi.skeleton/) - . . | - . . v - . . install - . . distribution - . . and packages, - . . run - . . prepare script - . . (mkosi.prepare final) - . . or if incremental - . . use cached final image - . . | - . . v - . . copy - . . build results - . . | - . . v - . . copy - . . extra trees - . . (mkosi.extra/) - . . | - . . v - . . run - . . postinstall script - . . (mkosi.postinst final) - . . | - . . v - . . | - . . perform cleanup - . . (remove files, packages, - . . package metadata) - . . | - .--------------------------------------------------\[aq] - | . . - v . . - run . . - finalize script . . - (mkosi.finalize final) . . - | . . - .---------\[aq] . . - | . . - v . . - end . . - . . - HOST . BUILD . FINAL - . IMAGE . IMAGE - . . -\f[R] -.fi -.SS Supported output formats -.PP -The following output formats are supported: -.IP \[bu] 2 -Raw \f[I]GPT\f[R] disk image, with ext4 as root (\f[I]gpt_ext4\f[R]) -.IP \[bu] 2 -Raw \f[I]GPT\f[R] disk image, with xfs as root (\f[I]gpt_xfs\f[R]) -.IP \[bu] 2 -Raw \f[I]GPT\f[R] disk image, with btrfs as root (\f[I]gpt_btrfs\f[R]) -.IP \[bu] 2 -Raw \f[I]GPT\f[R] disk image, with squashfs as read-only root -(\f[I]gpt_squashfs\f[R]) -.IP \[bu] 2 -Plain squashfs image, without partition table, as read-only root -(\f[I]plain_squashfs\f[R]) -.IP \[bu] 2 -Plain directory, containing the OS tree (\f[I]directory\f[R]) -.IP \[bu] 2 -btrfs subvolume, with separate subvolumes for \f[C]/var\f[R], -\f[C]/home\f[R], \f[C]/srv\f[R], \f[C]/var/tmp\f[R] -(\f[I]subvolume\f[R]) -.IP \[bu] 2 -Tar archive (\f[I]tar\f[R]) -.IP \[bu] 2 -CPIO archive (\f[I]cpio\f[R]) in the format appropriate for a kernel -initrd -.PP -When a \f[I]GPT\f[R] disk image is created, the following additional -options are available: -.IP \[bu] 2 -A swap partition may be added in -.IP \[bu] 2 -The image may be made bootable on \f[I]EFI\f[R] and \f[I]BIOS\f[R] -systems -.IP \[bu] 2 -Separate partitions for \f[C]/srv\f[R] and \f[C]/home\f[R] may be added -in -.IP \[bu] 2 -The root, \f[C]/srv\f[R] and \f[C]/home\f[R] partitions may optionally -be encrypted with LUKS. -.IP \[bu] 2 -A dm-verity partition may be added in that adds runtime integrity data -for the root partition -.SS Configuration Settings -.PP -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]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] -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, 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]--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] -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 -repositories to use is combined. -Use \[lq]!*\[rq] to remove all repositories from to the list or use -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]<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] -This option is only applicable for RPM-based distributions: -\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 RPM repositories. -By default, a hardcoded set of default RPM 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]RepositoryDirectory\f[B]\f[R], \f[B]\f[CB]--repository-directory\f[B]\f[R] -This option can (for now) only be used with RPM-based istributions and -Arch Linux. -It identifies a directory containing extra repository definitions that -will be used when installing packages. -The files are passed directly to the corresponding package manager and -should be written in the format expected by the package manager of the -image\[cq]s distro. -.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. -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]--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]tar\f[R] (similar, but a tarball of the image is generated), -\f[C]cpio\f[R] (similar, but a cpio archive is generated), -\f[C]gpt_ext4\f[R] (a block device image with an ext4 file system inside -a GPT partition table), \f[C]gpt_xfs\f[R] (similar, but with an xfs file -system), \f[C]gpt_btrfs\f[R] (similar, but with an btrfs file system), -\f[C]gpt_squashfs\f[R] (similar, but with a squashfs file system), -\f[C]plain_squashfs\f[R] (a plain squashfs file system without a -partition table). -.TP -\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]--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]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]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]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 -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 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]--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 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]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. -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]--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]BootProtocols=\f[R] to select support for a different boot -protocol. -.TP -\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]. -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. -If \f[C]uefi\f[R] is specified the \f[C]sd-boot\f[R] UEFI boot loader is -used, if \f[C]bios\f[R] is specified the GNU Grub boot loader is used. -Use \[lq]!*\[rq] to remove all previously added protocols or -\[lq]!protocol\[rq] to remove one protocol. -.TP -\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]. -To remove specific arguments add a space separated list of \[lq]!\[rq] -prefixed arguments. -For example adding \[lq]!* console=ttyS0 rw\[rq] to a -\f[C]mkosi.default\f[R] file or the command line arguments passes -\[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]KernelCommandLine=\f[R] command line arguments. -.TP -\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]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]SecureBoot=\f[R] is used. -.TP -\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]SecureBoot=\f[R] is used. -.TP -\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]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]ReadOnly=\f[B]\f[R], \f[B]\f[CB]--read-only\f[B]\f[R] -Set the read-only flag on the root partition in the partition table. -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 is implied -on \f[C]gpt_squashfs\f[R] and \f[C]plain_squashfs\f[R]. -The read-only flag is essentially a hint to tools using the image (see -https://systemd.io/DISCOVERABLE_PARTITIONS/). -In particular, all systemd tools like \f[C]systemd-nspawn\f[R] and -\f[C]systemd-gpt-auto-generator\f[R] will mount such partitions -read-only, but tools from other project may ignore the flag. -.TP -\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]. -For ext4 this relies on \f[C]resize2fs -M\f[R], which reduces the free -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] -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 -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 -\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. -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] -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. -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], -\f[C]lz4\f[R], \f[C]xz\f[R] or a boolean value as argument. -If the latter is used compression is enabled/disabled and the default -algorithm is used. -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]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]). -\f[C]xz\f[R] compression is used by default. -Note that when applied to block device image types this means the image -cannot be started directly but needs to be decompressed first. -This also means that the \f[C]shell\f[R], \f[C]boot\f[R], \f[C]qemu\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] -Enable compression. -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] -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] -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]. -QCOW2 images can be read natively by \f[C]qemu\f[R], but not by the -Linux kernel. -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] -Set the image\[cq]s hostname to the specified name. -.TP -\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. -The version may also be configured in a file \f[C]mkosi.version\f[R] in -which case it may be conveniently managed via the \f[C]bump\f[R] verb or -the \f[C]--auto-bump\f[R] switch. -When specified the image version is included in the default output file -name, i.e.\ instead of \f[C]image.raw\f[R] the default will be -\f[C]image_0.1.raw\f[R] for version \f[C]0.1\f[R] of the image, and -similar. -The version is also passed via the \f[C]$IMAGE_VERSION\f[R] to any build -scripts invoked (which may be useful to patch it into -\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]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. -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 -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 -scripts invoked (which may be useful to patch it into -\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]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]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. -Currently mkosi uses dracut for all supported distributions except Clear -Linux and this option translates to enabling dracut\[cq]s hostonly -option. -.TP -\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 -every single boot, where \f[C]/etc/\f[R] and \f[C]/var/\f[R] are -populated by \f[C]systemd-tmpfiles\f[R]/\f[C]systemd-sysusers\f[R] and -related calls, or systems that are originally shipped without a root -file system, but where \f[C]systemd-repart\f[R] adds one on the first -boot. -.TP -\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 -files. -This is useful in A/B update scenarios where an existing disk image -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]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]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, 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. -.TP -\f[B]\f[CB]MachineID=\f[B]\f[R], \f[B]\f[CB]--machine-id\f[B]\f[R] -Set the machine\[cq]s ID to the specified value. -If unused, a random ID will be used while building the image and the -final image will be shipped without a machine ID. -.SS [Content] Section -.TP -\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]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 -packages when \f[I]other\f[R] packages are in the list. -For example, \f[C]systemd-udev\f[R] may be automatically included if the -image is bootable and \f[C]systemd\f[R] is installed. -With this, various \[lq]base\[rq] packages still need to be specified if -they should be included, but the corresponding \[lq]extension\[rq] -packages will be added automatically when appropriate. -This feature depends on support in the package manager, so it is not -implemented for all distributions. -.TP -\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 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 -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. -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. -.TP -\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] -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. -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]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 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]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 specified 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]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 -build/prepare/postinstall/finalize scripts are executed with. -Takes a space-separated list of variable assignments or just variable -names. -In the latter case, the values of those variables will be passed through -from the environment in which \f[C]mkosi\f[R] was invoked. -This option may be specified more than once, in which case all listed -variables will be set. -If the same variable is set twice, the later setting overrides the -earlier one. -.TP -\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]SourceFileTransfer=\f[R] to configure how the files are -transferred from the host to the container image. -.TP -\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 -allows the build system to reuse artifacts (such as object files, -executable, \&...) generated on previous invocations. -This directory is mounted into the development image when the build -script is invoked. -The build script can find the path to this directory in the -\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 the \[lq]Files\[rq] -section below). -.TP -\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 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 the \[lq]Files\[rq] -section below). -.TP -\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 -by a previous build and didn\[cq]t change. -The build script can find the path to this directory in the -\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 the \[lq]Files\[rq] -section below). -.TP -\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]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]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]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. -It is the last step before the image is cached (if incremental mode is -enabled). -This script is invoked inside a \f[C]systemd-nspawn\f[R] container -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 -right after copying in the build artifacts generated in the first phase -of the build. -This script is invoked inside a \f[C]systemd-nspawn\f[R] container -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 -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 \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. -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 -\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 -copy only those files \f[C]git ls-files --others\f[R] lists), -\f[C]mount\f[R] to bind mount the source tree directly. -Defaults to \f[C]copy-git-cached\f[R] if a \f[C]git\f[R] source tree is -detected, otherwise \f[C]copy-all\f[R]. -When you specify \f[C]copy-git-more\f[R], it is the same as -\f[C]copy-git-cached\f[R], except it also includes the \f[C].git/\f[R] -directory. -.TP -\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]SourceFileFransfer=\f[R] except -\f[C]mount\f[R]. -By default, sources are not copied into the final image. -.TP -\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]SourceFileTransfer=\f[R] is -\f[C]copy-all\f[R]. -Defaults to leaving them as symbolic links. -.TP -\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]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 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] -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. -.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], -\f[C]M\f[R], \f[C]G\f[R] to indicate kilo-, mega- and gigabytes (all to -the base of 1024). -This applies to output formats \f[C]gpt_ext4\f[R], \f[C]gpt_xfs\f[R], -\f[C]gpt_btrfs\f[R]. -Defaults to 3G. -.TP -\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 256 MB. -.TP -\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]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]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] -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] -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] -Select the \f[C]gpg\f[R] key to use for signing \f[C]SHA256SUMS\f[R]. -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] -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]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]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]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]QemuKvm=\f[B]\f[R], \f[B]\f[CB]--qemu-kvm=\f[B]\f[R] -When used with the \f[C]qemu\f[R] verb, this option specifies whether -QEMU should use KVM acceleration. -Defaults to yes if the host machine supports KVM acceleration, no -otherwise. -.TP -\f[B]\f[CB]NspawnKeepUnit=\f[B]\f[R], \f[B]\f[CB]--nspawn-keep-unit\f[B]\f[R] -When used, this option instructs underlying calls of systemd-nspawn to -use the current unit scope, instead of creating a dedicated transcient -scope unit for the containers. -This option should be used when mkosi is run by a service unit. -.TP -\f[B]\f[CB]Netdev=\f[B]\f[R], \f[B]\f[CB]--netdev\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]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 -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 virtual 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. -\f[C]mkosi\f[R] switches to this directory before doing anything. -Note that the various \f[C]mkosi.*\f[R] files are searched for only -after changing to this directory, hence using this option is an -effective way to build a project located in a specific directory. -.TP -\f[B]\f[CB]--default=\f[B]\f[R] -Loads additional settings from the specified settings file. -Most command line options may also be configured in a settings file. -See the table below to see which command line options match which -settings file option. -If this option is not used, but a file \f[C]mkosi.default\f[R] is found -in the local directory it is automatically used for this purpose. -If a setting is configured both on the command line and in the settings -file, the command line generally wins, except for options taking lists -in which case both lists are combined. -.TP -\f[B]\f[CB]--all\f[B]\f[R], \f[B]\f[CB]-a\f[B]\f[R] -Iterate through all files \f[C]mkosi.*\f[R] in the -\f[C]mkosi.files/\f[R] subdirectory, and build each as if -\f[C]--default=mkosi.files/mkosi.\&...\f[R] was invoked. -This is a quick way to build a large number of images in one go. -Any additional specified command line arguments override the relevant -options in all files processed this way. -.TP -\f[B]\f[CB]--all-directory=\f[B]\f[R] -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. -.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]--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[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]--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 Supported distributions -.PP -Images may be created containing installations of the following -operating systems: -.IP \[bu] 2 -\f[I]Fedora Linux\f[R] -.IP \[bu] 2 -\f[I]Debian\f[R] -.IP \[bu] 2 -\f[I]Ubuntu\f[R] -.IP \[bu] 2 -\f[I]Arch Linux\f[R] -.IP \[bu] 2 -\f[I]openSUSE\f[R] -.IP \[bu] 2 -\f[I]Mageia\f[R] -.IP \[bu] 2 -\f[I]CentOS\f[R] -.IP \[bu] 2 -\f[I]Clear Linux\f[R] -.IP \[bu] 2 -\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 -available. -Specifically, any distribution that packages \f[C]debootstrap\f[R] may -be used to build \f[I]Debian\f[R] or \f[I]Ubuntu\f[R] images. -Any distribution that packages \f[C]dnf\f[R] may be used to build -\f[I]Fedora Linux\f[R], \f[I]Mageia\f[R] or \f[I]OpenMandriva\f[R] -images. -Any distro that packages \f[C]pacstrap\f[R] may be used to build -\f[I]Arch Linux\f[R] images. -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], \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. -.SS Compatibility -.PP -Legacy concepts are avoided: generated images use \f[I]GPT\f[R] disk -labels (and no \f[I]MBR\f[R] labels), and only systemd-based images may -be generated. -.PP -All generated \f[I]GPT\f[R] disk images may be booted in a local -container directly with: -.IP -.nf -\f[C] -systemd-nspawn -bi image.raw -\f[R] -.fi -.PP -Additionally, bootable \f[I]GPT\f[R] disk images (as created with the -\f[C]--bootable\f[R] flag) work when booted directly by \f[I]EFI\f[R] -and \f[I]BIOS\f[R] systems, for example in \f[I]KVM\f[R] via: -.IP -.nf -\f[C] -qemu-kvm -m 512 -smp 2 -bios /usr/share/edk2/ovmf/OVMF_CODE.fd -drive format=raw,file=image.raw -\f[R] -.fi -.PP -\f[I]EFI\f[R] bootable \f[I]GPT\f[R] images are larger than plain -\f[I]GPT\f[R] images, as they additionally carry an \f[I]EFI\f[R] system -partition containing a boot loader, as well as a kernel, kernel modules, -udev and more. -.PP -All directory or btrfs subvolume images may be booted directly with: -.IP -.nf -\f[C] -systemd-nspawn -bD image -\f[R] -.fi -.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, -under the assumption that it is invoked from a \f[I]source\f[R] tree. -Specifically, the following files are used if they exist in the local -directory: -.IP \[bu] 2 -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], \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 -\f[I]source\f[R] tree is enough to get the right image of your choice -set up. -.RS 2 -.PP -Additionally, if a \f[I]\f[CI]mkosi.default.d/\f[I]\f[R] directory -exists, each file in it is loaded in the same manner adding/overriding -the values specified in \f[C]mkosi.default\f[R]. -If \f[C]mkosi.default.d/\f[R] contains a directory named after the -distribution being built, each file in that directory is also processed. -.PP -The file format is inspired by Windows \f[C].ini\f[R] files and supports -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][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 -.IP \[bu] 2 -The \f[B]\f[CB]mkosi.skeleton/\f[B]\f[R] directory or -\f[B]\f[CB]mkosi.skeleton.tar\f[B]\f[R] archive may be used to insert -files into the image. -The files are copied \f[I]before\f[R] the distribution packages are -installed into the image. -This allows creation of files that need to be provided early, for -example to configure the package manager or set systemd presets. -.RS 2 -.PP -When using the directory, file ownership is not preserved: all files -copied will be owned by root. -To preserve ownership, use a tar archive. -.RE -.IP \[bu] 2 -The \f[B]\f[CB]mkosi.extra/\f[B]\f[R] directory or -\f[B]\f[CB]mkosi.extra.tar\f[B]\f[R] archive may be used to insert -additional files into the image, on top of what the distribution -includes in its packages. -They are similar to \f[C]mkosi.skeleton/\f[R] and -\f[C]mkosi.skeleton.tar\f[R], but the files are copied into the -directory tree of the image \f[I]after\f[R] the OS was installed. -.RS 2 -.PP -When using the directory, file ownership is not preserved: all files -copied will be owned by root. -To preserve ownership, use a tar archive. -.RE -.IP \[bu] 2 -\f[B]\f[CB]mkosi.build\f[B]\f[R] may be an executable script. -If it exists, the image will be built twice: the first iteration will be -the \f[I]development\f[R] image, the second iteration will be the -\f[I]final\f[R] image. -The \f[I]development\f[R] image is used to build the project in the -current working directory (the \f[I]source\f[R] tree). -For that the whole directory is copied into the image, along with the -\f[C]mkosi.build\f[R] script. -The script is then invoked inside the image (via -\f[C]systemd-nspawn\f[R]), with \f[C]$SRCDIR\f[R] pointing to the -\f[I]source\f[R] tree. -\f[C]$DESTDIR\f[R] points to a directory where the script should place -any files generated it would like to end up in the \f[I]final\f[R] -image. -Note that \f[C]make\f[R]/\f[C]automake\f[R]/\f[C]meson\f[R] based build -systems generally honor \f[C]$DESTDIR\f[R], thus making it very natural -to build \f[I]source\f[R] trees from the build script. -After the \f[I]development\f[R] image was built and the build script ran -inside of it, it is removed again. -After that the \f[I]final\f[R] image is built, without any -\f[I]source\f[R] tree or build script copied in. -However, this time the contents of \f[C]$DESTDIR\f[R] are added into the -image. -.RS 2 -.PP -When the source tree is copied into the \f[I]build\f[R] image, all files -are copied, except for \f[C]mkosi.builddir/\f[R], \f[C]mkosi.cache/\f[R] -and \f[C]mkosi.output/\f[R]. -That said, \f[C].gitignore\f[R] is respected if the source tree is a -\f[C]git\f[R] checkout. -If multiple different images shall be built from the same source tree it -is essential to exclude their output files from this copy operation, as -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, 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 -passed in. -.RE -.IP \[bu] 2 -The \f[B]\f[CB]mkosi.prepare\f[B]\f[R] script is invoked directly after -the software packages are installed, from within the image context, if -it exists. -It is once called for the \f[I]development\f[R] image (if this is -enabled, see above) with the \[lq]build\[rq] command line parameter, -right before copying the extra tree. -It is called a second time for the \f[I]final\f[R] image with the -\[lq]final\[rq] command line parameter. -This script has network access and may be used to install packages from -other sources than the distro\[cq]s package manager -(e.g.\ \f[C]pip\f[R], \f[C]npm\f[R], \&...), after all software packages -are installed but before the image is cached (if incremental mode is -enabled). -This script is executed within \f[C]$SRCDIR\f[R]. -In contrast to a general purpose installation, it is safe to install -packages to the system (\f[C]pip install\f[R], -\f[C]npm install -g\f[R]) instead of in \f[C]$SRCDIR\f[R] itself -because the build image is only used for a single project and can easily -be thrown away and rebuilt so there\[cq]s no risk of conflicting -dependencies and no risk of polluting the host system. -.IP \[bu] 2 -The \f[B]\f[CB]mkosi.postinst\f[B]\f[R] script is invoked as the -penultimate step of preparing an image, from within the image context, -if it exists. -It is called first for the \f[I]development\f[R] image (if this is -enabled, see above) with the \[lq]build\[rq] command line parameter, -right before invoking the build script. -It is called a second time for the \f[I]final\f[R] image with the -\[lq]final\[rq] command line parameter, right before the image is -considered complete. -This script may be used to alter the images without any restrictions, -after all software packages and built sources have been installed. -Note that this script is executed directly in the image context with the -final root directory in place, without any -\f[C]$SRCDIR\f[R]/\f[C]$DESTDIR\f[R] setup. -.IP \[bu] 2 -The \f[B]\f[CB]mkosi.finalize\f[B]\f[R] script, if it exists, is invoked -as last step of preparing an image, from the host system. -It is once called for the \f[I]development\f[R] image (if this is -enabled, see above) with the \[lq]build\[rq] command line parameter, as -the last step before invoking the build script, after the -\f[C]mkosi.postinst\f[R] script is invoked. -It is called the second time with the \[lq]final\[rq] command line -parameter as the last step before the image is considered complete. -The environment variable \f[C]$BUILDROOT\f[R] points to the root -directory of the installation image. -Additional verbs may be added in the future, the script should be -prepared for that. -This script may be used to alter the images without any restrictions, -after all software packages and built sources have been installed. -This script is more flexible than \f[C]mkosi.postinst\f[R] in two -regards: it has access to the host file system so it\[cq]s easier to -copy in additional files or to modify the image based on external -configuration, and the script is run in the host, so it can be used even -without emulation even if the image has a foreign architecture. -.IP \[bu] 2 -The \f[B]\f[CB]mkosi.mksquashfs-tool\f[B]\f[R] script, if it exists, -will be called wherever \f[C]mksquashfs\f[R] would be called. -.IP \[bu] 2 -The \f[B]\f[CB]mkosi.nspawn\f[B]\f[R] nspawn settings file will be -copied into the same place as the output image file, if it exists. -This is useful since nspawn looks for settings files next to image files -it boots, for additional container runtime settings. -.IP \[bu] 2 -The \f[B]\f[CB]mkosi.cache/\f[B]\f[R] directory, if it exists, is -automatically used as package download cache, in order to speed repeated -runs of the tool. -.IP \[bu] 2 -The \f[B]\f[CB]mkosi.builddir/\f[B]\f[R] directory, if it exists, is -automatically used as out-of-tree build directory, if the build commands -in the \f[C]mkosi.build\f[R] script support it. -Specifically, this directory will be mounted into the build container, -and the \f[C]$BUILDDIR\f[R] environment variable will be set to it when -the build script is invoked. -The build script may then use this directory as build directory, for -automake-style or ninja-style out-of-tree builds. -This speeds up builds considerably, in particular when \f[C]mkosi\f[R] -is used in incremental mode (\f[C]-i\f[R]): not only the disk images, -but also the build tree is reused between subsequent invocations. -Note that if this directory does not exist the \f[C]$BUILDDIR\f[R] -environment variable is not set, and it is up to build script to decide -whether to do in in-tree or an out-of-tree build, and which build -directory to use. -.IP \[bu] 2 -The \f[B]\f[CB]mkosi.includedir/\f[B]\f[R] directory, if it exists, is -automatically used as an out-of-tree include directory for header files. -Specifically, it will be mounted in the build container at -\f[C]/usr/include/\f[R] when building the build image and when running -the build script. -After building the (cached) build image, this directory will contain all -the files installed to \f[C]/usr/include\f[R]. -Language servers or other tools can use these files to provide a better -editing experience for developers working on a project. -.IP \[bu] 2 -The \f[B]\f[CB]mkosi.installdir/\f[B]\f[R] directory, if it exists, is -automatically used as the install directory. -Specifically, this directory will be mounted into the container at -\f[C]/root/dest\f[R] when running the build script. -After running the build script, the contents of this directory are -installed into the final image. -This is useful to cache the install step of the build. -If used, subsequent builds will only have to reinstall files that have -changed since the previous build. -.IP \[bu] 2 -The \f[B]\f[CB]mkosi.rootpw\f[B]\f[R] file can be used to provide the -password or hashed password (if \f[C]--password-is-hashed\f[R] is set) -for the root user of the image. -The password may optionally be followed by a newline character which is -implicitly removed. -The file must have an access mode of 0600 or less. -If this file does not exist, the distribution\[cq]s default root -password is set (which usually means access to the root user is -blocked). -.IP \[bu] 2 -The \f[B]\f[CB]mkosi.passphrase\f[B]\f[R] file provides the passphrase -to use when LUKS encryption is selected. -It should contain the passphrase literally, and not end in a newline -character (i.e.\ in the same format as cryptsetup and -\f[C]/etc/crypttab\f[R] expect the passphrase files). -The file must have an access mode of 0600 or less. -If this file does not exist and encryption is requested, the user is -queried instead. -.IP \[bu] 2 -The \f[B]\f[CB]mkosi.secure-boot.crt\f[B]\f[R] and -\f[B]\f[CB]mkosi.secure-boot.key\f[B]\f[R] files contain an X.509 -certificate and PEM private key to use when UEFI SecureBoot support is -enabled. -All EFI binaries included in the image\[cq]s ESP are signed with this -key, as a late step in the build process. -.IP \[bu] 2 -The \f[B]\f[CB]mkosi.output/\f[B]\f[R] directory will be used for all -build artifacts, if the image output path is not configured (i.e.\ no -\f[C]--output=\f[R] setting specified), or configured to a filename -(i.e.\ a path containing no \f[C]/\f[R] character). -This includes the image itself, the root hash file in case Verity is -used, the checksum and its signature if that\[cq]s enabled, and the -nspawn settings file if there is any. -Note that this directory is not used if the image output path contains -at least one slash, and has no effect in that case. -This setting is particularly useful if multiple different images shall -be built from the same working directory, as otherwise the build result -of a preceding run might be copied into a build image as part of the -source tree (see above). -.IP \[bu] 2 -The \f[B]\f[CB]mkosi.reposdir/\f[B]\f[R] directory, if it exists, is -automatically used as the repository directory for extra repository -files. -See the \f[C]RepositoryDirectory\f[R] option for more information. -.PP -All these files are optional. -.PP -Note that the location of all these files may also be configured during -invocation via command line switches, and as settings in -\f[C]mkosi.default\f[R], in case the default settings are not acceptable -for a project. -.SH BUILD PHASES -.PP -If no build script \f[C]mkosi.build\f[R] (see above) is used the build -consists of a single phase only: the final image is generated as the -combination of \f[C]mkosi.skeleton/\f[R] (see above), the unpacked -distribution packages and \f[C]mkosi.extra/\f[R]. -.PP -If a build script \f[C]mkosi.build\f[R] is used the build consists of -two phases: in the the first \f[C]development\f[R] phase an image that -includes necessary build tools (i.e.\ the combination of -\f[C]Packages=\f[R] and \f[C]BuildPackages=\f[R] is installed) is -generated (i.e.\ the combination of \f[C]mkosi.skeleton/\f[R] and -unpacked distribution packages). -Into this image the source tree is copied and \f[C]mkosi.build\f[R] -executed. -The artifacts the \f[C]mkosi.build\f[R] generates are saved. -Then, the second \f[C]final\f[R] phase starts: an image that excludes -the build tools (i.e.\ only \f[C]Packages=\f[R] is installed, -\f[C]BuildPackages=\f[R] is not) is generated. -This time the build artifacts saved from the first phase are copied in, -and \f[C]mkosi.extra\f[R] copied on top, thus generating the final -image. -.PP -The two-phased approach ensures that source tree is executed in a clean -and comprehensive environment, while at the same the final image remains -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] 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. -.SH CACHING -.PP -\f[C]mkosi\f[R] supports three different caches for speeding up -repetitive re-building of images. -Specifically: -.IP "1." 3 -The package cache of the distribution package manager may be cached -between builds. -This is configured with the \f[C]--cache=\f[R] option or the -\f[C]mkosi.cache/\f[R] directory. -This form of caching relies on the distribution\[cq]s package manager, -and caches distribution packages (RPM, DEB, \&...) after they are -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], 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 -image). -This form of caching allows bypassing the time-consuming package -unpacking step of the distribution package managers, but is only -effective if the list of packages to use remains stable, but the build -sources and its scripts change regularly. -Note that this cache requires manual flushing: whenever the package list -is modified the cached images need to be explicitly removed before the -next re-build, using the \f[C]-f\f[R] switch. -.IP "3." 3 -Finally, between multiple builds the build artifact directory may be -shared, using the \f[C]mkosi.builddir/\f[R] directory. -This directory allows build systems such as Meson to reuse already -compiled sources from a previous built, thus speeding up the build -process of the \f[C]mkosi.build\f[R] build script. -.PP -The package cache (i.e.\ the first item above) is unconditionally -useful. -The latter two caches only apply to uses of \f[C]mkosi\f[R] with a -source tree and build script. -When all three are enabled together turn-around times for complete image -builds are minimal, as only changed source files need to be recompiled: -an OS image rebuilt will be almost as quick to build the source tree -only. -.SH ENVIRONMENT VARIABLES -.PP -The build script \f[C]mkosi.build\f[R] receives the following -environment variables: -.IP \[bu] 2 -\f[C]$SRCDIR\f[R] contains the path to the sources to build. -.IP \[bu] 2 -\f[C]$DESTDIR\f[R] is a directory into which any artifacts generated by -the build script shall be placed. -.IP \[bu] 2 -\f[C]$BUILDDIR\f[R] is only defined if \f[C]mkosi.builddir\f[R] and -points to the build directory to use. -This is useful for all build systems that support out-of-tree builds to -reuse already built artifacts from previous runs. -.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 -(\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 -(\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 -(\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 -.PP -Create and run a raw \f[I]GPT\f[R] image with \f[I]ext4\f[R], as -\f[C]image.raw\f[R]: -.IP -.nf -\f[C] -# mkosi --bootable --incremental boot -\f[R] -.fi -.PP -Create and run a bootable btrfs \f[I]GPT\f[R] image, as -\f[C]foobar.raw\f[R]: -.IP -.nf -\f[C] -# mkosi --format gpt_btrfs --bootable -o foobar.raw -# mkosi --output foobar.raw boot -# mkosi --output foobar.raw qemu -\f[R] -.fi -.PP -Create and run a \f[I]Fedora Linux\f[R] image into a plain directory: -.IP -.nf -\f[C] -# mkosi --distribution fedora --format directory boot -\f[R] -.fi -.PP -Create a compressed image \f[C]image.raw.xz\f[R] and add a checksum -file, and install \f[I]SSH\f[R] into it: -.IP -.nf -\f[C] -# mkosi --distribution fedora --format gpt_squashfs --checksum --compress --package=openssh-clients -\f[R] -.fi -.PP -Inside the source directory of an \f[C]automake\f[R]-based project, -configure \f[I]mkosi\f[R] so that simply invoking \f[C]mkosi\f[R] -without any parameters builds an OS image containing a built version of -the project in its current state: -.IP -.nf -\f[C] -# cat >mkosi.default <<EOF -[Distribution] -Distribution=fedora -Release=24 - -[Output] -Format=gpt_btrfs -Bootable=yes - -[Content] -Packages=openssh-clients,httpd -BuildPackages=make,gcc,libcurl-devel -EOF -# cat >mkosi.build <<EOF -#!/bin/sh -cd $SRCDIR -\&./autogen.sh -\&./configure --prefix=/usr -make -j \[ga]nproc\[ga] -make install -EOF -# chmod +x mkosi.build -# mkosi --bootable --incremental boot -# systemd-nspawn -bi image.raw -\f[R] -.fi -.PP -To create a \f[I]Fedora Linux\f[R] image with hostname: -.IP -.nf -\f[C] -# mkosi --distribution fedora --hostname image -\f[R] -.fi -.PP -Also you could set hostname in configuration file: -.IP -.nf -\f[C] -# cat mkosi.default -\&... -[Output] -Hostname=image -\&... -\f[R] -.fi -.SH REQUIREMENTS -.PP -mkosi is packaged for various distributions: Debian, Ubuntu, Arch Linux, -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 -it). -.PP -When not using distribution packages make sure to install the necessary -dependencies. -For example, on \f[I]Fedora Linux\f[R] you need: -.IP -.nf -\f[C] -dnf install arch-install-scripts btrfs-progs debootstrap dosfstools edk2-ovmf e2fsprogs squashfs-tools gnupg python3 tar veritysetup xfsprogs xz zypper sbsigntools -\f[R] -.fi -.PP -On Debian/Ubuntu it might be necessary to install the -\f[C]ubuntu-keyring\f[R], \f[C]ubuntu-archive-keyring\f[R] and/or -\f[C]debian-archive-keyring\f[R] packages explicitly, in addition to -\f[C]debootstrap\f[R], depending on what kind of distribution images you -want to build. -\f[C]debootstrap\f[R] on Debian only pulls in the Debian keyring on its -own, and the version on Ubuntu only the one from Ubuntu. -.PP -Note that the minimum required Python version is 3.7. -.SH REFERENCES -.IP \[bu] 2 -Primary mkosi git repository on -GitHub (https://github.com/systemd/mkosi/) -.IP \[bu] 2 -mkosi \[em] A Tool for Generating OS -Images (http://0pointer.net/blog/mkosi-a-tool-for-generating-os-images.html) -introductory blog post by Lennart Poettering -.IP \[bu] 2 -The mkosi OS generation tool (https://lwn.net/Articles/726655/) story on -LWN -.SH SEE ALSO -.PP -\f[C]systemd-nspawn(1)\f[R], \f[C]dnf(8)\f[R], \f[C]debootstrap(8)\f[R] -.SH AUTHORS -The mkosi Authors. |