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 "container"  to  indi‐
89       cate 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.
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       --net how --network how
149
150
151       Sets  the  configuration  for  the network namespace for the container.
152       The configured value can be "" (the empty  string)  or  "container"  to
153       indicate  that  a new network namespace should be created, or it can be
154       "host" to indicate that the network namespace in which  buildah  itself
155       is  being  run  should  be  reused,  or it can be the path to a network
156       namespace which is already in use by another process.
157
158
159       --pid how
160
161
162       Sets the configuration for the PID namespace for  the  container.   The
163       configured  value  can be "" (the empty string) or "container" to indi‐
164       cate that a new PID namespace should be created, or it can be "host" to
165       indicate  that  the  PID namespace in which buildah itself is being run
166       should be reused, or it can be the path to a  PID  namespace  which  is
167       already in use by another process.
168
169
170       --runtime path
171
172
173       The  path  to  an alternate OCI-compatible runtime. Default is runc, or
174       crun when machine is configured to use cgroups V2.
175
176
177       Note: You can also override the default runtime by  setting  the  BUIL‐
178       DAH_RUNTIME environment variable.  export BUILDAH_RUNTIME=/usr/bin/crun
179
180
181       --runtime-flag flag
182
183
184       Adds  global  flags  for  the  container runtime. To list the supported
185       flags, please consult the manpages of the selected  container  runtime.
186       Note:  Do  not  pass  the leading -- to the flag. To pass the runc flag
187       --log-format json to buildah run, the  option  given  would  be  --run‐
188       time-flag log-format=json.
189
190
191       --no-pivot
192
193
194       Do  not  use  pivot  root to jail process inside rootfs. This should be
195       used whenever the rootfs is on top of a ramdisk.
196
197
198       Note: You can make  this  option  the  default  by  setting  the  BUIL‐
199       DAH_NOPIVOT environment variable.  export BUILDAH_NOPIVOT=true
200
201
202       -t, --tty, --terminal
203
204
205       By default a pseudo-TTY is allocated only when buildah's standard input
206       is attached to a pseudo-TTY.  Setting the --tty  option  to  true  will
207       cause  a pseudo-TTY to be allocated inside the container connecting the
208       user's "terminal" with the stdin and stdout stream  of  the  container.
209       Setting  the  --tty  option  to  false will prevent the pseudo-TTY from
210       being allocated.
211
212
213       --user user[:group]
214
215
216       Set the user to be used for running the command in the container.   The
217       user  can  be specified as a user name or UID, optionally followed by a
218       group name or GID, separated by a colon (':').  If names are used,  the
219       container should include entries for those names in its /etc/passwd and
220       /etc/group files.
221
222
223       --uts how
224
225
226       Sets the configuration for the UTS namespace for  the  container.   The
227       configured  value  can be "" (the empty string) or "container" to indi‐
228       cate that a new UTS namespace should be created, or it can be "host" to
229       indicate  that  the  UTS namespace in which buildah itself is being run
230       should be reused, or it can be the path to a  UTS  namespace  which  is
231       already in use by another process.
232
233
234       --volume, -v source:destination:options
235
236
237       Create a bind mount. If you specify, -v /HOST-DIR:/CONTAINER-DIR, Buil‐
238       dah bind mounts /HOST-DIR in the host to /CONTAINER-DIR in the  Buildah
239       container. The OPTIONS are a comma delimited list and can be:
240
241
242              · [rw|ro]
243
244              · [z|Z]
245
246              · [[r]shared|[r]slave|[r]private]
247
248
249
250       The  CONTAINER-DIR  must  be  an  absolute  path such as /src/docs. The
251       HOST-DIR must be an absolute path  as  well.  Buildah  bind-mounts  the
252       HOST-DIR  to  the  path you specify. For example, if you supply /foo as
253       the host path, Buildah copies the contents of  /foo  to  the  container
254       filesystem on the host and bind mounts that into the container.
255
256
257       You  can  specify multiple  -v options to mount one or more mounts to a
258       container.
259
260
261       You can add the :ro or :rw suffix to a volume to mount it read-only  or
262       read-write  mode,  respectively.  By  default,  the volumes are mounted
263       read-write.  See examples.
264
265
266       Labeling systems like SELinux require that proper labels are placed  on
267       volume  content mounted into a container. Without a label, the security
268       system might prevent the processes running inside  the  container  from
269       using  the  content. By default, Buildah does not change the labels set
270       by the OS.
271
272
273       To change a label in the container context, you can add either  of  two
274       suffixes  :z  or :Z to the volume mount. These suffixes tell Buildah to
275       relabel file objects on the shared volumes. The z option tells  Buildah
276       that  two  containers  share  the  volume content. As a result, Buildah
277       labels the content with a shared content label.  Shared  volume  labels
278       allow all containers to read/write content.  The Z option tells Buildah
279       to label the content with a private unshared label.  Only  the  current
280       container can use a private volume.
281
282
283       By default bind mounted volumes are private. That means any mounts done
284       inside container will not be visible on the host and vice  versa.  This
285       behavior  can be changed by specifying a volume mount propagation prop‐
286       erty.
287
288
289       When the mount propagation policy is set to  shared,  any  mounts  com‐
290       pleted  inside the container on that volume will be visible to both the
291       host and container. When the mount propagation policy is set to  slave,
292       one  way  mount  propagation is enabled and any mounts completed on the
293       host for that volume will be visible only inside of the container.   To
294       control   the   mount  propagation  property  of  the  volume  use  the
295       :[r]shared, :[r]slave or :[r]private propagation flag. The  propagation
296       property  can  be  specified  only for bind mounted volumes and not for
297       internal volumes or named volumes. For mount propagation to work on the
298       source  mount point (the mount point where source dir is mounted on) it
299       has to have the right propagation properties. For shared  volumes,  the
300       source  mount point has to be shared. And for slave volumes, the source
301       mount has to be either shared or slave.
302
303
304       Use df <source-dir> to determine the source mount and then use  findmnt
305       -o TARGET,PROPAGATION <source-mount-dir> to determine propagation prop‐
306       erties of source mount, if findmnt utility is not available, the source
307       mount  point  can  be  determined  by  looking  at  the  mount entry in
308       /proc/self/mountinfo. Look at optional fields and see if any propagaion
309       properties are specified.  shared:X means the mount is shared, master:X
310       means the mount is slave and if nothing is there that means  the  mount
311       is private.
312
313
314       To  change  propagation  properties of a mount point use the mount com‐
315       mand. For example, to bind mount the source  directory  /foo  do  mount
316       --bind /foo /foo and mount --make-private --make-shared /foo. This will
317       convert /foo into a shared mount point.  The propagation properties  of
318       the  source  mount  can  be  changed directly. For instance if / is the
319       source mount for /foo, then use mount --make-shared / to convert / into
320       a shared mount.
321
322
323       NOTE:  End parsing of options with the -- option, so that other options
324       can be passed to the command inside of the container.
325
326

EXAMPLE

328       buildah run containerID -- ps -auxw
329
330
331       buildah run --hostname myhost containerID -- ps -auxw
332
333
334       buildah run containerID -- sh -c 'echo $PATH'
335
336
337       buildah run --runtime-flag log-format=json containerID /bin/bash
338
339
340       buildah run --runtime-flag debug containerID /bin/bash
341
342
343       buildah run --tty containerID /bin/bash
344
345
346       buildah run --tty=false containerID ls /
347
348
349       buildah run --volume /path/on/host:/path/in/container:ro,z  containerID
350       sh
351
352
353       buildah   run  --mount  type=bind,src=/tmp/on:host,dst=/in:container,ro
354       containerID sh
355
356

SEE ALSO

358       buildah(1),    buildah-from(1),    buildah-config(1),    namespaces(7),
359       pid_namespaces(7), crun(1), runc(8)
360
361
362
363buildah                           March 2017                    buildah-run(1)
Impressum