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)