From 75e7b9040ba9f44a4bff7152d9b56e066854f5c7 Mon Sep 17 00:00:00 2001 From: Jarrod Johnson Date: Tue, 25 Nov 2025 13:19:03 -0500 Subject: [PATCH] Add more imgutil documentation --- confluent_client/doc/man/imgutil.ronn | 139 ++++++++++++++++++++++++++ imgutil/imgutil | 2 +- 2 files changed, 140 insertions(+), 1 deletion(-) create mode 100644 confluent_client/doc/man/imgutil.ronn diff --git a/confluent_client/doc/man/imgutil.ronn b/confluent_client/doc/man/imgutil.ronn new file mode 100644 index 00000000..939cef09 --- /dev/null +++ b/confluent_client/doc/man/imgutil.ronn @@ -0,0 +1,139 @@ +# imgutil(1) -- Work with confluent OS cloning and diskless images + +## SYNOPSIS + +`imgutil` `build` [] +`imgutil` `exec` [] [...] +`imgutil` `unpack` +`imgutil` `pack` [] +`imgutil` `capture` + +## DESCRIPTION + +**imgutil** is a utility for creating, managing, and deploying OS images for diskless boot and system cloning in a Confluent environment. It supports building images from scratch, capturing images from running systems, and packing/unpacking diskless profiles. + +## COMMANDS + +* `build`: + Build a new diskless image from scratch in the specified scratch directory. + +* `exec`: + Start the specified scratch directory as a container and optionally run a command inside it. + +* `unpack`: + Unpack a diskless image profile to a scratch directory for modification. + +* `pack`: + Pack a scratch directory into a diskless profile that can be deployed. + +* `capture`: + Capture an image for cloning from a running system. + +## BUILD OPTIONS + +* `-r`, `--addrepos` : + Repositories to add in addition to the main source. May be specified multiple times. + +* `-p`, `--packagelist` : + Filename of package list to replace default pkglist. + +* `-a`, `--addpackagelist` : + A list of additional packages to include. May be specified multiple times. + +* `-s`, `--source` : + Directory to pull installation from, typically a subdirectory of `/var/lib/confluent/distributions`. By default, the repositories for the build system are used. For Ubuntu, this is not supported; the build system repositories are always used. + +* `-y`, `--non-interactive`: + Avoid prompting for confirmation. + +* `-v`, `--volume` : + Directory to make available in the build environment. `-v /` will cause it to be mounted in image as `/run/external/`. `-v /:/run/root` will override the target to be `/run/root`. Something like `/var/lib/repository:-` will cause it to mount to the identical path inside the image. May be specified multiple times. + +* : + Directory to build new diskless root in. + +## EXEC OPTIONS + +* `-v`, `--volume` : + Directory to make available in the build environment. `-v /` will cause it to be mounted in image as `/run/external/`. `-v /:/run/root` will override the target to be `/run/root`. May be specified multiple times. + +* : + Directory of an unpacked diskless root. + +* : + Optional command to run (defaults to a shell). + +## UNPACK OPTIONS + +* : + The diskless OS profile to unpack. + +* : + Directory to extract diskless root to. + +## PACK OPTIONS + +* `-b`, `--baseprofile` : + Profile to copy extra info from. For example, to make a new version of an existing profile, reference the previous one as baseprofile. + +* `-u`, `--unencrypted`: + Pack an unencrypted image rather than encrypting. + +* : + Directory containing diskless root. + +* : + The desired diskless OS profile name to pack the root into. + +## CAPTURE OPTIONS + +* : + Node to capture image from. + +* : + Profile name for captured image. + +## EXAMPLES + +Build a diskless image from a distribution: + + imgutil build -s alma-9.6-x86_64 /tmp/myimage + +Execute a shell in an unpacked image: + + imgutil exec /tmp/myimage + +Execute a specific command in an image: + + imgutil exec /tmp/myimage /bin/rpm -qa + +Unpack an existing profile for modification: + + imgutil unpack myprofile /tmp/myimage + +Pack a modified image into a new profile: + + imgutil pack /tmp/myimage myprofile-v2 + +Capture an image from a running node: + + imgutil capture node01 production-image + +## FILES + +* `/var/lib/confluent/public/os/`: + Default location for OS profiles. + +* `/var/lib/confluent/private/os/`: + Location for encrypted image keys and private data. + +* `/var/lib/confluent/distributions/`: + Default location for installation sources. + +## SEE ALSO + +osdeploy(8) + +## AUTHOR + +Written for the Confluent project. diff --git a/imgutil/imgutil b/imgutil/imgutil index 6ecc7295..0c44d8ee 100644 --- a/imgutil/imgutil +++ b/imgutil/imgutil @@ -894,7 +894,7 @@ def main(): buildp.add_argument('-p', '--packagelist', help='Filename of package list to replace default pkglist', default='') buildp.add_argument('-a', '--addpackagelist', action='append', default=[], help='A list of additional packages to include, may be specified multiple times') - buildp.add_argument('-s', '--source', help='Directory to pull installation from, typically a subdirectory of /var/lib/confluent/distributions. By default, the repositories for the build system are used.') + buildp.add_argument('-s', '--source', help='Directory to pull installation from, typically a subdirectory of /var/lib/confluent/distributions. By default, the repositories for the build system are used. For Ubuntu, this is not supported, the build system repositories are always used.') buildp.add_argument('-y', '--non-interactive', help='Avoid prompting for confirmation', action='store_true') buildp.add_argument('-v', '--volume', help='Directory to make available in the build environment. -v / will '