buildah-config(1)

buildah-config 💅✨

okay bestie, welcome to the buildah-config(1) page — yeah it lives in the General Commands Manual section, and yeah it's about to be your new obsession 🎀

---

✨ NAME ✨

buildah-config — Update image configuration settings. 🦋

Like. It literally goes in and tweaks the config on your image. That's the whole vibe. 👑

---

🌸 SYNOPSIS 🌸

buildah config [options] container

so it's buildah config, then whatever [options] you wanna throw at it, then the container you're messing with. easy. periodt. 💅

---

💖 DESCRIPTION 💖

Here's the tea: this command updates one or more of the settings kept for a container.</strong> 🫶

One setting, twelve settings, honestly whatever you're feeling — it just goes in and refreshes the config, no cap. 🌈

Also bestie, heads up: it's one or more — so don't come at me thinking you gotta do them one at a time. You don't. 🔥

---

okay that's the setup, keep reading, there's SO much more 👑

💅 OPTIONS 💅

Okay bestie, here's the whole menu. Every flag, every note, no skips. Let's go. ✨

• --add-history — drops an entry into the image's history that notes the changes you made to --cmd, --entrypoint, --env, --healthcheck, --label, --onbuild, --port, --shell, --stop-signal, --user, --volume, and --workingdir. Defaults to false.

Note: you can also override that default with the BUILDAH_HISTORY environment variable. Like: export BUILDAH_HISTORY=true

• --annotation, -a annotation=annotation — adds an image annotation (think annotation=annotation) to the image manifest of any images that get built from this container. Use it as many times as you want. If the annotation has a trailing -, the annotation gets removed from the config. And if the annotation is literally set to -, then all annotations get yeeted from the config. 💀
• --arch architecture — sets the target architecture for any images built from this container. By default, if the container came from an image, that image's target architecture stays; otherwise the host's architecture gets recorded. 🦋
• --author author — sets the contact info for the author on any images built from this container.
• --cmd command — sets the default command to run for containers based on any images built from this container. When you pair it with an entry point, this is what specifies the default parameters for that entry point. 👑
• --comment comment — sets the image-level comment for any images built from this container.

Note: this setting isn't in the OCIv1 image format, so it gets discarded when writing images in OCIv1 formats.

• --created-by created — sets the description of how the topmost layer was created, for any images created from this container.
• --domainname domain — sets the domainname to use when running containers based on any images built from this container.

Note: this setting isn't in the OCIv1 image format, so it gets discarded when writing images in OCIv1 formats.

• --entrypoint "command" | '["command", "arg1", ...]' — sets the entry point for containers based on any images built from this container. buildah supports two formats here, bestie: a plain string, or an array of commands.

Note: when the entrypoint is a string, container runtimes will ignore the cmd value of the container image. But if you use the array form, the cmd gets appended onto the end of the entrypoint cmd and they get executed together.

Note: the string form gets appended to the sh -c command as the entrypoint. The array form replaces the entrypoint entirely.

String Format:

$ buildah from scratch
$ buildah config --entrypoint "/usr/bin/notashell" working-container
$ buildah inspect --format '{{ .OCIv1.Config.Entrypoint }}' working-container
[/bin/sh -c /usr/bin/notshell]
$ buildah inspect --format '{{ .Docker.Config.Entrypoint }}' working-container
[/bin/sh -c /usr/bin/notshell]

Array Format:

$ buildah config --entrypoint '["/usr/bin/notashell"]' working-container
$ buildah inspect --format '{{ .OCIv1.Config.Entrypoint }}' working-container
[/usr/bin/notashell]
$ buildah inspect --format '{{ .Docker.Config.Entrypoint }}' working-container
[/usr/bin/notashell]

• --env, -e env[=value] — adds a value (like env=value) to the environment for containers based on any images built from this container. Can be used multiple times. If env is named but you give it neither = nor a value, the value gets pulled from the current process environment. If env has a trailing -, that env gets removed from the config. And if env is set to -, then all environment variables get removed from the config. 🧚
• --healthcheck command — specifies a command that should run to check whether a container is running correctly.

Values can be NONE, "CMD ..." (run that command directly), "CMD-SHELL ..." (run that command using the system's shell), or the empty value (which removes a previously-set value and its related settings).

Note: this setting isn't in the OCIv1 image format, so it gets discarded when writing images in OCIv1 formats.

• --healthcheck-interval interval — specifies how often the command from the --healthcheck option should run.

Note: this setting isn't in the OCIv1 image format, so it gets discarded when writing images in OCIv1 formats.

• --healthcheck-retries count — specifies how many times the command from the --healthcheck option can fail before the container is considered unhealthy.

Note: this setting isn't in the OCIv1 image format, so it gets discarded when writing images in OCIv1 formats.

• --healthcheck-start-interval interval — specifies the time between health checks during the start period.

Note: this setting isn't in the OCIv1 image format, so it gets discarded when writing images in OCIv1 formats.

• --healthcheck-start-period interval — specifies how much time can elapse after a container has started before a failure to run the command from the --healthcheck option should be treated as a sign that the container is failing. During this window, failures get blamed on the container not having fully started yet and won't count as errors. After the command succeeds, or the time period has elapsed, failures start counting as errors. 😭

Note: this setting isn't in the OCIv1 image format, so it gets discarded when writing images in OCIv1 formats.

• --healthcheck-timeout interval — specifies how long to wait after starting the command from the --healthcheck option for it to return its exit status. If the command hasn't returned within this time, it should be considered to have failed.

Note: this setting isn't in the OCIv1 image format, so it gets discarded when writing images in OCIv1 formats.

• --history-comment comment — sets a comment on the topmost layer of any images created from this container.
• --hostname host — sets the hostname to use when running containers based on any images built from this container.

Note: this setting isn't in the OCIv1 image format, so it gets discarded when writing images in OCIv1 formats.

• --label, -l label=value — adds an image label (like label=value) to the image configuration of any images built from this container. Can be used multiple times. If label has a trailing -, the label gets removed from the config. If label is set to -, then all labels get removed from the config. ✨
• --onbuild onbuild command — adds an ONBUILD command to the image. ONBUILD commands run automatically when images get built based on the image you're creating. 🤯

Note: this setting isn't in the OCIv1 image format, so it gets discarded when writing images in OCIv1 formats.

• --os operating system — sets the target operating system for any images built from this container. By default, if the container came from an image, its OS is kept; otherwise the host's OS name gets recorded.
• --os-feature feature — sets the name of a required operating system feature for any images built from this container. By default, if the container came from an image, the base image's required OS feature list is kept — if it specified one. This option is typically only meaningful when the image's OS is Windows.

If feature has a trailing -, the feature gets removed from the set of required features that'll be listed in the image. If feature is set to -, then the entire features list gets removed from the config.

• --os-version version — sets the exact required operating system version for any images built from this container. By default, if the container came from an image, the base image's required OS version is kept — if it specified one. This option is typically only meaningful when the image's OS is Windows, and it's typically set in Windows base images, so using this option is usually unnecessary. 🙈
• --port, -p port/protocol — adds a port to expose when running containers based on any images built from this container. Can be used multiple times. To say whether the port listens on TCP or UDP, use port/protocol. The default is TCP if you don't specify a protocol. To expose the port on both TCP and UDP, specify the port option multiple times. If port has a trailing - and is already set, the port gets removed from the configuration. If port is set to -, then all exposed ports settings get removed from the configuration. 🔥
• --shell shell — sets the default shell to run inside the container image. The shell instruction lets the default shell used for the shell form of commands be overridden. The default shell for Linux containers is /bin/sh -c. 🐚

Note: this setting isn't in the OCIv1 image format, so it gets discarded when writing images in OCIv1 formats.

• --stop-signal signal — sets the default stop signal for the container. This signal gets sent when the container is stopped; the default is SIGINT.
• --unsetannotation annotation — unsets the image annotation, so it doesn't get inherited from the base image.
• --unsetlabel label — unsets the image label, so it doesn't get inherited from the base image.
• --user, -u user[:group] — sets the default user to use when running containers based on this image. The user can be a user name or UID, optionally followed by a group name or GID, separated by a colon (:). If you use names, the container should include entries for those names in its /etc/passwd and /etc/group files. 🫶
• --variant variant — sets the target architecture variant for any images built from this container. By default, if the container came from an image, that image's target architecture and variant info is kept; otherwise the host's architecture and variant get recorded. 🌈
• --volume, -v volume — adds a location in the directory tree that should be marked as a volume in any images built from this container. Can be used multiple times. If volume has a trailing - and is already set, the volume gets removed from the config. If volume is set to -, then all volumes get removed from the config. 🎀
• --workingdir directory — sets the initial working directory for containers based on images built from this container.

🌸 EXAMPLE 🌸

okay bestie, here's the part where we just show you, because honestly? reading is hard and doing is slay. every single one of these goes in a code block, character-for-character, no edits, no cap 💅

buildah config --author='Jane Austen' --workingdir='/etc/mycontainers'
containerID

author gets set to Jane Austen (a literal icon, she ate) and the working dir gets set to /etc/mycontainers. yes the containerID is on its own line up there — that's just how it wrapped, don't come for me 🙈

buildah config --entrypoint /entrypoint.sh containerID

setting an entrypoint the chill way, as one plain string. simple. clean. iconic ✨

buildah config --entrypoint '[ "/entrypoint.sh", "dev" ]' containerID

and here's the JSON-array form of the same thing, because sometimes you need the whole posse (/entrypoint.sh plus the arg dev) showing up together 🫶

buildah config --env foo=bar --env PATH=$PATH containerID

stacking env vars, one after the other. foo=bar and PATH pulls whatever $PATH is in your shell rn — so like, it's giving "inherited", okay? 😌

buildah config --env foo- containerID

not me removing foo entirely just by slapping a - at the end 💀 that trailing dash is the unset move, fr fr.

buildah config --label Name=Mycontainer --label  Version=1.0 containerID

two labels, one command. yes there are two spaces before Version in the original and yes we are keeping them, we don't touch the sacred text 📝

buildah config --label Name- containerID

and boom, Name label deleted, same trailing-dash energy as the env one. it's giving "be gone" 👑

buildah config --annotation note=myNote containerID

adding an annotation note set to myNote. annotations are the lowkey mysterious sibling of labels, iykyk 🌈

buildah config --annotation note-

removing that annotation. heads up bestie — this one has no containerID in the original example, so that's exactly what we're showing. don't add one, don't remove one, we keep it real 💖

buildah config --volume /usr/myvol containerID

declaring /usr/myvol as a volume, aka "this spot is for storing stuff, bestie" 🍓

buildah config --volume /usr/myvol- containerID

and un-declaring it with the dash. the dash is truly the main character of this whole page 😭

buildah config --port 1234 --port 8080 containerID

two ports, both plain numbers, both just... exposed. no protocol drama 🌸

buildah config --port 514/tcp --port 514/udp containerID

same port number 514 but for tcp and udp — she contains multitudes 💜

buildah config --env 1234=5678 containerID

numbers as an env var name, living their best numeric life. valid, apparently. slay 🔥

buildah config --env 1234- containerID

and unsetting the numeric one. dash stays undefeated ⭐

buildah config --os-version 10.0.19042.1645 containerID

setting the OS version to 10.0.19042.1645. look at all those lil numbers, so specific 🎀

buildah config --os-feature win32k containerID

adding the win32k OS feature ✨

buildah config --os-feature win32k- containerID

and removing it. dash. again. always the dash. periodt 💅

---

🦋 SEE ALSO 🦋

• buildah(1) — the mothership, the origin story, go read her 💖

---

that's the whole page, bestie!! you made it to the end and honestly? obsessed with you 🥹💖

this lil masterpiece lives in the buildah source, and the page itself is dated March 2017 — a classic, a timeless queen 👑 go forth and configure your containers, you absolute legend 🧚💜