1buildah-run(1) General Commands Manual buildah-run(1)
2
3
4
6 buildah-run - Run a command inside of the container.
7
8
10 buildah run [options] [--] container command
11
12
14 Launches a container and runs the specified command in that container
15 using the container's root filesystem as a root filesystem, using con‐
16 figuration settings inherited from the container's image or as speci‐
17 fied using previous calls to the buildah config command. To execute
18 buildah run within an interactive shell, specify the --tty option.
19
20
22 --add-history
23
24
25 Add an entry to the history which will note what command is being in‐
26 voked. Defaults to false.
27
28
29 Note: You can also override the default value of --add-history by set‐
30 ting the BUILDAH_HISTORY environment variable. export BUILDAH_HIS‐
31 TORY=true
32
33
34 --cap-add=CAP_xxx
35
36
37 Add the specified capability to the set of capabilities which will be
38 granted to the specified command. Certain capabilities are granted by
39 default; this option can be used to add more beyond the defaults, which
40 may have been modified by --cap-add and --cap-drop options used with
41 the buildah from invocation which created the container.
42
43
44 --cap-drop=CAP_xxx
45
46
47 Add the specified capability from the set of capabilities which will be
48 granted to the specified command. The CAP_AUDIT_WRITE, CAP_CHOWN,
49 CAP_DAC_OVERRIDE, CAP_FOWNER, CAP_FSETID, CAP_KILL, CAP_MKNOD,
50 CAP_NET_BIND_SERVICE, CAP_SETFCAP, CAP_SETGID, CAP_SETPCAP, CAP_SETUID,
51 and CAP_SYS_CHROOT capabilities are granted by default; this option can
52 be used to remove them from the defaults, which may have been modified
53 by --cap-add and --cap-drop options used with the buildah from invoca‐
54 tion which created the container.
55
56
57 If a capability is specified to both the --cap-add and --cap-drop op‐
58 tions, it will be dropped, regardless of the order in which the options
59 were given.
60
61
62 --cgroupns how
63
64
65 Sets the configuration for the cgroup namespaces for the container.
66 The configured value can be "" (the empty string) or "private" to indi‐
67 cate that a new cgroup namespace should be created, or it can be "host"
68 to indicate that the cgroup namespace in which buildah itself is being
69 run should be reused.
70
71
72 --contextdir directory
73
74
75 Allows setting context directory for current RUN invocation. Specifying
76 a context directory causes RUN context to consider context directory as
77 root directory for specified source in --mount of type 'bind'.
78
79
80 --env, -e env=value
81
82
83 Temporarily add a value (e.g. env=value) to the environment for the
84 running process. Unlike buildah config --env, the environment will not
85 persist to later calls to buildah run or to the built image. Can be
86 used multiple times.
87
88
89 --hostname
90
91
92 Set the hostname inside of the running container.
93
94
95 --ipc how
96
97
98 Sets the configuration for the IPC namespaces for the container. The
99 configured value can be "" (the empty string) or "private" to indicate
100 that a new IPC namespace should be created, or it can be "host" to in‐
101 dicate that the IPC namespace in which buildah itself is being run
102 should be reused, or it can be the path to an IPC namespace which is
103 already in use by another process.
104
105
106 --isolation type
107
108
109 Controls what type of isolation is used for running the process. Rec‐
110 ognized types include oci (OCI-compatible runtime, the default), root‐
111 less (OCI-compatible runtime invoked using a modified configuration,
112 with --no-new-keyring added to its create invocation, reusing the
113 host's network and UTS namespaces, and creating private IPC, PID,
114 mount, and user namespaces; the default for unprivileged users), and
115 chroot (an internal wrapper that leans more toward chroot(1) than con‐
116 tainer technology, reusing the host's control group, network, IPC, and
117 PID namespaces, and creating private mount and UTS namespaces, and cre‐
118 ating user namespaces only when they're required for ID mapping).
119
120
121 Note: You can also override the default isolation type by setting the
122 BUILDAH_ISOLATION environment variable. export BUILDAH_ISOLATION=oci
123
124
125 --mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]
126
127
128 Attach a filesystem mount to the container
129
130
131 Current supported mount TYPES are bind, cache, secret and tmpfs. [1]
132 ⟨#Footnote1⟩
133
134
135 e.g.
136
137 type=bind,source=/path/on/host,destination=/path/in/container
138
139 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
140
141 type=cache,target=/path/in/container
142
143 Common Options:
144
145 · src, source: mount source spec for bind and volume. Mandatory for bind. If `from` is specified, `src` is the subpath in the `from` field.
146
147 · dst, destination, target: mount destination spec.
148
149 · ro, read-only: true or false (default).
150
151 Options specific to bind:
152
153 · bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2).
154
155 . bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive.
156
157 · from: stage or image name for the root of the source. Defaults to the build context.
158
159 · z: Set shared SELinux label on mounted destination. Use if SELinux is enabled on host machine.
160
161 · Z: Set private SELinux label on mounted destination. Use if SELinux is enabled on host machine.
162
163 Options specific to tmpfs:
164
165 · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
166
167 · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
168
169 · tmpcopyup: Path that is shadowed by the tmpfs mount is recursively copied up to the tmpfs itself.
170
171 Options specific to secret:
172
173 · id: the identifier for the secret passed into the `buildah bud --secret` or `podman build --secret` command.
174
175 Options specific to cache:
176
177 · id: Create a separate cache directory for a particular id.
178
179 · mode: File mode for new cache directory in octal. Default 0755.
180
181 · ro, readonly: read only cache if set.
182
183 · uid: uid for cache directory.
184
185 · gid: gid for cache directory.
186
187 · from: stage name for the root of the source. Defaults to host cache directory.
188
189 · z: Set shared SELinux label on mounted destination. Enabled by default if SELinux is enabled on the host machine.
190
191 · Z: Set private SELinux label on mounted destination. Use if SELinux is enabled on host machine.
192
193
194
195 --network, --net=mode
196
197
198 Sets the configuration for the network namespace for the container.
199
200
201 • none: no networking;
202
203 • host: use the host network stack. Note: the host mode gives
204 the container full access to local system services such as D-
205 bus and is therefore considered insecure;
206
207 • ns:path: path to a network namespace to join;
208
209 • private: create a new namespace for the container (default)
210
211
212
213 --no-hosts
214
215
216 Do not create /etc/hosts for the container.
217
218
219 By default, Buildah manages /etc/hosts, adding the container's own IP
220 address. --no-hosts disables this, and the image's /etc/hosts will be
221 preserved unmodified.
222
223
224 --no-pivot
225
226
227 Do not use pivot root to jail process inside rootfs. This should be
228 used whenever the rootfs is on top of a ramdisk.
229
230
231 Note: You can make this option the default by setting the BUIL‐
232 DAH_NOPIVOT environment variable. export BUILDAH_NOPIVOT=true
233
234
235 --pid how
236
237
238 Sets the configuration for the PID namespace for the container. The
239 configured value can be "" (the empty string) or "private" to indicate
240 that a new PID namespace should be created, or it can be "host" to in‐
241 dicate that the PID namespace in which buildah itself is being run
242 should be reused, or it can be the path to a PID namespace which is al‐
243 ready in use by another process.
244
245
246 --runtime path
247
248
249 The path to an alternate OCI-compatible runtime. Default is runc, or
250 crun when machine is configured to use cgroups V2.
251
252
253 Note: You can also override the default runtime by setting the BUIL‐
254 DAH_RUNTIME environment variable. export BUILDAH_RUNTIME=/usr/bin/crun
255
256
257 --runtime-flag flag
258
259
260 Adds global flags for the container runtime. To list the supported
261 flags, please consult the manpages of the selected container runtime.
262 Note: Do not pass the leading -- to the flag. To pass the runc flag
263 --log-format json to buildah run, the option given would be --runtime-
264 flag log-format=json.
265
266
267 --tty, --terminal, -t
268
269
270 By default a pseudo-TTY is allocated only when buildah's standard input
271 is attached to a pseudo-TTY. Setting the --tty option to true will
272 cause a pseudo-TTY to be allocated inside the container connecting the
273 user's "terminal" with the stdin and stdout stream of the container.
274 Setting the --tty option to false will prevent the pseudo-TTY from be‐
275 ing allocated.
276
277
278 --user user[:group]
279
280
281 Set the user to be used for running the command in the container. The
282 user can be specified as a user name or UID, optionally followed by a
283 group name or GID, separated by a colon (':'). If names are used, the
284 container should include entries for those names in its /etc/passwd and
285 /etc/group files.
286
287
288 --uts how
289
290
291 Sets the configuration for the UTS namespace for the container. The
292 configured value can be "" (the empty string) or "private" to indicate
293 that a new UTS namespace should be created, or it can be "host" to in‐
294 dicate that the UTS namespace in which buildah itself is being run
295 should be reused, or it can be the path to a UTS namespace which is al‐
296 ready in use by another process.
297
298
299 --volume, -v source:destination:options
300
301
302 Create a bind mount. If you specify, -v /HOST-DIR:/CONTAINER-DIR, Buil‐
303 dah bind mounts /HOST-DIR in the host to /CONTAINER-DIR in the Buildah
304 container. The OPTIONS are a comma delimited list and can be: [1]
305 ⟨#Footnote1⟩
306
307
308 • [rw|ro]
309
310 • [U]
311
312 • [z|Z]
313
314 • [[r]shared|[r]slave|[r]private]
315
316
317
318 The CONTAINER-DIR must be an absolute path such as /src/docs. The HOST-
319 DIR must be an absolute path as well. Buildah bind-mounts the HOST-DIR
320 to the path you specify. For example, if you supply /foo as the host
321 path, Buildah copies the contents of /foo to the container filesystem
322 on the host and bind mounts that into the container.
323
324
325 You can specify multiple -v options to mount one or more mounts to a
326 container.
327
328
329 Write Protected Volume Mounts
330
331
332 You can add the :ro or :rw suffix to a volume to mount it read-only or
333 read-write mode, respectively. By default, the volumes are mounted
334 read-write. See examples.
335
336
337 Chowning Volume Mounts
338
339
340 By default, Buildah does not change the owner and group of source vol‐
341 ume directories mounted into containers. If a container is created in a
342 new user namespace, the UID and GID in the container may correspond to
343 another UID and GID on the host.
344
345
346 The :U suffix tells Buildah to use the correct host UID and GID based
347 on the UID and GID within the container, to change the owner and group
348 of the source volume.
349
350
351 Labeling Volume Mounts
352
353
354 Labeling systems like SELinux require that proper labels are placed on
355 volume content mounted into a container. Without a label, the security
356 system might prevent the processes running inside the container from
357 using the content. By default, Buildah does not change the labels set
358 by the OS.
359
360
361 To change a label in the container context, you can add either of two
362 suffixes :z or :Z to the volume mount. These suffixes tell Buildah to
363 relabel file objects on the shared volumes. The z option tells Buildah
364 that two containers share the volume content. As a result, Buildah la‐
365 bels the content with a shared content label. Shared volume labels al‐
366 low all containers to read/write content. The Z option tells Buildah
367 to label the content with a private unshared label. Only the current
368 container can use a private volume.
369
370
371 By default bind mounted volumes are private. That means any mounts done
372 inside container will not be visible on the host and vice versa. This
373 behavior can be changed by specifying a volume mount propagation prop‐
374 erty.
375
376
377 When the mount propagation policy is set to shared, any mounts com‐
378 pleted inside the container on that volume will be visible to both the
379 host and container. When the mount propagation policy is set to slave,
380 one way mount propagation is enabled and any mounts completed on the
381 host for that volume will be visible only inside of the container. To
382 control the mount propagation property of the volume use the
383 :[r]shared, :[r]slave or :[r]private propagation flag. The propagation
384 property can be specified only for bind mounted volumes and not for in‐
385 ternal volumes or named volumes. For mount propagation to work on the
386 source mount point (the mount point where source dir is mounted on) it
387 has to have the right propagation properties. For shared volumes, the
388 source mount point has to be shared. And for slave volumes, the source
389 mount has to be either shared or slave. [1] ⟨#Footnote1⟩
390
391
392 Use df <source-dir> to determine the source mount and then use findmnt
393 -o TARGET,PROPAGATION <source-mount-dir> to determine propagation prop‐
394 erties of source mount, if findmnt utility is not available, the source
395 mount point can be determined by looking at the mount entry in
396 /proc/self/mountinfo. Look at optional fields and see if any propaga‐
397 tion properties are specified. shared:X means the mount is shared,
398 master:X means the mount is slave and if nothing is there that means
399 the mount is private. [1] ⟨#Footnote1⟩
400
401
402 To change propagation properties of a mount point use the mount com‐
403 mand. For example, to bind mount the source directory /foo do mount
404 --bind /foo /foo and mount --make-private --make-shared /foo. This will
405 convert /foo into a shared mount point. The propagation properties of
406 the source mount can be changed directly. For instance if / is the
407 source mount for /foo, then use mount --make-shared / to convert / into
408 a shared mount.
409
410
411 --workingdir directory
412
413
414 Temporarily set the working directory for the running process. Unlike
415 buildah config --workingdir, the workingdir will not persist to later
416 calls to buildah run or the built image.
417
418
419 NOTE: End parsing of options with the -- option, so that other options
420 can be passed to the command inside of the container.
421
422
424 buildah run containerID -- ps -auxw
425
426
427 buildah run --hostname myhost containerID -- ps -auxw
428
429
430 buildah run containerID -- sh -c 'echo $PATH'
431
432
433 buildah run --runtime-flag log-format=json containerID /bin/bash
434
435
436 buildah run --runtime-flag debug containerID /bin/bash
437
438
439 buildah run --tty containerID /bin/bash
440
441
442 buildah run --tty=false containerID ls /
443
444
445 buildah run --volume /path/on/host:/path/in/container:ro,z containerID
446 sh
447
448
449 buildah run -v /path/on/host:/path/in/container:z,U containerID sh
450
451
452 buildah run --mount type=bind,src=/tmp/on:host,dst=/in:container,ro
453 containerID sh
454
455
457 buildah(1), buildah-from(1), buildah-config(1), namespaces(7),
458 pid_namespaces(7), crun(1), runc(8)
459
460
462 1: The Buildah project is committed to inclusivity, a core value of
463 open source. The master and slave mount propagation terminology used
464 here is problematic and divisive, and should be changed. However, these
465 terms are currently used within the Linux kernel and must be used as-is
466 at this time. When the kernel maintainers rectify this usage, Buildah
467 will follow suit immediately.
468
469
470
471buildah March 2017 buildah-run(1)