podman-con...er-runlabel(1)

💖 podman-container-runlabel — the manual page, but make it cute 💖

okay so you're reading the General Commands Manual page for podman-container-runlabel, and bestie, this one is a whole vibe. Let's get into it. ✨

---

✨ NAME ✨

podman-container-runlabel — execute a command as described by a container-image label. that's it, that's the whole job. 💅

---

🦋 SYNOPSIS 🦋

podman container runlabel [options] label image [arg...]

---

🌸 DESCRIPTION 🌸

okay so here's the tea: podman container runlabel reads the label you asked for off the image, and then executes it as a command on the host. If that label doesn't exist? Podman just exits with an error, no drama, no mercy. 😭 And any extra arguments you tack on get appended to the command. slay.

so, history lesson but make it fun 🧚: container images have always described the contents (like, the layers) and how a container runtime (think crun(1) or runc(1)) executes the container. Like, an image can set the environment and the command in its config. but — and this is the plot twist — a container image cannot directly specify how a container engine like Podman executes it. an image config has zero info about log drivers, namespaces, or which capabilities it needs to run correctly. it's giving "i have no idea what i want." 💀

podman container runlabel fixes that limitation in a simple yet efficient way. Podman reads the label's contents and interprets it as a command that gets executed on the host. so the image itself gets to describe exactly how Podman runs it. for instance, a label with the content:

/usr/bin/podman run -d --pid=host --privileged \${IMAGE}

instructs that the image be executed in a detached, privileged container using the PID namespace of the host. iconic. this lifts the self-description of a container image from "what" to "how". main character energy fr fr. 👑

bestie, listen. the runlabel command is intended to be run in trusted environments exclusively. using it on untrusted images is not recommended. no cap. do not do it. 🙈

---

🎀 VARIABLES 🎀

the contents of a label can refer to these variables, which get substituted while the label is being processed. 💫

• IMAGE — the name of the image. when you run podman container runlabel label fedora, the IMAGE variable gets replaced with fedora. valid formats are IMAGE, $IMAGE, ${IMAGE} and =IMAGE.
• NAME — as specified by the --name option. the format is identical to the one of the IMAGE attribute.
• PWD — gets replaced with the current working directory.

---

💅 OPTIONS 💅

• --authfile=path — path of the authentication file. default is ${XDG_RUNTIME_DIR}/containers/auth.json on Linux, and $HOME/.config/containers/auth.json on Windows/macOS. this file is created by podman login. if the authorization state isn't found there, $HOME/.docker/config.json gets checked, which is set using docker login.

note: there's also the option to override the default path of the authentication file by setting the REGISTRY_AUTH_FILE environment variable. you do that with export REGISTRY_AUTH_FILE=path. 🫶

• --cert-dir=path — use certificates at path (*.crt, *.cert, *.key) to connect to the registry. (default: /etc/containers/certs.d) for details, see containers-certs.d(5). (this option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines)
• --creds=[username[:password]] — the [username[:password]] to use to authenticate with the registry, if required. if one or both values are not supplied, a command line prompt appears and the value can be entered. the password is entered without echo. lowkey spooky but it's for your own good. 🕵️

note that the specified credentials are only used to authenticate against target registries. they are not used for mirrors or when the registry gets rewritten (see containers-registries.conf(5)); to authenticate against those, consider using a containers-auth.json(5) file. iykyk.

• --display — display the label's value of the image, having populated its environment variables. the runlabel command is not executed if --display is specified. it's just looking, not touching. 👀
• --help, -h — print usage statement. classic.
• --name, -n=name — use this name for creating content for the container. if not specified, name defaults to the name of the image.
• --quiet, -q — suppress output information when pulling images. shhh. 🤫
• --replace — if a container exists with the current name, it is stopped, deleted and a new container is created from this image. out with the old, in with the new. ✨
• --tls-verify — require HTTPS and verify certificates when contacting registries (default: true). if explicitly set to true, TLS verification is used. if set to false, TLS verification is not used. if not specified, TLS verification is used unless the target registry is listed as an insecure registry in containers-registries.conf(5).

---

🌈 EXAMPLES 🌈

execute the run label of an image called foobar. 🍓

$ podman container runlabel run foobar

execute the install label of an image called foobar with additional arguments.

$ podman container runlabel install foobar apples oranges

display the contents of the run label of image foobar. (just peeking, bestie 💜)

$ podman container runlabel --display run foobar

re-run a container using a label that sets a fixed container name. the --replace flag ensures any existing container is removed first.

$ podman ps -a
CONTAINER ID  IMAGE                             COMMAND               CREATED         STATUS                     PORTS       NAMES
1254c038d892  docker.io/library/busybox:latest  echo Hello from r...  26 seconds ago  Exited (0) 26 seconds ago              test-runlabel

$ podman container runlabel --replace RUN runlabel-test
Hello from runlabel

$ podman ps -a
CONTAINER ID  IMAGE                             COMMAND               CREATED        STATUS                    PORTS       NAMES
28efd9600d0c  docker.io/library/busybox:latest  echo Hello from r...  4 seconds ago  Exited (0) 4 seconds ago              test-runlabel

this command is useful when the label uses a fixed name (e.g., --name mycontainer) and you want to repeatedly run it without manually removing the previous container. no manual cleanup era, we love to see it. 🎀

---

🔥 SEE ALSO 🔥

podman(1), crun(1), runc(8), containers-certs.d(5), containers-auth.json(5), containers-registries.conf(5)

---

👑 HISTORY 👑

• August 2021, Refinements by Valentin Rothberg (rothberg at redhat dot com)
• September 2018, Originally compiled by Brent Baude (bbaude at redhat dot com)

---

and that's the whole page, bestie!! 🦋 the footer of this page is literally just the truncated manual name again — podman-con...er-runlabel(1) — sitting pretty at the bottom of the General Commands Manual, and honestly? it ate. go forth and run those labels, but only on images you trust. periodt. 💖✨🎀