1buildah-run(1)              General Commands Manual             buildah-run(1)
2
3
4

NAME

6       buildah-run - Run a command inside of the container.
7
8

SYNOPSIS

10       buildah run [options] [--] container command
11
12

DESCRIPTION

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

OPTIONS

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
201none: no networking;
202
203host: 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
207ns:path: path to a network namespace to join;
208
209private: 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

EXAMPLE

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

SEE ALSO

457       buildah(1),    buildah-from(1),    buildah-config(1),    namespaces(7),
458       pid_namespaces(7), crun(1), runc(8)
459
460

FOOTNOTES

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)
Impressum