From 103434fcae086a72a8e37c1bfa489115a5cef6ec Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Thu, 12 Dec 2024 15:08:23 +0000 Subject: [PATCH] install: Lift `hide=true` from `install ensure-completion` While this has obscure use cases right now, we will need to support it for the forseeable future, so just lift its `hide=true` state so it's clear that it exists. Update the generated man pages. Signed-off-by: Colin Walters --- docs/src/man/bootc-container-lint.md | 2 +- docs/src/man/bootc-container.md | 2 +- docs/src/man/bootc-edit.md | 2 +- .../man/bootc-install-ensure-completion.md | 30 +++++++++++++++++++ .../man/bootc-install-print-configuration.md | 2 +- docs/src/man/bootc-install-to-disk.md | 19 ++++++++++-- .../src/man/bootc-install-to-existing-root.md | 25 ++++++++++++---- docs/src/man/bootc-install-to-filesystem.md | 18 +++++++++-- docs/src/man/bootc-install.md | 9 ++++-- docs/src/man/bootc-rollback.md | 2 +- docs/src/man/bootc-status.md | 6 ++-- docs/src/man/bootc-switch.md | 4 +-- docs/src/man/bootc-upgrade.md | 2 +- docs/src/man/bootc-usr-overlay.md | 8 ++--- docs/src/man/bootc.md | 2 +- lib/src/cli.rs | 1 - 16 files changed, 105 insertions(+), 29 deletions(-) create mode 100644 docs/src/man/bootc-install-ensure-completion.md diff --git a/docs/src/man/bootc-container-lint.md b/docs/src/man/bootc-container-lint.md index d0d290ed6..43d9897e9 100644 --- a/docs/src/man/bootc-container-lint.md +++ b/docs/src/man/bootc-container-lint.md @@ -23,4 +23,4 @@ part of a build process; it will error if any problems are detected. # VERSION -v1.1.0 +v1.1.2 diff --git a/docs/src/man/bootc-container.md b/docs/src/man/bootc-container.md index b7a3516de..1c91bf0d8 100644 --- a/docs/src/man/bootc-container.md +++ b/docs/src/man/bootc-container.md @@ -30,4 +30,4 @@ bootc-container-help(8) # VERSION -v1.1.0 +v1.1.2 diff --git a/docs/src/man/bootc-edit.md b/docs/src/man/bootc-edit.md index 7f3816b4f..c80691c5d 100644 --- a/docs/src/man/bootc-edit.md +++ b/docs/src/man/bootc-edit.md @@ -36,4 +36,4 @@ Only changes to the \`spec\` section are honored. # VERSION -v1.1.0 +v1.1.2 diff --git a/docs/src/man/bootc-install-ensure-completion.md b/docs/src/man/bootc-install-ensure-completion.md new file mode 100644 index 000000000..4dd073265 --- /dev/null +++ b/docs/src/man/bootc-install-ensure-completion.md @@ -0,0 +1,30 @@ +# NAME + +bootc-install-ensure-completion - Intended for use in environments that +are performing an ostree-based installation, not bootc + +# SYNOPSIS + +**bootc install ensure-completion** \[**-h**\|**\--help**\] + +# DESCRIPTION + +Intended for use in environments that are performing an ostree-based +installation, not bootc. + +In this scenario the installation may be missing bootc specific features +such as kernel arguments, logically bound images and more. This command +can be used to attempt to reconcile. At the current time, the only +tested environment is Anaconda using \`ostreecontainer\` and it is +recommended to avoid usage outside of that environment. Instead, ensure +your code is using \`bootc install to-filesystem\` from the start. + +# OPTIONS + +**-h**, **\--help** + +: Print help (see a summary with -h) + +# VERSION + +v1.1.2 diff --git a/docs/src/man/bootc-install-print-configuration.md b/docs/src/man/bootc-install-print-configuration.md index 4387e155d..9242848de 100644 --- a/docs/src/man/bootc-install-print-configuration.md +++ b/docs/src/man/bootc-install-print-configuration.md @@ -27,4 +27,4 @@ string-valued filesystem name suitable for passing to \`mkfs.\$type\`. # VERSION -v1.1.0 +v1.1.2 diff --git a/docs/src/man/bootc-install-to-disk.md b/docs/src/man/bootc-install-to-disk.md index 051c3ce78..d0091a529 100644 --- a/docs/src/man/bootc-install-to-disk.md +++ b/docs/src/man/bootc-install-to-disk.md @@ -10,8 +10,8 @@ bootc-install-to-disk - Install to the target block device \[**\--enforce-container-sigpolicy**\] \[**\--target-ostree-remote**\] \[**\--skip-fetch-check**\] \[**\--disable-selinux**\] \[**\--karg**\] \[**\--root-ssh-authorized-keys**\] \[**\--generic-image**\] -\[**\--stateroot**\] \[**\--via-loopback**\] \[**-h**\|**\--help**\] -\<*DEVICE*\> +\[**\--bound-images**\] \[**\--stateroot**\] \[**\--via-loopback**\] +\[**-h**\|**\--help**\] \<*DEVICE*\> # DESCRIPTION @@ -130,6 +130,19 @@ boot. \- All bootloader types will be installed - Changes to the system firmware will be skipped +**\--bound-images**=*BOUND_IMAGES* \[default: stored\] + +: How should logically bound images be retrieved\ + +\ +*Possible values:* + +> - stored: Bound images must exist in the sources root container +> storage (default) +> +> - pull: Bound images will be pulled and stored directly in the +> targets bootc container storage + **\--stateroot**=*STATEROOT* : The stateroot name to use. Defaults to \`default\` @@ -149,4 +162,4 @@ firmware will be skipped # VERSION -v1.1.0 +v1.1.2 diff --git a/docs/src/man/bootc-install-to-existing-root.md b/docs/src/man/bootc-install-to-existing-root.md index b9fe45e1c..41357bd4f 100644 --- a/docs/src/man/bootc-install-to-existing-root.md +++ b/docs/src/man/bootc-install-to-existing-root.md @@ -10,8 +10,9 @@ bootc-install-to-existing-root - Install to the host root filesystem \[**\--target-ostree-remote**\] \[**\--skip-fetch-check**\] \[**\--disable-selinux**\] \[**\--karg**\] \[**\--root-ssh-authorized-keys**\] \[**\--generic-image**\] -\[**\--stateroot**\] \[**\--acknowledge-destructive**\] -\[**-h**\|**\--help**\] \[*ROOT_PATH*\] +\[**\--bound-images**\] \[**\--stateroot**\] +\[**\--acknowledge-destructive**\] \[**-h**\|**\--help**\] +\[*ROOT_PATH*\] # DESCRIPTION @@ -115,6 +116,19 @@ boot. \- All bootloader types will be installed - Changes to the system firmware will be skipped +**\--bound-images**=*BOUND_IMAGES* \[default: stored\] + +: How should logically bound images be retrieved\ + +\ +*Possible values:* + +> - stored: Bound images must exist in the sources root container +> storage (default) +> +> - pull: Bound images will be pulled and stored directly in the +> targets bootc container storage + **\--stateroot**=*STATEROOT* : The stateroot name to use. Defaults to \`default\` @@ -129,9 +143,10 @@ firmware will be skipped \[*ROOT_PATH*\] \[default: /target\] -: Path to the mounted root; its expected to invoke podman with \`-v - /:/target\`, then supplying this argument is unnecessary +: Path to the mounted root; this is now not necessary to provide. + Historically it was necessary to ensure the host rootfs was mounted + at here via e.g. \`-v /:/target\` # VERSION -v1.1.0 +v1.1.2 diff --git a/docs/src/man/bootc-install-to-filesystem.md b/docs/src/man/bootc-install-to-filesystem.md index 04c2eadf9..1963cdca5 100644 --- a/docs/src/man/bootc-install-to-filesystem.md +++ b/docs/src/man/bootc-install-to-filesystem.md @@ -13,7 +13,8 @@ filesystem structure \[**\--target-ostree-remote**\] \[**\--skip-fetch-check**\] \[**\--disable-selinux**\] \[**\--karg**\] \[**\--root-ssh-authorized-keys**\] \[**\--generic-image**\] -\[**\--stateroot**\] \[**-h**\|**\--help**\] \<*ROOT_PATH*\> +\[**\--bound-images**\] \[**\--stateroot**\] \[**-h**\|**\--help**\] +\<*ROOT_PATH*\> # DESCRIPTION @@ -144,6 +145,19 @@ boot. \- All bootloader types will be installed - Changes to the system firmware will be skipped +**\--bound-images**=*BOUND_IMAGES* \[default: stored\] + +: How should logically bound images be retrieved\ + +\ +*Possible values:* + +> - stored: Bound images must exist in the sources root container +> storage (default) +> +> - pull: Bound images will be pulled and stored directly in the +> targets bootc container storage + **\--stateroot**=*STATEROOT* : The stateroot name to use. Defaults to \`default\` @@ -161,4 +175,4 @@ mounting. To override this, use \`\--root-mount-spec\`. # VERSION -v1.1.0 +v1.1.2 diff --git a/docs/src/man/bootc-install.md b/docs/src/man/bootc-install.md index 089ae2bab..010c36179 100644 --- a/docs/src/man/bootc-install.md +++ b/docs/src/man/bootc-install.md @@ -10,7 +10,7 @@ bootc-install - Install the running container to a target Install the running container to a target. -\## Understanding installations +## Understanding installations OCI containers are effectively layers of tarballs with JSON for metadata; they cannot be booted directly. The \`bootc install\` flow is @@ -48,6 +48,11 @@ bootc-install-to-existing-root(8) : Install to the host root filesystem +bootc-install-ensure-completion(8) + +: Intended for use in environments that are performing an ostree-based + installation, not bootc + bootc-install-print-configuration(8) : Output JSON to stdout that contains the merged installation @@ -61,4 +66,4 @@ bootc-install-help(8) # VERSION -v1.1.0 +v1.1.2 diff --git a/docs/src/man/bootc-rollback.md b/docs/src/man/bootc-rollback.md index eea1e887b..a0b8d3e22 100644 --- a/docs/src/man/bootc-rollback.md +++ b/docs/src/man/bootc-rollback.md @@ -34,4 +34,4 @@ rollback invocation. # VERSION -v1.1.0 +v1.1.2 diff --git a/docs/src/man/bootc-status.md b/docs/src/man/bootc-status.md index 215f38151..685fd76a5 100644 --- a/docs/src/man/bootc-status.md +++ b/docs/src/man/bootc-status.md @@ -16,13 +16,13 @@ bootc system state. If standard output is not a terminal, output a YAML-formatted object using a schema intended to match a Kubernetes resource that describes the state of the booted system. -\## Parsing output via programs +## Parsing output via programs Either the default YAML format or \`\--format=json\` can be used. Do not attempt to explicitly parse the output of \`\--format=humanreadable\` as it will very likely change over time. -\## Programmatically detecting whether the system is deployed via bootc +## Programmatically detecting whether the system is deployed via bootc Invoke e.g. \`bootc status \--json\`, and check if \`status.booted\` is not \`null\`. @@ -59,4 +59,4 @@ not \`null\`. # VERSION -v1.1.0 +v1.1.2 diff --git a/docs/src/man/bootc-switch.md b/docs/src/man/bootc-switch.md index 432d902e6..4e91d14f8 100644 --- a/docs/src/man/bootc-switch.md +++ b/docs/src/man/bootc-switch.md @@ -15,7 +15,7 @@ Target a new container image reference to boot. This is almost exactly the same operation as \`upgrade\`, but additionally changes the container image reference instead. -\## Usage +## Usage A common pattern is to have a management agent control operating system updates via container image tags; for example, @@ -69,4 +69,4 @@ includes a default policy which requires signatures. # VERSION -v1.1.0 +v1.1.2 diff --git a/docs/src/man/bootc-upgrade.md b/docs/src/man/bootc-upgrade.md index c5b5efb17..b2a428f07 100644 --- a/docs/src/man/bootc-upgrade.md +++ b/docs/src/man/bootc-upgrade.md @@ -52,4 +52,4 @@ userspace-only restart. # VERSION -v1.1.0 +v1.1.2 diff --git a/docs/src/man/bootc-usr-overlay.md b/docs/src/man/bootc-usr-overlay.md index 075ba050b..bcf4620c3 100644 --- a/docs/src/man/bootc-usr-overlay.md +++ b/docs/src/man/bootc-usr-overlay.md @@ -12,20 +12,20 @@ will be discarded on reboot Adds a transient writable overlayfs on \`/usr\` that will be discarded on reboot. -\## Use cases +## Use cases A common pattern is wanting to use tracing/debugging tools, such as \`strace\` that may not be in the base image. A system package manager such as \`apt\` or \`dnf\` can apply changes into this transient overlay that will be discarded on reboot. -\## /etc and /var +## /etc and /var However, this command has no effect on \`/etc\` and \`/var\` - changes written there will persist. It is common for package installations to modify these directories. -\## Unmounting +## Unmounting Almost always, a system process will hold a reference to the open mount point. You can however invoke \`umount -l /usr\` to perform a \"lazy @@ -39,4 +39,4 @@ unmount\". # VERSION -v1.1.0 +v1.1.2 diff --git a/docs/src/man/bootc.md b/docs/src/man/bootc.md index 07a32e328..186e99fc7 100644 --- a/docs/src/man/bootc.md +++ b/docs/src/man/bootc.md @@ -72,4 +72,4 @@ bootc-help(8) # VERSION -v1.1.0 +v1.1.2 diff --git a/lib/src/cli.rs b/lib/src/cli.rs index bd896f4fa..e293fd940 100644 --- a/lib/src/cli.rs +++ b/lib/src/cli.rs @@ -190,7 +190,6 @@ pub(crate) enum InstallOpts { /// to reconcile. At the current time, the only tested environment is Anaconda using `ostreecontainer` /// and it is recommended to avoid usage outside of that environment. Instead, ensure your /// code is using `bootc install to-filesystem` from the start. - #[clap(hide = true)] EnsureCompletion {}, /// Output JSON to stdout that contains the merged installation configuration /// as it may be relevant to calling processes using `install to-filesystem`