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
26       invoked.  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
58       options, it will be dropped, regardless  of  the  order  in  which  the
59       options were given.
60
61
62       --cni-config-dir=directory
63
64
65       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
70
71       --cni-plugin-path=directory[:directory[:directory[...]]]
72
73
74       List of directories in which the CNI plugins which  will  be  used  for
75       configuring network namespaces can be found.
76
77
78       --hostname
79
80
81       Set the hostname inside of the running container.
82
83
84       --ipc how
85
86
87       Sets  the  configuration for the IPC namespaces for the container.  The
88       configured value can be "" (the empty string) or "private" to  indicate
89       that  a  new  IPC  namespace  should be created, or it can be "host" to
90       indicate that the IPC namespace in which buildah itself  is  being  run
91       should  be  reused,  or it can be the path to an IPC namespace which is
92       already in use by another process.
93
94
95       --isolation type
96
97
98       Controls what type of isolation is used for running the process.   Rec‐
99       ognized  types include oci (OCI-compatible runtime, the default), root‐
100       less (OCI-compatible runtime invoked using  a  modified  configuration,
101       with  --no-new-keyring added to its create invocation, with network and
102       UTS namespaces disabled, and IPC, PID, and user namespaces enabled; the
103       default  for  unprivileged users), and chroot (an internal wrapper that
104       leans more toward chroot(1) than container technology).
105
106
107       Note: You can also override the default isolation type by  setting  the
108       BUILDAH_ISOLATION environment variable.  export BUILDAH_ISOLATION=oci
109
110
111       --mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]
112
113
114       Attach a filesystem mount to the container
115
116
117       Current supported mount TYPES are bind, and tmpfs. [1] ⟨#Footnote1⟩
118
119
120                 e.g.
121
122                 type=bind,source=/path/on/host,destination=/path/in/container
123
124                 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
125
126                 Common Options:
127
128                        · src, source: mount source spec for bind and volume. Mandatory for bind.
129
130                        · dst, destination, target: mount destination spec.
131
132                        · ro, read-only: true or false (default).
133
134                 Options specific to bind:
135
136                        · bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2).
137
138                        . bind-nonrecursive: do not setup a recursive bind mount.  By default it is recursive.
139
140                 Options specific to tmpfs:
141
142                        · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
143
144                        · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
145
146
147
148       --network, --net=mode
149
150
151       Sets the configuration for the network namespace for the container.
152
153
154              · none: no networking;
155
156              · host:  use  the  host network stack. Note: the host mode gives
157                the container full access to local  system  services  such  as
158                D-bus and is therefore considered insecure;
159
160              · ns:path: path to a network namespace to join;
161
162              · private: create a new namespace for the container (default)
163
164
165
166       --pid how
167
168
169       Sets  the  configuration  for the PID namespace for the container.  The
170       configured value can be "" (the empty string) or "private" to  indicate
171       that  a  new  PID  namespace  should be created, or it can be "host" to
172       indicate that the PID namespace in which buildah itself  is  being  run
173       should  be  reused,  or  it can be the path to a PID namespace which is
174       already in use by another process.
175
176
177       --runtime path
178
179
180       The path to an alternate OCI-compatible runtime. Default  is  runc,  or
181       crun when machine is configured to use cgroups V2.
182
183
184       Note:  You  can  also override the default runtime by setting the BUIL‐
185       DAH_RUNTIME environment variable.  export BUILDAH_RUNTIME=/usr/bin/crun
186
187
188       --runtime-flag flag
189
190
191       Adds global flags for the container  runtime.  To  list  the  supported
192       flags,  please  consult the manpages of the selected container runtime.
193       Note: Do not pass the leading -- to the flag. To  pass  the  runc  flag
194       --log-format  json  to  buildah  run,  the option given would be --run‐
195       time-flag log-format=json.
196
197
198       --no-pivot
199
200
201       Do not use pivot root to jail process inside  rootfs.  This  should  be
202       used whenever the rootfs is on top of a ramdisk.
203
204
205       Note:  You  can  make  this  option  the  default  by setting the BUIL‐
206       DAH_NOPIVOT environment variable.  export BUILDAH_NOPIVOT=true
207
208
209       -t, --tty, --terminal
210
211
212       By default a pseudo-TTY is allocated only when buildah's standard input
213       is  attached  to  a  pseudo-TTY.  Setting the --tty option to true will
214       cause a pseudo-TTY to be allocated inside the container connecting  the
215       user's  "terminal"  with  the stdin and stdout stream of the container.
216       Setting the --tty option to false  will  prevent  the  pseudo-TTY  from
217       being allocated.
218
219
220       --user user[:group]
221
222
223       Set  the user to be used for running the command in the container.  The
224       user can be specified as a user name or UID, optionally followed  by  a
225       group  name or GID, separated by a colon (':').  If names are used, the
226       container should include entries for those names in its /etc/passwd and
227       /etc/group files.
228
229
230       --uts how
231
232
233       Sets  the  configuration  for the UTS namespace for the container.  The
234       configured value can be "" (the empty string) or "private" to  indicate
235       that  a  new  UTS  namespace  should be created, or it can be "host" to
236       indicate that the UTS namespace in which buildah itself  is  being  run
237       should  be  reused,  or  it can be the path to a UTS namespace which is
238       already in use by another process.
239
240
241       --volume, -v source:destination:options
242
243
244       Create a bind mount. If you specify, -v /HOST-DIR:/CONTAINER-DIR, Buil‐
245       dah  bind mounts /HOST-DIR in the host to /CONTAINER-DIR in the Buildah
246       container. The OPTIONS are a comma  delimited  list  and  can  be:  [1]
247       ⟨#Footnote1⟩
248
249
250              · [rw|ro]
251
252              · [U]
253
254              · [z|Z]
255
256              · [[r]shared|[r]slave|[r]private]
257
258
259
260       The  CONTAINER-DIR  must  be  an  absolute  path such as /src/docs. The
261       HOST-DIR must be an absolute path  as  well.  Buildah  bind-mounts  the
262       HOST-DIR  to  the  path you specify. For example, if you supply /foo as
263       the host path, Buildah copies the contents of  /foo  to  the  container
264       filesystem on the host and bind mounts that into the container.
265
266
267       You  can  specify multiple  -v options to mount one or more mounts to a
268       container.
269
270
271       Write Protected Volume Mounts
272
273
274       You can add the :ro or :rw suffix to a volume to mount it read-only  or
275       read-write  mode,  respectively.  By  default,  the volumes are mounted
276       read-write.  See examples.
277
278
279       Chowning Volume Mounts
280
281
282       By default, Buildah does not change the owner and group of source  vol‐
283       ume directories mounted into containers. If a container is created in a
284       new user namespace, the UID and GID in the container may correspond  to
285       another UID and GID on the host.
286
287
288       The  :U  suffix tells Buildah to use the correct host UID and GID based
289       on the UID and GID within the container, to change the owner and  group
290       of the source volume.
291
292
293       Labeling Volume Mounts
294
295
296       Labeling  systems like SELinux require that proper labels are placed on
297       volume content mounted into a container. Without a label, the  security
298       system  might  prevent  the processes running inside the container from
299       using the content. By default, Buildah does not change the  labels  set
300       by the OS.
301
302
303       To  change  a label in the container context, you can add either of two
304       suffixes :z or :Z to the volume mount. These suffixes tell  Buildah  to
305       relabel  file objects on the shared volumes. The z option tells Buildah
306       that two containers share the volume  content.  As  a  result,  Buildah
307       labels  the  content  with a shared content label. Shared volume labels
308       allow all containers to read/write content.  The Z option tells Buildah
309       to  label  the content with a private unshared label.  Only the current
310       container can use a private volume.
311
312
313       By default bind mounted volumes are private. That means any mounts done
314       inside  container  will not be visible on the host and vice versa. This
315       behavior can be changed by specifying a volume mount propagation  prop‐
316       erty.
317
318
319       When  the  mount  propagation  policy is set to shared, any mounts com‐
320       pleted inside the container on that volume will be visible to both  the
321       host  and container. When the mount propagation policy is set to slave,
322       one way mount propagation is enabled and any mounts  completed  on  the
323       host  for that volume will be visible only inside of the container.  To
324       control  the  mount  propagation  property  of  the  volume   use   the
325       :[r]shared,  :[r]slave or :[r]private propagation flag. The propagation
326       property can be specified only for bind mounted  volumes  and  not  for
327       internal volumes or named volumes. For mount propagation to work on the
328       source mount point (the mount point where source dir is mounted on)  it
329       has  to  have the right propagation properties. For shared volumes, the
330       source mount point has to be shared. And for slave volumes, the  source
331       mount has to be either shared or slave. [1] ⟨#Footnote1⟩
332
333
334       Use  df <source-dir> to determine the source mount and then use findmnt
335       -o TARGET,PROPAGATION <source-mount-dir> to determine propagation prop‐
336       erties of source mount, if findmnt utility is not available, the source
337       mount point can  be  determined  by  looking  at  the  mount  entry  in
338       /proc/self/mountinfo.  Look  at optional fields and see if any propaga‐
339       tion properties are specified.  shared:X means  the  mount  is  shared,
340       master:X  means  the  mount is slave and if nothing is there that means
341       the mount is private. [1] ⟨#Footnote1⟩
342
343
344       To change propagation properties of a mount point use  the  mount  com‐
345       mand.  For  example,  to  bind mount the source directory /foo do mount
346       --bind /foo /foo and mount --make-private --make-shared /foo. This will
347       convert  /foo into a shared mount point.  The propagation properties of
348       the source mount can be changed directly. For  instance  if  /  is  the
349       source mount for /foo, then use mount --make-shared / to convert / into
350       a shared mount.
351
352
353       NOTE: End parsing of options with the -- option, so that other  options
354       can be passed to the command inside of the container.
355
356

EXAMPLE

358       buildah run containerID -- ps -auxw
359
360
361       buildah run --hostname myhost containerID -- ps -auxw
362
363
364       buildah run containerID -- sh -c 'echo $PATH'
365
366
367       buildah run --runtime-flag log-format=json containerID /bin/bash
368
369
370       buildah run --runtime-flag debug containerID /bin/bash
371
372
373       buildah run --tty containerID /bin/bash
374
375
376       buildah run --tty=false containerID ls /
377
378
379       buildah  run --volume /path/on/host:/path/in/container:ro,z containerID
380       sh
381
382
383       buildah run -v /path/on/host:/path/in/container:z,U containerID sh
384
385
386       buildah  run  --mount   type=bind,src=/tmp/on:host,dst=/in:container,ro
387       containerID sh
388
389

SEE ALSO

391       buildah(1),    buildah-from(1),    buildah-config(1),    namespaces(7),
392       pid_namespaces(7), crun(1), runc(8)
393
394

FOOTNOTES

396       1: The Buildah project is committed to inclusivity,  a  core  value  of
397       open  source.  The  master and slave mount propagation terminology used
398       here is problematic and divisive, and should be changed. However, these
399       terms are currently used within the Linux kernel and must be used as-is
400       at this time. When the kernel maintainers rectify this  usage,  Buildah
401       will follow suit immediately.
402
403
404
405buildah                           March 2017                    buildah-run(1)
Impressum