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 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 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 --cni-config-dir=directory
63 Location of CNI configuration files which will dictate which plugins
66 will be used to configure network interfaces and routing inside the
67 running container, if the container will be run in its own network
68 namespace, and networking is not disabled.
69 --cni-plugin-path=directory[:directory[:directory[...]]]
72 List of directories in which the CNI plugins which will be used for
75 configuring network namespaces can be found.
76 --env, -e env=value
79 Temporarily add a value (e.g. env=value) to the environment for the
82 running process. Unlike buildah config --env, the environment will not
83 persist to later calls to buildah run or to the built image. Can be
84 used multiple times.
85 --hostname
88 Set the hostname inside of the running container.
91 --ipc how
94 Sets the configuration for the IPC namespaces for the container. The
97 configured value can be "" (the empty string) or "private" to indicate
98 that a new IPC namespace should be created, or it can be "host" to in‐
99 dicate that the IPC namespace in which buildah itself is being run
100 should be reused, or it can be the path to an IPC namespace which is
101 already in use by another process.
102 --isolation type
105 Controls what type of isolation is used for running the process. Rec‐
108 ognized types include oci (OCI-compatible runtime, the default), root‐
109 less (OCI-compatible runtime invoked using a modified configuration,
110 with --no-new-keyring added to its create invocation, reusing the
111 host's network and UTS namespaces, and creating private IPC, PID,
112 mount, and user namespaces; the default for unprivileged users), and
113 chroot (an internal wrapper that leans more toward chroot(1) than con‐
114 tainer technology, reusing the host's control group, network, IPC, and
115 PID namespaces, and creating private mount and UTS namespaces, and cre‐
116 ating user namespaces only when they're required for ID mapping).
117 Note: You can also override the default isolation type by setting the
120 BUILDAH_ISOLATION environment variable. export BUILDAH_ISOLATION=oci
121 --mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]
124 Attach a filesystem mount to the container
127 Current supported mount TYPES are bind, and tmpfs. [1] ⟨#Footnote1⟩
130 e.g.
133 type=bind,source=/path/on/host,destination=/path/in/container
135 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
137 Common Options:
139 · src, source: mount source spec for bind and volume. Mandatory for bind.
141 · dst, destination, target: mount destination spec.
143 · ro, read-only: true or false (default).
145 Options specific to bind:
147 · bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2).
149 . bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive.
151 Options specific to tmpfs:
153 · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
155 · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
157 --network, --net=mode
161 Sets the configuration for the network namespace for the container.
164 • none: no networking;
167 • host: use the host network stack. Note: the host mode gives
169 the container full access to local system services such as D-
170 bus and is therefore considered insecure;
171 • ns:path: path to a network namespace to join;
173 • private: create a new namespace for the container (default)
175 --pid how
179 Sets the configuration for the PID namespace for the container. The
182 configured value can be "" (the empty string) or "private" to indicate
183 that a new PID namespace should be created, or it can be "host" to in‐
184 dicate that the PID namespace in which buildah itself is being run
185 should be reused, or it can be the path to a PID namespace which is al‐
186 ready in use by another process.
187 --runtime path
190 The path to an alternate OCI-compatible runtime. Default is runc, or
193 crun when machine is configured to use cgroups V2.
194 Note: You can also override the default runtime by setting the BUIL‐
197 DAH_RUNTIME environment variable. export BUILDAH_RUNTIME=/usr/bin/crun
198 --runtime-flag flag
201 Adds global flags for the container runtime. To list the supported
204 flags, please consult the manpages of the selected container runtime.
205 Note: Do not pass the leading -- to the flag. To pass the runc flag
206 --log-format json to buildah run, the option given would be --runtime-
207 flag log-format=json.
208 --no-pivot
211 Do not use pivot root to jail process inside rootfs. This should be
214 used whenever the rootfs is on top of a ramdisk.
215 Note: You can make this option the default by setting the BUIL‐
218 DAH_NOPIVOT environment variable. export BUILDAH_NOPIVOT=true
219 -t, --tty, --terminal
222 By default a pseudo-TTY is allocated only when buildah's standard input
225 is attached to a pseudo-TTY. Setting the --tty option to true will
226 cause a pseudo-TTY to be allocated inside the container connecting the
227 user's "terminal" with the stdin and stdout stream of the container.
228 Setting the --tty option to false will prevent the pseudo-TTY from be‐
229 ing allocated.
230 --user user[:group]
233 Set the user to be used for running the command in the container. The
236 user can be specified as a user name or UID, optionally followed by a
237 group name or GID, separated by a colon (':'). If names are used, the
238 container should include entries for those names in its /etc/passwd and
239 /etc/group files.
240 --uts how
243 Sets the configuration for the UTS namespace for the container. The
246 configured value can be "" (the empty string) or "private" to indicate
247 that a new UTS namespace should be created, or it can be "host" to in‐
248 dicate that the UTS namespace in which buildah itself is being run
249 should be reused, or it can be the path to a UTS namespace which is al‐
250 ready in use by another process.
251 --volume, -v source:destination:options
254 Create a bind mount. If you specify, -v /HOST-DIR:/CONTAINER-DIR, Buil‐
257 dah bind mounts /HOST-DIR in the host to /CONTAINER-DIR in the Buildah
258 container. The OPTIONS are a comma delimited list and can be: [1]
259 ⟨#Footnote1⟩
260 • [rw|ro]
263 • [U]
265 • [z|Z]
267 • [[r]shared|[r]slave|[r]private]
269 The CONTAINER-DIR must be an absolute path such as /src/docs. The HOST-
273 DIR must be an absolute path as well. Buildah bind-mounts the HOST-DIR
274 to the path you specify. For example, if you supply /foo as the host
275 path, Buildah copies the contents of /foo to the container filesystem
276 on the host and bind mounts that into the container.
277 You can specify multiple -v options to mount one or more mounts to a
280 container.
281 Write Protected Volume Mounts
284 You can add the :ro or :rw suffix to a volume to mount it read-only or
287 read-write mode, respectively. By default, the volumes are mounted
288 read-write. See examples.
289 Chowning Volume Mounts
292 By default, Buildah does not change the owner and group of source vol‐
295 ume directories mounted into containers. If a container is created in a
296 new user namespace, the UID and GID in the container may correspond to
297 another UID and GID on the host.
298 The :U suffix tells Buildah to use the correct host UID and GID based
301 on the UID and GID within the container, to change the owner and group
302 of the source volume.
303 Labeling Volume Mounts
306 Labeling systems like SELinux require that proper labels are placed on
309 volume content mounted into a container. Without a label, the security
310 system might prevent the processes running inside the container from
311 using the content. By default, Buildah does not change the labels set
312 by the OS.
313 To change a label in the container context, you can add either of two
316 suffixes :z or :Z to the volume mount. These suffixes tell Buildah to
317 relabel file objects on the shared volumes. The z option tells Buildah
318 that two containers share the volume content. As a result, Buildah la‐
319 bels the content with a shared content label. Shared volume labels al‐
320 low all containers to read/write content. The Z option tells Buildah
321 to label the content with a private unshared label. Only the current
322 container can use a private volume.
323 By default bind mounted volumes are private. That means any mounts done
326 inside container will not be visible on the host and vice versa. This
327 behavior can be changed by specifying a volume mount propagation prop‐
328 erty.
329 When the mount propagation policy is set to shared, any mounts com‐
332 pleted inside the container on that volume will be visible to both the
333 host and container. When the mount propagation policy is set to slave,
334 one way mount propagation is enabled and any mounts completed on the
335 host for that volume will be visible only inside of the container. To
336 control the mount propagation property of the volume use the
337 :[r]shared, :[r]slave or :[r]private propagation flag. The propagation
338 property can be specified only for bind mounted volumes and not for in‐
339 ternal volumes or named volumes. For mount propagation to work on the
340 source mount point (the mount point where source dir is mounted on) it
341 has to have the right propagation properties. For shared volumes, the
342 source mount point has to be shared. And for slave volumes, the source
343 mount has to be either shared or slave. [1] ⟨#Footnote1⟩
344 Use df <source-dir> to determine the source mount and then use findmnt
347 -o TARGET,PROPAGATION <source-mount-dir> to determine propagation prop‐
348 erties of source mount, if findmnt utility is not available, the source
349 mount point can be determined by looking at the mount entry in
350 /proc/self/mountinfo. Look at optional fields and see if any propaga‐
351 tion properties are specified. shared:X means the mount is shared,
352 master:X means the mount is slave and if nothing is there that means
353 the mount is private. [1] ⟨#Footnote1⟩
354 To change propagation properties of a mount point use the mount com‐
357 mand. For example, to bind mount the source directory /foo do mount
358 --bind /foo /foo and mount --make-private --make-shared /foo. This will
359 convert /foo into a shared mount point. The propagation properties of
360 the source mount can be changed directly. For instance if / is the
361 source mount for /foo, then use mount --make-shared / to convert / into
362 a shared mount.
363 --workingdir directory
366 Temporarily set the working directory for the running process. Unlike
369 buildah config --workingdir, the workingdir will not persist to later
370 calls to buildah run or the built image.
371 NOTE: End parsing of options with the -- option, so that other options
374 can be passed to the command inside of the container.
375
378 buildah run containerID -- ps -auxw
379 buildah run --hostname myhost containerID -- ps -auxw
382 buildah run containerID -- sh -c 'echo $PATH'
385 buildah run --runtime-flag log-format=json containerID /bin/bash
388 buildah run --runtime-flag debug containerID /bin/bash
391 buildah run --tty containerID /bin/bash
394 buildah run --tty=false containerID ls /
397 buildah run --volume /path/on/host:/path/in/container:ro,z containerID
400 sh
401 buildah run -v /path/on/host:/path/in/container:z,U containerID sh
404 buildah run --mount type=bind,src=/tmp/on:host,dst=/in:container,ro
407 containerID sh
408
411 buildah(1), buildah-from(1), buildah-config(1), namespaces(7),
412 pid_namespaces(7), crun(1), runc(8)
413
416 1: The Buildah project is committed to inclusivity, a core value of
417 open source. The master and slave mount propagation terminology used
418 here is problematic and divisive, and should be changed. However, these
419 terms are currently used within the Linux kernel and must be used as-is
420 at this time. When the kernel maintainers rectify this usage, Buildah
421 will follow suit immediately.
422buildah March 2017 buildah-run(1)