From: Daan De Meyer Date: Sat, 6 May 2023 11:45:13 +0000 (+0200) Subject: Fix sections for a number of settings X-Git-Tag: v15~177^2~10 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d2875feb77f330bfe67178a6e3b36c014c47cda7;p=thirdparty%2Fmkosi.git Fix sections for a number of settings Let's move a bunch of settings to a section that makes more sense for them. No functional change, just moving stuff around. --- diff --git a/mkosi.md b/mkosi.md index 520276ca6..a950ed7d3 100644 --- a/mkosi.md +++ b/mkosi.md @@ -122,6 +122,82 @@ The following command line verbs are known: : 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. @@ -419,38 +495,6 @@ a boolean argument: either "1", "yes", or "true" to enable, or "0", `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. - - - -`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 @@ -461,43 +505,6 @@ a boolean argument: either "1", "yes", or "true" to enable, or "0", 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 @@ -627,6 +634,31 @@ a boolean argument: either "1", "yes", or "true" to enable, or "0", 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 @@ -789,15 +821,6 @@ a boolean argument: either "1", "yes", or "true" to enable, or "0", 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 @@ -847,6 +870,29 @@ a boolean argument: either "1", "yes", or "true" to enable, or "0", ### [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 @@ -863,6 +909,32 @@ a boolean argument: either "1", "yes", or "true" to enable, or "0", ### [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 diff --git a/mkosi/__init__.py b/mkosi/__init__.py index 032ca1054..36eb204cc 100644 --- a/mkosi/__init__.py +++ b/mkosi/__init__.py @@ -1229,7 +1229,6 @@ def print_summary(args: MkosiArgs, config: MkosiConfig) -> None: 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} @@ -1238,30 +1237,24 @@ def print_summary(args: MkosiArgs, config: MkosiConfig) -> None: 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)} @@ -1270,7 +1263,9 @@ def print_summary(args: MkosiArgs, config: MkosiConfig) -> None: 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)} @@ -1281,6 +1276,8 @@ def print_summary(args: MkosiArgs, config: MkosiConfig) -> None: 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)} """ @@ -1289,6 +1286,9 @@ def print_summary(args: MkosiArgs, config: MkosiConfig) -> None: 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}) diff --git a/mkosi/config.py b/mkosi/config.py index 317dd7a6c..de2f0b55d 100644 --- a/mkosi/config.py +++ b/mkosi/config.py @@ -797,57 +797,23 @@ class MkosiConfigParser: 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", @@ -869,11 +835,6 @@ class MkosiConfigParser: section="Output", parse=config_parse_boolean, ), - MkosiConfigSetting( - dest="incremental", - section="Output", - parse=config_parse_boolean, - ), MkosiConfigSetting( dest="split_artifacts", section="Output", @@ -917,6 +878,12 @@ class MkosiConfigParser: 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", @@ -1006,13 +973,6 @@ class MkosiConfigParser: 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", @@ -1085,6 +1045,34 @@ class MkosiConfigParser: 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", @@ -1099,6 +1087,18 @@ class MkosiConfigParser: 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", @@ -1448,43 +1448,6 @@ class MkosiConfigParser: 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", @@ -1501,13 +1464,6 @@ class MkosiConfigParser: 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", @@ -1574,6 +1530,12 @@ class MkosiConfigParser: 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", @@ -1670,13 +1632,6 @@ class MkosiConfigParser: 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", @@ -1766,6 +1721,37 @@ class MkosiConfigParser: ) 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", @@ -1783,6 +1769,20 @@ class MkosiConfigParser: 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",