NAME

       podman-container-runlabel - Execute a command as described by a container-image label

SYNOPSIS

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

DESCRIPTION

       podman  container runlabel reads the specified label of the image and executes it as command on the host.
       If the label does not exist, Podman exits with an  error.   Additional  arguments  are  appended  to  the
       command.

       Historically,  container  images  describe the contents (e.g., layers) and how a container runtime (e.g.,
       crun(1) or runc(1)) executes the container.  For instance, an image  may  set  the  environment  and  the
       command  in its configuration.  However, a container image cannot directly specify how a container engine
       such as Podman executes it.  For instance, an image configuration does not include information about  log
       drivers, namespaces, or which capabilities it needs to run correctly.

       podman  container  runlabel  addresses  the limitation of container images in a simple yet efficient way.
       Podman reads the contents of the label and interpret it as a command that is executed on the host.   This
       way  an  image can describe exactly how it is executed by Podman.  For instance, a label with the content
       /usr/bin/podman run -d --pid=host --privileged  \${IMAGE}  instructs  the  image  to  be  executed  in  a
       detached,  privileged  container  that  is  using  the  PID  namespace of the host.  This lifts the self-
       description of a container image from "what" to "how".

       Note that the runlabel command is intended to be run in  trusted  environments  exclusively.   Using  the
       command on untrusted images is not recommended.

VARIABLES

       The  contents  of  a label may refer to the following variables which is substituted while processing the
       label.

       IMAGE The name of the image.  When executing podman container runlabel label fedora the IMAGE variable is
       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 Will be 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.   The  file  is  created  by  podman login. If the
       authorization state is not found there, $HOME/.docker/config.json is checked, which is set  using  docker
       login.

       Note:  There  is  also  the option to override the default path of the authentication file by setting the
       REGISTRY_AUTH_FILE environment variable. This can be done 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.

       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.

   --display
       Display the label's value of the image having populated its environment variables.  The runlabel  command
       is not executed if --display is specified.

   --help, -h
       Print usage statement

   --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

   --replace
       If  a  container exists with the current name, it is stopped, deleted and a new container is created from
       this image.

   --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.

       $ podman container runlabel --display run foobar

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)

                                                                                    podman-container-runlabel(1)