1buildah-run(1) General Commands Manual buildah-run(1)
2
6 buildah-run - Run a command inside of the container.
7
10 buildah run [options] [--] container command
11
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
22 --add-history
23 Add an entry to the history which will note what command is being in‐
26 voked. Defaults to false.
27 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 --cap-add=CAP_xxx
35 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 --cap-drop=CAP_xxx
45 Drop the specified capability from the set of capabilities which will
48 be granted to the specified command. The CAP_CHOWN, CAP_DAC_OVERRIDE,
49 CAP_FOWNER, CAP_FSETID, CAP_KILL, CAP_NET_BIND_SERVICE, CAP_SETFCAP,
50 CAP_SETGID, CAP_SETPCAP, and CAP_SETUID capabilities are granted by de‐
51 fault; this option can be used to remove them from the defaults, which
52 may have been modified by --cap-add and --cap-drop options used with
53 the buildah from invocation which created the container. The list of
54 default capabilities is managed in containers.conf(5).
55 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 --cgroupns how
63 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 --contextdir directory
73 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 --env, -e env=value
81 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 --hostname
90 Set the hostname inside of the running container.
93 --ipc how
96 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 --isolation type
107 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 Note: You can also override the default isolation type by setting the
122 BUILDAH_ISOLATION environment variable. export BUILDAH_ISOLATION=oci
123 --mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]
126 Attach a filesystem mount to the container
129 Current supported mount TYPES are bind, cache, secret and tmpfs. [1]
132 ⟨#Footnote1⟩
133 e.g.
136 type=bind,source=/path/on/host,destination=/path/in/container
138 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
140 type=cache,target=/path/in/container
142 Common Options:
144 · 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 · dst, destination, target: mount destination spec.
148 · ro, read-only: true or false (default).
150 Options specific to bind:
152 · bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2).
154 . bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive.
156 · from: stage or image name for the root of the source. Defaults to the build context.
158 · z: Set shared SELinux label on mounted destination. Use if SELinux is enabled on host machine.
160 · Z: Set private SELinux label on mounted destination. Use if SELinux is enabled on host machine.
162 Options specific to tmpfs:
164 · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
166 · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
168 · tmpcopyup: Path that is shadowed by the tmpfs mount is recursively copied up to the tmpfs itself.
170 Options specific to secret:
172 · id: the identifier for the secret passed into the `buildah bud --secret` or `podman build --secret` command.
174 Options specific to cache:
176 · id: Create a separate cache directory for a particular id.
178 · mode: File mode for new cache directory in octal. Default 0755.
180 · ro, readonly: read only cache if set.
182 · uid: uid for cache directory.
184 · gid: gid for cache directory.
186 · from: stage name for the root of the source. Defaults to host cache directory.
188 · z: Set shared SELinux label on mounted destination. Enabled by default if SELinux is enabled on the host machine.
190 · Z: Set private SELinux label on mounted destination. Use if SELinux is enabled on host machine.
192 --network, --net=mode
196 Sets the configuration for the network namespace for the container.
199 Valid mode values are:
202 • none: no networking. Invalid if using --dns, --dns-opt, or
205 --dns-search;
206 • host: use the host network stack. Note: the host mode gives
208 the container full access to local system services such as D-
209 bus and is therefore considered insecure;
210 • ns:path: path to a network namespace to join;
212 • private: create a new namespace for the container (default)
214 • <network name|ID>: Join the network with the given name or ID,
216 e.g. use --network mynet to join the network with the name
217 mynet. Only supported for rootful users.
218 • slirp4netns[:OPTIONS,...]: use slirp4netns(1) to create a user
220 network stack. This is the default for rootless containers. It
221 is possible to specify these additional options, they can also
222 be set with network_cmd_options in containers.conf:
223 • allow_host_loopback=true|false: Allow slirp4netns to reach
225 the host loopback IP (default is 10.0.2.2 or the second IP
226 from slirp4netns cidr subnet when changed, see the cidr op‐
227 tion below). The default is false.
228 • mtu=MTU: Specify the MTU to use for this network. (Default
230 is 65520).
231 • cidr=CIDR: Specify ip range to use for this network. (De‐
233 fault is 10.0.2.0/24).
234 • enable_ipv6=true|false: Enable IPv6. Default is true. (Re‐
236 quired for outbound_addr6).
237 • outbound_addr=INTERFACE: Specify the outbound interface
239 slirp binds to (ipv4 traffic only).
240 • outbound_addr=IPv4: Specify the outbound ipv4 address slirp
242 binds to.
243 • outbound_addr6=INTERFACE: Specify the outbound interface
245 slirp binds to (ipv6 traffic only).
246 • outbound_addr6=IPv6: Specify the outbound ipv6 address slirp
248 binds to.
249 • pasta[:OPTIONS,...]: use pasta(1) to create a user-mode net‐
253 working stack.
254 This is only supported in rootless mode.
255 By default, IPv4 and IPv6 addresses and routes, as well as the
256 pod interface name, are copied from the host. If port forward‐
257 ing isn't configured, ports are forwarded dynamically as ser‐
258 vices are bound on either side (init namespace or container
259 namespace). Port forwarding preserves the original source IP
260 address. Options described in pasta(1) can be specified as
261 comma-separated arguments.
262 In terms of pasta(1) options, --config-net is given by de‐
263 fault, in order to configure networking when the container is
264 started, and --no-map-gw is also assumed by default, to avoid
265 direct access from container to host using the gateway ad‐
266 dress. The latter can be overridden by passing --map-gw in the
267 pasta-specific options (despite not being an actual pasta(1)
268 option).
269 Also, -t none and -u none are passed to disable automatic port
270 forwarding based on bound ports. Similarly, -T none and -U
271 none are given to disable the same functionality from con‐
272 tainer to host.
273 Some examples:
274 • pasta:--map-gw: Allow the container to directly reach the
276 host using the gateway address.
277 • pasta:--mtu,1500: Specify a 1500 bytes MTU for the tap in‐
279 terface in the container.
280 • pasta:--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-for‐
282 ward,10.0.2.3,-m,1500,--no-ndp,--no-dhcpv6,--no-dhcp, equiv‐
283 alent to default slirp4netns(1) options: disable IPv6, as‐
284 sign 10.0.2.0/24 to the tap0 interface in the container,
285 with gateway 10.0.2.3, enable DNS forwarder reachable at
286 10.0.2.3, set MTU to 1500 bytes, disable NDP, DHCPv6 and
287 DHCP support.
288 • pasta:-I,tap0,--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-
290 forward,10.0.2.3,--no-ndp,--no-dhcpv6,--no-dhcp, equivalent
291 to default slirp4netns(1) options with Podman overrides:
292 same as above, but leave the MTU to 65520 bytes
293 • pasta:-t,auto,-u,auto,-T,auto,-U,auto: enable automatic port
295 forwarding based on observed bound ports from both host and
296 container sides
297 • pasta:-T,5201: enable forwarding of TCP port 5201 from con‐
299 tainer to host, using the loopback interface instead of the
300 tap interface for improved performance
301 --no-hostname
307 Do not create the /etc/hostname file in the container for RUN instruc‐
310 tions.
311 By default, Buildah manages the /etc/hostname file, adding the con‐
314 tainer's own hostname. When the --no-hostname option is set, the im‐
315 age's /etc/hostname will be preserved unmodified if it exists.
316 --no-hosts
319 Do not create the /etc/hosts file in the container for RUN instruc‐
322 tions.
323 By default, Buildah manages /etc/hosts, adding the container's own IP
326 address. --no-hosts disables this, and the image's /etc/hosts will be
327 preserved unmodified.
328 --no-pivot
331 Do not use pivot root to jail process inside rootfs. This should be
334 used whenever the rootfs is on top of a ramdisk.
335 Note: You can make this option the default by setting the BUIL‐
338 DAH_NOPIVOT environment variable. export BUILDAH_NOPIVOT=true
339 --pid how
342 Sets the configuration for the PID namespace for the container. The
345 configured value can be "" (the empty string) or "private" to indicate
346 that a new PID namespace should be created, or it can be "host" to in‐
347 dicate that the PID namespace in which buildah itself is being run
348 should be reused, or it can be the path to a PID namespace which is al‐
349 ready in use by another process.
350 --runtime path
353 The path to an alternate OCI-compatible runtime. Default is runc, or
356 crun when machine is configured to use cgroups V2.
357 Note: You can also override the default runtime by setting the BUIL‐
360 DAH_RUNTIME environment variable. export BUILDAH_RUNTIME=/usr/bin/crun
361 --runtime-flag flag
364 Adds global flags for the container runtime. To list the supported
367 flags, please consult the manpages of the selected container runtime.
368 Note: Do not pass the leading -- to the flag. To pass the runc flag
369 --log-format json to buildah run, the option given would be --runtime-
370 flag log-format=json.
371 --tty, --terminal, -t
374 By default a pseudo-TTY is allocated only when buildah's standard input
377 is attached to a pseudo-TTY. Setting the --tty option to true will
378 cause a pseudo-TTY to be allocated inside the container connecting the
379 user's "terminal" with the stdin and stdout stream of the container.
380 Setting the --tty option to false will prevent the pseudo-TTY from be‐
381 ing allocated.
382 --user user[:group]
385 Set the user to be used for running the command in the container. The
388 user can be specified as a user name or UID, optionally followed by a
389 group name or GID, separated by a colon (':'). If names are used, the
390 container should include entries for those names in its /etc/passwd and
391 /etc/group files.
392 --uts how
395 Sets the configuration for the UTS namespace for the container. The
398 configured value can be "" (the empty string) or "private" to indicate
399 that a new UTS namespace should be created, or it can be "host" to in‐
400 dicate that the UTS namespace in which buildah itself is being run
401 should be reused, or it can be the path to a UTS namespace which is al‐
402 ready in use by another process.
403 --volume, -v source:destination:options
406 Create a bind mount. If you specify, -v /HOST-DIR:/CONTAINER-DIR, Buil‐
409 dah bind mounts /HOST-DIR in the host to /CONTAINER-DIR in the Buildah
410 container. The OPTIONS are a comma delimited list and can be: [1]
411 ⟨#Footnote1⟩
412 • [rw|ro]
415 • [U]
417 • [z|Z]
419 • [[r]shared|[r]slave|[r]private]
421 The CONTAINER-DIR must be an absolute path such as /src/docs. The HOST-
425 DIR must be an absolute path as well. Buildah bind-mounts the HOST-DIR
426 to the path you specify. For example, if you supply /foo as the host
427 path, Buildah copies the contents of /foo to the container filesystem
428 on the host and bind mounts that into the container.
429 You can specify multiple -v options to mount one or more mounts to a
432 container.
433 Write Protected Volume Mounts
436 You can add the :ro or :rw suffix to a volume to mount it read-only or
439 read-write mode, respectively. By default, the volumes are mounted
440 read-write. See examples.
441 Chowning Volume Mounts
444 By default, Buildah does not change the owner and group of source vol‐
447 ume directories mounted into containers. If a container is created in a
448 new user namespace, the UID and GID in the container may correspond to
449 another UID and GID on the host.
450 The :U suffix tells Buildah to use the correct host UID and GID based
453 on the UID and GID within the container, to change the owner and group
454 of the source volume.
455 Labeling Volume Mounts
458 Labeling systems like SELinux require that proper labels are placed on
461 volume content mounted into a container. Without a label, the security
462 system might prevent the processes running inside the container from
463 using the content. By default, Buildah does not change the labels set
464 by the OS.
465 To change a label in the container context, you can add either of two
468 suffixes :z or :Z to the volume mount. These suffixes tell Buildah to
469 relabel file objects on the shared volumes. The z option tells Buildah
470 that two containers share the volume content. As a result, Buildah la‐
471 bels the content with a shared content label. Shared volume labels al‐
472 low all containers to read/write content. The Z option tells Buildah
473 to label the content with a private unshared label. Only the current
474 container can use a private volume.
475 By default bind mounted volumes are private. That means any mounts done
478 inside container will not be visible on the host and vice versa. This
479 behavior can be changed by specifying a volume mount propagation prop‐
480 erty.
481 When the mount propagation policy is set to shared, any mounts com‐
484 pleted inside the container on that volume will be visible to both the
485 host and container. When the mount propagation policy is set to slave,
486 one way mount propagation is enabled and any mounts completed on the
487 host for that volume will be visible only inside of the container. To
488 control the mount propagation property of the volume use the
489 :[r]shared, :[r]slave or :[r]private propagation flag. The propagation
490 property can be specified only for bind mounted volumes and not for in‐
491 ternal volumes or named volumes. For mount propagation to work on the
492 source mount point (the mount point where source dir is mounted on) it
493 has to have the right propagation properties. For shared volumes, the
494 source mount point has to be shared. And for slave volumes, the source
495 mount has to be either shared or slave. [1] ⟨#Footnote1⟩
496 Use df <source-dir> to determine the source mount and then use findmnt
499 -o TARGET,PROPAGATION <source-mount-dir> to determine propagation prop‐
500 erties of source mount, if findmnt utility is not available, the source
501 mount point can be determined by looking at the mount entry in
502 /proc/self/mountinfo. Look at optional fields and see if any propaga‐
503 tion properties are specified. shared:X means the mount is shared,
504 master:X means the mount is slave and if nothing is there that means
505 the mount is private. [1] ⟨#Footnote1⟩
506 To change propagation properties of a mount point use the mount com‐
509 mand. For example, to bind mount the source directory /foo do mount
510 --bind /foo /foo and mount --make-private --make-shared /foo. This will
511 convert /foo into a shared mount point. The propagation properties of
512 the source mount can be changed directly. For instance if / is the
513 source mount for /foo, then use mount --make-shared / to convert / into
514 a shared mount.
515 --workingdir directory
518 Temporarily set the working directory for the running process. Unlike
521 buildah config --workingdir, the workingdir will not persist to later
522 calls to buildah run or the built image.
523 NOTE: End parsing of options with the -- option, so that other options
526 can be passed to the command inside of the container.
527
530 buildah run containerID -- ps -auxw
531 buildah run --hostname myhost containerID -- ps -auxw
534 buildah run containerID -- sh -c 'echo $PATH'
537 buildah run --runtime-flag log-format=json containerID /bin/bash
540 buildah run --runtime-flag debug containerID /bin/bash
543 buildah run --tty containerID /bin/bash
546 buildah run --tty=false containerID ls /
549 buildah run --volume /path/on/host:/path/in/container:ro,z containerID
552 sh
553 buildah run -v /path/on/host:/path/in/container:z,U containerID sh
556 buildah run --mount type=bind,src=/tmp/on:host,dst=/in:container,ro
559 containerID sh
560
563 buildah(1), buildah-from(1), buildah-config(1), namespaces(7),
564 pid_namespaces(7), crun(1), runc(8), containers.conf(5)
565
568 1: The Buildah project is committed to inclusivity, a core value of
569 open source. The master and slave mount propagation terminology used
570 here is problematic and divisive, and should be changed. However, these
571 terms are currently used within the Linux kernel and must be used as-is
572 at this time. When the kernel maintainers rectify this usage, Buildah
573 will follow suit immediately.
574buildah March 2017 buildah-run(1)