: This verb is equivalent to the `--help` switch documented below: it
shows a brief usage explanation.
+## Commandline-only Options
+
+Those settings cannot be configured in the configuration files.
+
+`--force`, `-f`
+
+: Replace the output file if it already exists, when building an
+ image. By default when building an image and an output artifact
+ already exists `mkosi` 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 "Files" section below),
+ specifying this option thrice will ensure the package cache is
+ removed too, before the re-build is initiated. For the `clean`
+ 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.
+
+`--directory=`, `-C`
+
+: Takes a path to a directory. `mkosi` switches to this directory
+ before doing anything. Note that the various `mkosi.*` 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.
+
+`--config=`
+
+: 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
+ `mkosi.conf` 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.
+
+`--debug=`
+
+: Enable additional debugging output.
+
+`--debug-shell=`
+
+: When executing a command in the image fails, mkosi will start an interactive
+ shell in the image allowing further debugging.
+
+`--version`
+
+: Show package version.
+
+`--help`, `-h`
+
+: Show brief usage information.
+
+`--genkey-common-name=`
+
+: Common name to be used when generating keys via mkosi's `genkey` command. Defaults to `mkosi of %u`, where
+ `%u` expands to the username of the user invoking mkosi.
+
+`--genkey-valid-days=`
+
+: Number of days that the keys should remain valid when generating keys via mkosi's `genkey` command.
+ Defaults to two years (730 days).
+
+`--auto-bump=`, `-B`
+
+: If specified, after each successful build the the version is bumped
+ in a fashion equivalent to the `bump` 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.
+
## Execution Flow
Execution flow for `mkosi build`. Default values/calls are shown in parentheses.
`mkosi.installdir` exists in the local directory, it is automatically
used for this purpose (also see the "Files" section below).
-`Force=`, `--force`, `-f`
-
-: Replace the output file if it already exists, when building an
- image. By default when building an image and an output artifact
- already exists `mkosi` 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 "Files" section below),
- specifying this option thrice will ensure the package cache is
- removed too, before the re-build is initiated. For the `clean`
- 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.
-
- <!-- FIXME: allow `Force=<n>` -->
-
-`Bootable=`, `--bootable=`
-
-: Takes a boolean or `auto`. Enables or disables generation of a bootable
- image. If enabled, mkosi will install systemd-boot, run kernel-install,
- generate unified kernel images for installed kernels and add an ESP
- partition when the disk image output is used. If systemd-boot is not
- installed or no kernel images can be found, the build will fail. `auto`
- behaves as if the option was enabled, but the build won't fail if either
- no kernel images or systemd-boot can't be found. If disabled, systemd-boot
- won't be installed even if found inside the image, kernel-install won't be
- executed, no unified kernel images will be generated and no ESP partition
- will be added to the image if the disk output format is used.
-
`UseSubvolumes=`, `--use-subvolumes=`
: Takes a boolean or `auto`. Enables or disables use of btrfs subvolumes for
created, an error is raised. If `auto`, missing `btrfs` or failures to
create subvolumes are ignored.
-`KernelCommandLine=`, `--kernel-command-line=`
-
-: Use the specified kernel command line when building images. By default
- command line arguments get appended. To remove all arguments from the
- current list pass "!\*". To remove specific arguments add a space
- separated list of "!" prefixed arguments. For example adding
- "!\* console=ttyS0 rw" to a `mkosi.conf` file or the command line
- arguments passes "console=ttyS0 rw" to the kernel in any case. Just
- adding "console=ttyS0 rw" would append these two arguments to the kernel
- command line created by lower priority configuration files or previous
- `KernelCommandLine=` command line arguments.
-
-`SecureBoot=`, `--secure-boot`
-
-: Sign the resulting kernel/initrd image for UEFI SecureBoot.
-
-`SecureBootKey=`, `--secure-boot-key=`
-
-: Path to the PEM file containing the secret key for signing the
- UEFI kernel image, if `SecureBoot=` is used.
-
-`SecureBootCertificate=`, `--secure-boot-certificate=`
-
-: Path to the X.509 file containing the certificate for the signed
- UEFI kernel image, if `SecureBoot=` is used.
-
-[//]: # (Please add external tools to the list here.)
-
-`SignExpectedPCR=`, `--sign-expected-pcr`
-
-: Measure the components of the unified kernel image (UKI) using
- `systemd-measure` and embed the PCR signature into the unified kernel
- image. This option takes a boolean value or the special value `auto`,
- which is the default, which is equal to a true value if the
- [`cryptography`](https://cryptography.io/) module is importable and
- the `systemd-measure` binary is in `PATH`.
-
`CompressOutput=`, `--compress-output=`
: Configure compression for the resulting image or archive. The
normally run during the source build process. Note that this option
has no effect unless the `mkosi.build` build script honors it.
+`Bootable=`, `--bootable=`
+
+: Takes a boolean or `auto`. Enables or disables generation of a bootable
+ image. If enabled, mkosi will install systemd-boot, run kernel-install,
+ generate unified kernel images for installed kernels and add an ESP
+ partition when the disk image output is used. If systemd-boot is not
+ installed or no kernel images can be found, the build will fail. `auto`
+ behaves as if the option was enabled, but the build won't fail if either
+ no kernel images or systemd-boot can't be found. If disabled, systemd-boot
+ won't be installed even if found inside the image, kernel-install won't be
+ executed, no unified kernel images will be generated and no ESP partition
+ will be added to the image if the disk output format is used.
+
+`KernelCommandLine=`, `--kernel-command-line=`
+
+: Use the specified kernel command line when building images. By default
+ command line arguments get appended. To remove all arguments from the
+ current list pass "!\*". To remove specific arguments add a space
+ separated list of "!" prefixed arguments. For example adding
+ "!\* console=ttyS0 rw" to a `mkosi.conf` file or the command line
+ arguments passes "console=ttyS0 rw" to the kernel in any case. Just
+ adding "console=ttyS0 rw" would append these two arguments to the kernel
+ command line created by lower priority configuration files or previous
+ `KernelCommandLine=` command line arguments.
+
`BaseTrees=`, `--base-tree=`
: Takes a colon separated pair of directories to use as base images. When
reproducibility, as long as the package data cache is already fully
populated.
-`Settings=`, `--settings=`
-
-: Specifies a `.nspawn` settings file for `systemd-nspawn` to use in
- the `boot` and `shell` verbs, and to place next to the generated
- image file. This is useful to configure the `systemd-nspawn`
- environment when the image is run. If this setting is not used but
- an `mkosi.nspawn` file found in the local directory it is
- automatically used for this purpose.
-
`Initrd=`, `--initrd`
: Use user-provided initrd(s). Takes a comma separated list of paths to initrd
### [Validation] Section
+`SecureBoot=`, `--secure-boot`
+
+: Sign the resulting kernel/initrd image for UEFI SecureBoot.
+
+`SecureBootKey=`, `--secure-boot-key=`
+
+: Path to the PEM file containing the secret key for signing the
+ UEFI kernel image, if `SecureBoot=` is used.
+
+`SecureBootCertificate=`, `--secure-boot-certificate=`
+
+: Path to the X.509 file containing the certificate for the signed
+ UEFI kernel image, if `SecureBoot=` is used.
+
+`SignExpectedPCR=`, `--sign-expected-pcr`
+
+: Measure the components of the unified kernel image (UKI) using
+ `systemd-measure` and embed the PCR signature into the unified kernel
+ image. This option takes a boolean value or the special value `auto`,
+ which is the default, which is equal to a true value if the
+ [`cryptography`](https://cryptography.io/) module is importable and
+ the `systemd-measure` binary is in `PATH`.
+
`Checksum=`, `--checksum`
: Generate a `SHA256SUMS` file of all generated artifacts after the
### [Host] Section
+`Incremental=`, `--incremental=`, `-i`
+
+: Enable incremental build mode. This only applies if the two-phase
+ `mkosi.build` 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 `mkosi.build` script is invoked in the
+ development container. Similarly, a copy of the final image is
+ created immediately before the build artifacts from the
+ `mkosi.build` script are copied in. On subsequent invocations of
+ `mkosi` with the `-i` 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 `Packages=` are modified. In order to force
+ rebuilding of these cached images, combine `-i` with `-ff` to ensure
+ cached images are first removed and then re-created.
+
+`NSpawnSettings=`, `--settings=`
+
+: Specifies a `.nspawn` settings file for `systemd-nspawn` to use in
+ the `boot` and `shell` verbs, and to place next to the generated
+ image file. This is useful to configure the `systemd-nspawn`
+ environment when the image is run. If this setting is not used but
+ an `mkosi.nspawn` file found in the local directory it is
+ automatically used for this purpose.
+
`ExtraSearchPaths=`, `--extra-search-path=`
: List of colon-separated paths to look for tools in, before using the
Local Mirror (build): {none_to_none(config.local_mirror)}
Repo Signature/Key check: {yes_no(config.repository_key_check)}
Repositories: {",".join(config.repositories)}
- Initrds: {",".join(os.fspath(p) for p in config.initrds)}
{bold("OUTPUT")}:
Image ID: {config.image_id}
Manifest Formats: {maniformats}
Output Directory: {none_to_default(config.output_dir)}
Workspace Directory: {none_to_default(config.workspace_dir)}
+ Cache Directory: {none_to_none(config.cache_dir)}
+ Build Directory: {none_to_none(config.build_dir)}
+ Install Directory: {none_to_none(config.install_dir)}
Output: {bold(config.output_with_compression)}
Output Checksum: {none_to_na(config.output_checksum if config.checksum else None)}
Output Signature: {none_to_na(config.output_signature if config.sign else None)}
Output nspawn Settings: {none_to_na(config.output_nspawn_settings if config.nspawn_settings is not None else None)}
- Incremental: {yes_no(config.incremental)}
Compression: {config.compress_output.name}
- Bootable: {yes_no_auto(config.bootable)}
- Kernel Command Line: {" ".join(config.kernel_command_line)}
- UEFI SecureBoot: {yes_no(config.secure_boot)}
- SecureBoot Sign Key: {none_to_none(config.secure_boot_key)}
- SecureBoot Certificate: {none_to_none(config.secure_boot_certificate)}
{bold("CONTENT")}:
Packages: {line_join_list(config.packages)}
With Documentation: {yes_no(config.with_docs)}
- Package Cache: {none_to_none(config.cache_dir)}
Skeleton Trees: {line_join_source_target_list(config.skeleton_trees)}
Extra Trees: {line_join_source_target_list(config.extra_trees)}
Clean Package Metadata: {yes_no_auto(config.clean_package_metadata)}
Remove Files: {line_join_list(config.remove_files)}
Remove Packages: {line_join_list(config.remove_packages)}
Build Sources: {config.build_sources}
- Build Directory: {none_to_none(config.build_dir)}
- Install Directory: {none_to_none(config.install_dir)}
Build Packages: {line_join_list(config.build_packages)}
Build Script: {path_or_none(config.build_script, check_script_input)}
Run Tests in Build Script: {yes_no(config.with_tests)}
Finalize Script: {path_or_none(config.finalize_script, check_script_input)}
Script Environment: {line_join_list(env)}
Scripts with network: {yes_no(config.with_network)}
- nspawn Settings: {none_to_none(config.nspawn_settings)}
+ Bootable: {yes_no_auto(config.bootable)}
+ Kernel Command Line: {" ".join(config.kernel_command_line)}
+ Initrds: {",".join(os.fspath(p) for p in config.initrds)}
Locale: {none_to_default(config.locale)}
Locale Messages: {none_to_default(config.locale_messages)}
Keymap: {none_to_default(config.keymap)}
Autologin: {yes_no(config.autologin)}
{bold("HOST CONFIGURATION")}:
+ Incremental: {yes_no(config.incremental)}
+ NSpawn Settings: {none_to_none(config.nspawn_settings)}
Extra search paths: {line_join_list(config.extra_search_paths)}
QEMU Extra Arguments: {line_join_list(config.qemu_args)}
"""
summary += f"""\
{bold("VALIDATION")}:
+ UEFI SecureBoot: {yes_no(config.secure_boot)}
+ SecureBoot Sign Key: {none_to_none(config.secure_boot_key)}
+ SecureBoot Certificate: {none_to_none(config.secure_boot_certificate)}
Checksum: {yes_no(config.checksum)}
Sign: {yes_no(config.sign)}
GPG Key: ({"default" if config.key is None else config.key})
MkosiConfigSetting(
dest="cache_dir",
name="CacheDirectory",
- section="Content",
+ section="Output",
parse=config_make_path_parser(required=False),
paths=("mkosi.cache",),
),
MkosiConfigSetting(
dest="build_dir",
name="BuildDirectory",
- section="Content",
+ section="Output",
parse=config_make_path_parser(required=False),
paths=("mkosi.builddir",),
),
MkosiConfigSetting(
dest="install_dir",
name="InstallDirectory",
- section="Content",
- parse=config_make_path_parser(required=False),
- paths=("mkosi.installdir",),
- ),
- MkosiConfigSetting(
- dest="kernel_command_line",
- section="Output",
- parse=config_make_list_parser(delimiter=" "),
- default=["console=ttyS0"],
- ),
- MkosiConfigSetting(
- dest="secure_boot",
- section="Output",
- parse=config_parse_boolean,
- ),
- MkosiConfigSetting(
- dest="secure_boot_key",
- section="Output",
- parse=config_make_path_parser(),
- paths=("mkosi.key",),
- ),
- MkosiConfigSetting(
- dest="secure_boot_certificate",
- section="Output",
- parse=config_make_path_parser(),
- paths=("mkosi.crt",),
- ),
- MkosiConfigSetting(
- dest="sign_expected_pcr",
- section="Output",
- parse=config_parse_feature,
- ),
- MkosiConfigSetting(
- dest="passphrase",
section="Output",
parse=config_make_path_parser(required=False),
- paths=("mkosi.passphrase",),
+ paths=("mkosi.installdir",),
),
MkosiConfigSetting(
dest="compress_output",
section="Output",
parse=config_parse_boolean,
),
- MkosiConfigSetting(
- dest="incremental",
- section="Output",
- parse=config_parse_boolean,
- ),
MkosiConfigSetting(
dest="split_artifacts",
section="Output",
parse=config_parse_boolean,
default=True,
),
+ MkosiConfigSetting(
+ dest="kernel_command_line",
+ section="Content",
+ parse=config_make_list_parser(delimiter=" "),
+ default=["console=ttyS0"],
+ ),
MkosiConfigSetting(
dest="bootable",
section="Content",
section="Content",
parse=config_parse_boolean,
),
- MkosiConfigSetting(
- dest="nspawn_settings",
- name="NSpawnSettings",
- section="Content",
- parse=config_make_path_parser(),
- paths=("mkosi.nspawn",),
- ),
MkosiConfigSetting(
dest="initrds",
section="Content",
section="Content",
parse=config_parse_string,
),
+ MkosiConfigSetting(
+ dest="secure_boot",
+ section="Validation",
+ parse=config_parse_boolean,
+ ),
+ MkosiConfigSetting(
+ dest="secure_boot_key",
+ section="Validation",
+ parse=config_make_path_parser(),
+ paths=("mkosi.key",),
+ ),
+ MkosiConfigSetting(
+ dest="secure_boot_certificate",
+ section="Validation",
+ parse=config_make_path_parser(),
+ paths=("mkosi.crt",),
+ ),
+ MkosiConfigSetting(
+ dest="sign_expected_pcr",
+ section="Validation",
+ parse=config_parse_feature,
+ ),
+ MkosiConfigSetting(
+ dest="passphrase",
+ section="Validation",
+ parse=config_make_path_parser(required=False),
+ paths=("mkosi.passphrase",),
+ ),
MkosiConfigSetting(
dest="checksum",
section="Validation",
dest="key",
section="Validation",
),
+ MkosiConfigSetting(
+ dest="incremental",
+ section="Host",
+ parse=config_parse_boolean,
+ ),
+ MkosiConfigSetting(
+ dest="nspawn_settings",
+ name="NSpawnSettings",
+ section="Host",
+ parse=config_make_path_parser(),
+ paths=("mkosi.nspawn",),
+ ),
MkosiConfigSetting(
dest="extra_search_paths",
section="Host",
help="Path to use as persistent install directory",
action=action,
)
- group.add_argument(
- "--kernel-command-line",
- metavar="OPTIONS",
- help="Set the kernel command line (only bootable images)",
- action=action,
- )
- group.add_argument(
- "--secure-boot",
- metavar="BOOL",
- help="Sign the resulting kernel/initrd image for UEFI SecureBoot",
- nargs="?",
- action=action,
- )
- group.add_argument(
- "--secure-boot-key",
- metavar="PATH",
- help="UEFI SecureBoot private key in PEM format",
- action=action,
- )
- group.add_argument(
- "--secure-boot-certificate",
- metavar="PATH",
- help="UEFI SecureBoot certificate in X509 format",
- action=action,
- )
- group.add_argument(
- "--sign-expected-pcr",
- metavar="FEATURE",
- help="Measure the components of the unified kernel image (UKI) and embed the PCR signature into the UKI",
- action=action,
- )
- group.add_argument(
- "--passphrase",
- metavar="PATH",
- help="Path to a file containing the passphrase to use when LUKS encryption is selected",
- action=action,
- )
group.add_argument(
"--compress-output",
metavar="ALG",
nargs="?",
action=action,
)
- group.add_argument(
- "-i", "--incremental",
- metavar="BOOL",
- help="Make use of and generate intermediary cache images",
- nargs="?",
- action=action,
- )
group.add_argument(
"--split-artifacts",
metavar="BOOL",
nargs="?",
action=action,
)
+ group.add_argument(
+ "--kernel-command-line",
+ metavar="OPTIONS",
+ help="Set the kernel command line (only bootable images)",
+ action=action,
+ )
group.add_argument(
"--autologin",
metavar="BOOL",
help="Only use the package cache when installing packages",
action=action,
)
- group.add_argument(
- "--settings",
- metavar="PATH",
- help="Add in .nspawn settings file",
- dest="nspawn_settings",
- action=action,
- )
group.add_argument(
"--initrd",
help="Add a user-provided initrd to image",
)
group = parser.add_argument_group("Validation options")
+ group.add_argument(
+ "--secure-boot",
+ metavar="BOOL",
+ help="Sign the resulting kernel/initrd image for UEFI SecureBoot",
+ nargs="?",
+ action=action,
+ )
+ group.add_argument(
+ "--secure-boot-key",
+ metavar="PATH",
+ help="UEFI SecureBoot private key in PEM format",
+ action=action,
+ )
+ group.add_argument(
+ "--secure-boot-certificate",
+ metavar="PATH",
+ help="UEFI SecureBoot certificate in X509 format",
+ action=action,
+ )
+ group.add_argument(
+ "--sign-expected-pcr",
+ metavar="FEATURE",
+ help="Measure the components of the unified kernel image (UKI) and embed the PCR signature into the UKI",
+ action=action,
+ )
+ group.add_argument(
+ "--passphrase",
+ metavar="PATH",
+ help="Path to a file containing the passphrase to use when LUKS encryption is selected",
+ action=action,
+ )
group.add_argument(
"--checksum",
metavar="BOOL",
group.add_argument("--key", help="GPG key to use for signing", action=action)
group = parser.add_argument_group("Host configuration options")
+ group.add_argument(
+ "-i", "--incremental",
+ metavar="BOOL",
+ help="Make use of and generate intermediary cache images",
+ nargs="?",
+ action=action,
+ )
+ group.add_argument(
+ "--settings",
+ metavar="PATH",
+ help="Add in .nspawn settings file",
+ dest="nspawn_settings",
+ action=action,
+ )
group.add_argument(
"--extra-search-path",
help="List of colon-separated paths to look for programs before looking in PATH",
projects / thirdparty / mkosi.git / commitdiff
