1podman-container-runlabel(1)General Commands Manualpodman-container-runlabel(1)
2
3
4
6 podman-container-runlabel - Execute a command as described by a con‐
7 tainer-image label
8
9
11 podman container runlabel [options] label image [arg...]
12
13
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
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
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
130 Execute the run label of an image called foobar.
131
132 $ podman container runlabel run foobar
133
134
135
136 Execute the install label of an image called foobar with additional ar‐
137 guments.
138
139 $ podman container runlabel install foobar apples oranges
140
141
142
143 Display the contents of the run label of image foobar.
144
145 $ podman container runlabel --display run foobar
146
147
148
150 podman(1), crun(1), runc(8), containers-certs.d(5), containers-
151 auth.json(5), containers-registries.conf(5)
152
153
155 August 2021, Refinements by Valentin Rothberg (rothberg at redhat dot
156 com)
157
158
159 September 2018, Originally compiled by Brent Baude (bbaude at redhat
160 dot com)
161
162
163
164 podman-container-runlabel(1)