mirror of
https://github.com/xcat2/confluent.git
synced 2026-08-04 00:17:01 +00:00
Markus Hilger
7633bac055
Allow building EL and Ubuntu diskless images for a foreign architecture (e.g. aarch64 on an x86_64 host) by leveraging qemu-user-static. The target architecture is detected automatically from a -s source tree (for EL), or may be requested explicitly with the new --arch option. When the target differs from the host, dnf/debootstrap is invoked with --forcearch/--arch and the presence of an enabled binfmt_misc handler with the F (fix-binary) flag is verified up front, so emulation keeps working inside the installroot chroot and a missing setup yields an actionable error instead of a confusing exec failure mid-build. The image architecture is recorded in confluentimg.buildinfo so that pack selects the initramfs addons for the image architecture rather than the build host, and exec of a foreign-arch root performs the same binfmt check.
159 lines
4.7 KiB
Markdown
159 lines
4.7 KiB
Markdown
# imgutil(1) -- Work with confluent OS cloning and diskless images
|
|
|
|
## SYNOPSIS
|
|
|
|
`imgutil` `build` [<options>] <scratchdir>
|
|
`imgutil` `exec` [<options>] <scratchdir> [<cmd>...]
|
|
`imgutil` `unpack` <profilename> <scratchdir>
|
|
`imgutil` `pack` [<options>] <scratchdir> <profilename>
|
|
`imgutil` `capture` <node> <profilename>
|
|
|
|
## 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` <repository>:
|
|
Repositories to add in addition to the main source. May be specified multiple times.
|
|
|
|
* `-p`, `--packagelist` <file>:
|
|
Filename of package list to replace default pkglist.
|
|
|
|
* `-a`, `--addpackagelist` <file>:
|
|
A list of additional packages to include. May be specified multiple times.
|
|
|
|
* `-s`, `--source` <directory>:
|
|
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.
|
|
|
|
* `--arch` <architecture>:
|
|
Target architecture to build for (`x86_64` or `aarch64`). For Ubuntu, the
|
|
Debian-style names `amd64` and `arm64` are accepted as aliases. Building
|
|
for a foreign architecture is supported on EL and Ubuntu build hosts and
|
|
requires a statically linked qemu-user emulator registered in binfmt_misc
|
|
with the F (fix-binary) flag; on Ubuntu this is provided by the
|
|
qemu-user-static package (qemu-user-binfmt as of Ubuntu 26.04). For EL,
|
|
the architecture is also detected automatically when building from a `-s`
|
|
source tree.
|
|
|
|
* `-y`, `--non-interactive`:
|
|
Avoid prompting for confirmation.
|
|
|
|
* `-v`, `--volume` <mount>:
|
|
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.
|
|
|
|
* <scratchdir>:
|
|
Directory to build new diskless root in.
|
|
|
|
## EXEC OPTIONS
|
|
|
|
* `-v`, `--volume` <mount>:
|
|
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.
|
|
|
|
* <scratchdir>:
|
|
Directory of an unpacked diskless root.
|
|
|
|
* <cmd>:
|
|
Optional command to run (defaults to a shell).
|
|
|
|
## UNPACK OPTIONS
|
|
|
|
* <profilename>:
|
|
The diskless OS profile to unpack.
|
|
|
|
* <scratchdir>:
|
|
Directory to extract diskless root to.
|
|
|
|
## PACK OPTIONS
|
|
|
|
* `-b`, `--baseprofile` <profile>:
|
|
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.
|
|
|
|
* <scratchdir>:
|
|
Directory containing diskless root.
|
|
|
|
* <profilename>:
|
|
The desired diskless OS profile name to pack the root into.
|
|
|
|
## CAPTURE OPTIONS
|
|
|
|
* <node>:
|
|
Node to capture image from.
|
|
|
|
* <profilename>:
|
|
Profile name for captured image.
|
|
|
|
## EXAMPLES
|
|
|
|
Build a diskless image from a distribution:
|
|
|
|
imgutil build -s alma-9.6-x86_64 /tmp/myimage
|
|
|
|
Build an aarch64 EL diskless image on an x86_64 host (the architecture is
|
|
detected from the source tree):
|
|
|
|
imgutil build -s alma-9.6-aarch64 /tmp/myimage
|
|
|
|
Build an aarch64 Ubuntu diskless image on an amd64 Ubuntu host:
|
|
|
|
imgutil build --arch aarch64 /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.
|