buildah(1)

📦
version 1.45.0 · 7 versions
, in centos-stream 10, centos-stream 9, fedora 43, fedora 44

✨ NAME ✨

buildah — a command line tool that facilitates building OCI container images. 💅

(also hi, this is the buildah(1) page from the General Commands Manual, so you're literally in the right place bestie 🫶)

🌸 SYNOPSIS 🌸

buildah [OPTIONS] COMMAND [ARG...]

💖 DESCRIPTION 💖

okay so the Buildah package hands you a command line tool that can do all of this:

  • Create a working container, either from scratch or using an image as a starting point.
  • Mount a working container's root filesystem for manipulation.
  • Unmount a working container's root filesystem.
  • Use the updated contents of a container's root filesystem as a filesystem layer to create a new image.
  • Delete a working container or an image.
  • Rename a local container.

like, that's the whole glow-up pipeline. container in, image out. iconic behavior honestly 👑

🎀 OPTIONS 🎀

  • --cgroup-manager=manager — the CGroup manager to use for container cgroups. Supported values are cgroupfs or systemd. Default is systemd unless it's overridden in the containers.conf file.
    • Note: setting this flag can cause certain commands to break when called on containers that were previously created by the other CGroup manager type. 😭
    • Note: CGroup manager is not supported in rootless mode when using CGroups Version V1.
  • --imagestore path — the path under which content for pulled and built images will be stored. By default, the configured --root location is used for pulled and built images as well as containers. If the storage driver is overlay, then any images which have previously been written to the --root location will still be available.

This will override the imagestore option in containers-storage.conf(5).

  • --log-level level — the log level to be used. Either "trace", "debug", "info", "warn", "error", "fatal", or "panic", defaulting to "warn".
  • --help, -h — show help 🙋‍♀️
  • --registries-conf path — pathname of the configuration file which specifies which container registries should be consulted when completing image names which do not include a registry or domain portion. It is not recommended that this option be used, as the default behavior of using the system-wide configuration (/etc/containers/registries.conf) is most often preferred.
  • --registries-conf-dir path — pathname of the directory which contains configuration snippets which specify registries which should be consulted when completing image names which do not include a registry or domain portion. It is not recommended that this option be used, as the default behavior of using the system-wide configuration (/etc/containers/registries.d) is most often preferred.
  • --root path — storage root dir (default: "/var/lib/containers/storage" for UID 0, "$HOME/.local/share/containers/storage" for other users). The default root dir is configured in /etc/containers/storage.conf.
  • --runroot path — storage state dir (default: "/run/containers/storage" for UID 0, "/run/user/$UID" for other users). The default state dir is configured in /etc/containers/storage.conf.
  • --short-name-alias-conf path — pathname of the file which contains cached mappings between short image names and their corresponding fully-qualified names. It is used for mapping from names of images specified using short names like "ubi8" which don't include a registry component and a corresponding fully-specified name which includes a registry and any other components, such as "registry.access.redhat.com/ubi8". It is not recommended that this option be used, as the default behavior of using the system-wide cache (/var/cache/containers/short-name-aliases.conf) or per-user cache ($HOME/.cache/containers/short-name-aliases.conf) to supplement system-wide defaults is most often preferred.
  • --storage-driver value — storage driver. The default storage driver for UID 0 is configured in /etc/containers/storage.conf ($HOME/.config/containers/storage.conf in rootless mode), and is vfs for other users. The STORAGE_DRIVER environment variable overrides the default. The --storage-driver specified driver overrides all. 🫡

Examples: "overlay", "vfs"

Overriding this option will cause the storage-opt settings in /etc/containers/storage.conf to be ignored. The user must specify additional options via the --storage-opt flag.
  • --storage-opt value — storage driver option. Default storage driver options are configured in /etc/containers/storage.conf ($HOME/.config/containers/storage.conf in rootless mode). The STORAGE_OPTS environment variable overrides the default. The --storage-opt specified options overrides all.
  • --transient-store bool-value — store metadata about containers under the storage state directory (--runroot), with the intention that records about them will be removed when the system is rebooted. Additional garbage collection must still be performed at boot-time, so this option should remain disabled in most configurations. (default: false)
  • --userns-gid-map mapping — directly specifies a GID mapping which should be used to set ownership, at the filesystem level, on the working container's contents. Commands run when handling RUN instructions will default to being run in their own user namespaces, configured using the UID and GID maps.

Entries in this map take the form of one or more colon-separated triples of a starting in-container GID, a corresponding starting host-level GID, and the number of consecutive IDs which the map entry represents.

This option overrides the remap-gids setting in the options section of /etc/containers/storage.conf.

If this option is not specified, but a global --userns-gid-map setting is supplied, settings from the global option will be used.

If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-gid-map are specified, but --userns-uid-map is specified, the GID map will be set to use the same numeric values as the UID map.

NOTE: When this option is specified by a rootless user, the specified mappings are relative to the rootless usernamespace in the container, rather than being relative to the host as it would be when run rootful.
  • --userns-uid-map mapping — directly specifies a UID mapping which should be used to set ownership, at the filesystem level, on the working container's contents. Commands run when handling RUN instructions will default to being run in their own user namespaces, configured using the UID and GID maps.

Entries in this map take the form of one or more colon-separated triples of a starting in-container UID, a corresponding starting host-level UID, and the number of consecutive IDs which the map entry represents.

This option overrides the remap-uids setting in the options section of /etc/containers/storage.conf.

If this option is not specified, but a global --userns-uid-map setting is supplied, settings from the global option will be used.

If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-uid-map are specified, but --userns-gid-map is specified, the UID map will be set to use the same numeric values as the GID map.

NOTE: When this option is specified by a rootless user, the specified mappings are relative to the rootless usernamespace in the container, rather than being relative to the host as it would be when run rootful.
  • --version, -v — print the version 🔢

🦋 Environment Variables 🦋

Buildah can set up environment variables from the env entry in the [engine] table in the containers.conf(5). These variables can be overridden by passing environment variables before the buildah commands. 💫

part 2 is loading, don't go anywhere bestie 💅

🌈 COMMANDS 🌈

okay bestie, this is the part you actually came for 💅 — the whole roster of stuff buildah can do. Every single one of these lives in its own man page, so when you wanna go deep, just pull up that page and I promise it's worth it. Here's the lineup, in order, no skips, no cuts:

  • add — page: buildah-add(1) ✨ — Add the contents of a file, URL, or a directory to the container.
  • build — page: buildah-build(1) 🔥 — Builds an OCI image using instructions in one or more Containerfiles. this one is THE moment, lowkey the whole reason we're here.
  • commit — page: buildah-commit(1) 🎀 — Create an image from a working container.
  • config — page: buildah-config(1) 💜 — Update image configuration settings.
  • containers — page: buildah-containers(1) 🌸 — List the working containers and their base images.
  • copy — page: buildah-copy(1) 🦋 — Copies the contents of a file, URL, or directory into a container's working directory.
  • from — page: buildah-from(1) ⭐ — Creates a new working container, either from scratch or using a specified image as a starting point. your origin story fr fr.
  • images — page: buildah-images(1) 👑 — List images in local storage.
  • info — page: buildah-info(1) 🌈 — Display Buildah system information.
  • inspect — page: buildah-inspect(1) 🔍 — Inspects the configuration of a container or image.
  • login — page: buildah-login(1) 💖 — Login to a container registry.
  • logout — page: buildah-logout(1) 🙈 — Logout of a container registry.
  • manifest — page: buildah-manifest(1) 🧚 — Create and manipulate manifest lists and image indexes.
  • mkcw — page: buildah-mkcw(1) 🔐 — Convert a conventional container image into a confidential workload image.
  • mount — page: buildah-mount(1) 🌟 — Mount the working container's root filesystem.
  • prune — page: buildah-prune(1) 🧹 — Cleanup intermediate images as well as build and mount cache. self-care for your storage, honestly.
  • pull — page: buildah-pull(1) 🫶 — Pull an image from the specified location.
  • push — page: buildah-push(1) 🚀 — Push an image from local storage to elsewhere.
  • rename — page: buildah-rename(1) ✏️ — Rename a local container.
  • rm — page: buildah-rm(1) 💀 — Removes one or more working containers.
  • rmi — page: buildah-rmi(1) 💀 — Removes one or more images.
  • run — page: buildah-run(1) ⚡ — Run a command inside of the container.
  • source — page: buildah-source(1) 📦 — Create, push, pull and manage source images and associated source artifacts.
  • tag — page: buildah-tag(1) 🏷️ — Add an additional name to a local image.
  • umount — page: buildah-umount(1) 🌙 — Unmount a working container's root file system.
  • unshare — page: buildah-unshare(1) 🌀 — Launch a command in a user namespace with modified ID mappings.
  • version — page: buildah-version(1) 🍓 — Display the Buildah Version Information.

no cap, that's the full set of commands — twenty-seven of them, each with its own whole man page waiting for you. go off 💅

🌸 FILES 🌸

okay bestie, this is the part where we talk about the little config files that run the whole show behind the scenes. they're not glamorous but they're everything. 💅

💾 storage.conf (/etc/containers/storage.conf)

storage.conf is the storage configuration file for all tools using containers/storage. periodt.

it specifies all of the available container storage options for tools using shared container storage. all of them. the whole buffet. 🍓

💾 mounts.conf (/usr/share/containers/mounts.conf and optionally /etc/containers/mounts.conf)

so the mounts.conf files list volume mount files or directories that get automatically mounted inside containers when you run buildah run or buildah build. 🫶 container processes can then use that content. and here's the key thing — the volume mount content does not get committed to the final image.

usually these directories are used for passing secrets or credentials that the package software needs to access remote package repositories. iykyk 🔐

for example, a mounts.conf with the line "/usr/share/rhel/secrets:/run/secrets" means the content of the /usr/share/rhel/secrets directory gets mounted on /run/secrets inside the container. this mountpoint lets Red Hat Enterprise Linux subscriptions from the host be used within the container. iconic behaviour honestly.

you can also omit the destination if it's equal to the source path. for example, specifying /var/lib/secrets will mount the directory into the same container destination path /var/lib/secrets. no cap.

🚨 note note note: this is not a volume mount. the content of the volumes is copied into container storage, not bind mounted directly from the host. don't get it twisted bestie.

💾 registries.conf (/etc/containers/registries.conf)

registries.conf is the configuration file that specifies which container registries should be consulted when completing image names that don't include a registry or domain portion. it's giving "where do i look when you're vague" energy. 👑

💾 registries.d (/etc/containers/registries.d)

a directory containing configuration snippets which specify registries which should be consulted when completing image names which do not include a registry or domain portion. yes, it's basically the same job as registries.conf but as a directory of lil snippets. both exist. both matter. 💜

✨ SEE ALSO ✨

go read these too, they're the supporting cast and they ate:

📜 HISTORY 📜

December 2017, Originally compiled by Tom Sweeney tsweeney@redhat.com ⟨mailto:tsweeney@redhat.com⟩

and that's the whole page bestie!! 🎀 this buildah manual page is from March 2017, page buildah(1) — go forth and build containers, you absolute main character. slay responsibly. 💖✨🦋

📦 where this page comes from