podman-container-runlabel(1)

1podman-container-runlabel(1)General Commands Manualpodman-container-runlabel(1)
2
3
4

NAME

6       podman-container-runlabel  -  Execute  a command as described by a con‐
7       tainer-image label
8
9

SYNOPSIS

11       podman container runlabel [options] label image [arg...]
12
13

DESCRIPTION

15       podman container runlabel reads the specified label of  the  image  and
16       executes  it as command on the host.  If the label does not exist, Pod‐
17       man exits with an error.  Additional arguments are appended to the com‐
18       mand.
19
20
21       Historically, container images describe the contents (e.g., layers) and
22       how a container runtime (e.g., crun(1) or runc(1))  executes  the  con‐
23       tainer.  For instance, an image may set the environment and the command
24       in its configuration.  However, a container image cannot directly spec‐
25       ify  how  a container engine such as Podman executes it.  For instance,
26       an image configuration does not include information about log  drivers,
27       namespaces, or which capabilities it needs to run correctly.
28
29
30       podman  container runlabel addresses the limitation of container images
31       in a simple yet efficient way.  Podman reads the contents of the  label
32       and  interpret  it as a command that is executed on the host.  This way
33       an image can describe exactly how it is executed by  Podman.   For  in‐
34       stance,  a  label  with  the  content /usr/bin/podman run -d --pid=host
35       --privileged \${IMAGE} instructs the image to  be  executed  in  a  de‐
36       tached,  privileged  container  that  is using the PID namespace of the
37       host.  This lifts the self-description of a container image from "what"
38       to "how".
39
40
41       Note  that  the runlabel command is intended to be run in trusted envi‐
42       ronments exclusively.  Using the command on  untrusted  images  is  not
43       recommended.
44
45

VARIABLES

47       The  contents  of a label may refer to the following variables which is
48       substituted while processing the label.
49
50
51       IMAGE The name of the image.  When executing podman container  runlabel
52       label fedora the IMAGE variable is replaced with fedora.  Valid formats
53       are IMAGE, $IMAGE, ${IMAGE} and =IMAGE.
54
55
56       NAME As specified by the --name option.  The format is identical to the
57       one of the IMAGE attribute.
58
59
60       PWD Will be replaced with the current working directory.
61
62

OPTIONS

64   --authfile=path
65       Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
66       ers/auth.json on Linux, and $HOME/.config/containers/auth.json on  Win‐
67       dows/macOS.   The file is created by podman login. If the authorization
68       state is not found there, $HOME/.docker/config.json is  checked,  which
69       is set using docker login.
70
71
72       Note:  There is also the option to override the default path of the au‐
73       thentication file by setting the REGISTRY_AUTH_FILE  environment  vari‐
74       able. This can be done with export REGISTRY_AUTH_FILE=path.
75
76
77   --cert-dir=path
78       Use  certificates at path (*.crt, *.cert, *.key) to connect to the reg‐
79       istry. (Default: /etc/containers/certs.d) For details, see  containers-
80       certs.d(5).   (This  option  is  not  available  with the remote Podman
81       client, including Mac and Windows (excluding WSL2) machines)
82
83
84   --creds=[username[:password]]
85       The [username[:password]] to use to authenticate with the registry,  if
86       required.   If  one  or  both  values  are not supplied, a command line
87       prompt appears and the value can be entered. The  password  is  entered
88       without echo.
89
90
91       Note  that  the  specified  credentials  are  only used to authenticate
92       against target registries.  They are not used for mirrors or  when  the
93       registry gets rewritten (see containers-registries.conf(5)); to authen‐
94       ticate against those consider using a containers-auth.json(5) file.
95
96
97   --display
98       Display the label's value of the image having populated its environment
99       variables.  The runlabel command is not executed if --display is speci‐
100       fied.
101
102
103   --help, -h
104       Print usage statement
105
106
107   --name, -n=name
108       Use this name for creating content for the container.   If  not  speci‐
109       fied, name defaults to the name of the image.
110
111
112   --quiet, -q
113       Suppress output information when pulling images
114
115
116   --replace
117       If a container exists with the current name, it is stopped, deleted and
118       a new container is created from this image.
119
120
121   --tls-verify
122       Require HTTPS and verify certificates when contacting  registries  (de‐
123       fault: true).  If explicitly set to true, TLS verification is used.  If
124       set to false, TLS verification is not used.  If not specified, TLS ver‐
125       ification  is  used unless the target registry is listed as an insecure
126       registry in containers-registries.conf(5)
127
128

EXAMPLES

130       Execute the run label of an image called foobar.
131
132
133              $ podman container runlabel run foobar
134
135
136
137       Execute the install label of an image called foobar with additional ar‐
138       guments.
139
140
141              $ podman container runlabel install foobar apples oranges
142
143
144
145       Display the contents of the run label of image foobar.
146
147
148              $ podman container runlabel --display run foobar
149
150
151

HISTORY

158       August 2021, Refinements by Valentin Rothberg (rothberg at  redhat  dot
159       com)
160
161
162       September  2018,  Originally  compiled by Brent Baude (bbaude at redhat
163       dot com)
164
165
166
167                                                  podman-container-runlabel(1)