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

NAME

6       buildah-build - Build an image using instructions from Containerfiles
7
8

SYNOPSIS

10       buildah build [options] [context]
11
12
13       buildah bud [options] [context]
14
15
16       buildah build-using-dockerfile [options] [context]
17
18
19       build has aliases bud and build-using-dockerfile.
20
21

DESCRIPTION

23       Builds  an  image using instructions from one or more Containerfiles or
24       Dockerfiles and a specified build context directory.   A  Containerfile
25       uses  the same syntax as a Dockerfile internally.  For this document, a
26       file referred to as a Containerfile can be a file  named  either  'Con‐
27       tainerfile' or 'Dockerfile'.
28
29
30       The  build  context directory can be specified as the http(s) URL of an
31       archive, git repository or Containerfile.
32
33
34       If no context directory is specified, then Buildah will assume the cur‐
35       rent  working  directory  as build context, which should contain a Con‐
36       tainerfile.
37
38
39       Containerfiles ending with a ".in"  suffix  will  be  preprocessed  via
40       cpp(1).   This  can  be useful to decompose Containerfiles into several
41       reusable parts that can be used via CPP's #include directive.   Notice,
42       a  Containerfile.in file can still be used by other tools when manually
43       preprocessing them via cpp -E. Any comments ( Lines beginning with #  )
44       in  included Containerfile(s) that are not preprocess commands, will be
45       printed as warnings during builds.
46
47
48       When the URL is an archive, the contents of the URL is downloaded to  a
49       temporary location and extracted before execution.
50
51
52       When  the URL is a Containerfile, the file is downloaded to a temporary
53       location.
54
55
56       When a Git repository is set as the URL, the repository is  cloned  lo‐
57       cally and then set as the context.
58
59

OPTIONS

61       --add-host=[]
62
63
64       Add a custom host-to-IP mapping (host:ip)
65
66
67       Add a line to /etc/hosts. The format is hostname:ip. The --add-host op‐
68       tion can be set multiple times.
69
70
71       --annotation annotation
72
73
74       Add an image annotation (e.g. annotation=value) to the image  metadata.
75       Can be used multiple times.
76
77
78       Note: this information is not present in Docker image formats, so it is
79       discarded when writing images in Docker formats.
80
81
82       --arch="ARCH"
83
84
85       Set the ARCH of the image to be built, and that of the base image to be
86       pulled,  if  the build uses one, to the provided value instead of using
87       the architecture of  the  host.  (Examples:  arm,  arm64,  386,  amd64,
88       ppc64le, s390x)
89
90
91       --authfile path
92
93
94       Path  of  the  authentication file. Default is ${XDG_\RUNTIME_DIR}/con‐
95       tainers/auth.json. If  XDG_RUNTIME_DIR  is  not  set,  the  default  is
96       /run/containers/$UID/auth.json.  This file is created using using buil‐
97       dah login.
98
99
100       If the authorization  state  is  not  found  there,  $HOME/.docker/con‐
101       fig.json is checked, which is set using docker login.
102
103
104       Note: You can also override the default path of the authentication file
105       by setting the REGISTRY_AUTH_FILE  environment  variable.  export  REG‐
106       ISTRY_AUTH_FILE=path
107
108
109       --build-arg arg=value
110
111
112       Specifies a build argument and its value, which will be interpolated in
113       instructions read from the Containerfiles in the same way that environ‐
114       ment variables are, but which will not be added to environment variable
115       list in the resulting image's configuration.
116
117
118       Please refer to the BUILD TIME VARIABLES  ⟨#build-time-variables⟩  sec‐
119       tion  for  the list of variables that can be overridden within the Con‐
120       tainerfile at run time.
121
122
123       --cache-from
124
125
126       Images to utilise as potential cache sources.  Buildah  does  not  cur‐
127       rently support --cache-from so this is a NOOP.
128
129
130       --cap-add=CAP_xxx
131
132
133       When  executing  RUN instructions, run the command specified in the in‐
134       struction with the specified capability added to  its  capability  set.
135       Certain capabilities are granted by default; this option can be used to
136       add more.
137
138
139       --cap-drop=CAP_xxx
140
141
142       When executing RUN instructions, run the command specified in  the  in‐
143       struction  with  the  specified  capability removed from its capability
144       set.  The  CAP_AUDIT_WRITE,  CAP_CHOWN,  CAP_DAC_OVERRIDE,  CAP_FOWNER,
145       CAP_FSETID,  CAP_KILL,  CAP_MKNOD,  CAP_NET_BIND_SERVICE,  CAP_SETFCAP,
146       CAP_SETGID, CAP_SETPCAP, CAP_SETUID,  and  CAP_SYS_CHROOT  capabilities
147       are granted by default; this option can be used to remove them.
148
149
150       If  a  capability is specified to both the --cap-add and --cap-drop op‐
151       tions, it will be dropped, regardless of the order in which the options
152       were given.
153
154
155       --cert-dir path
156
157
158       Use  certificates at path (*.crt, *.cert, *.key) to connect to the reg‐
159       istry.  The default certificates directory is /etc/containers/certs.d.
160
161
162       --cgroup-parent=""
163
164
165       Path to cgroups under which the cgroup for the container will  be  cre‐
166       ated.  If  the path is not absolute, the path is considered to be rela‐
167       tive to the cgroups path of the init process. Cgroups will  be  created
168       if they do not already exist.
169
170
171       --compress
172
173
174       This option is added to be aligned with other containers CLIs.  Buildah
175       doesn't send a copy of the context directory to a daemon  or  a  remote
176       server.   Thus, compressing the data before sending it is irrelevant to
177       Buildah.
178
179
180       --cni-config-dir=directory
181
182
183       Location of CNI configuration files which will  dictate  which  plugins
184       will be used to configure network interfaces and routing for containers
185       created for handling RUN instructions, if those containers will be  run
186       in their own network namespaces, and networking is not disabled.
187
188
189       --cni-plugin-path=directory[:directory[:directory[...]]]
190
191
192       List  of  directories  in  which the CNI plugins which will be used for
193       configuring network namespaces can be found.
194
195
196       --cpu-period=0
197
198
199       Set the CPU period for the Completely Fair Scheduler (CFS), which is  a
200       duration in microseconds. Once the container's CPU quota is used up, it
201       will not be scheduled to run until the current period ends. Defaults to
202       100000 microseconds.
203
204
205       On  some  systems,  changing the CPU limits may not be allowed for non-
206       root users. For more  details,  see  https://github.com/containers/pod
207       man/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-
208       fails-with-a-permissions-error
209
210
211       --cpu-quota=0
212
213
214       Limit the CPU CFS (Completely Fair Scheduler) quota
215
216
217       Limit the container's CPU usage. By default, containers  run  with  the
218       full  CPU  resource.  This  flag  tell  the kernel to restrict the con‐
219       tainer's CPU usage to the quota you specify.
220
221
222       On some systems, changing the CPU limits may not be  allowed  for  non-
223       root  users.  For  more details, see https://github.com/containers/pod
224       man/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-
225       fails-with-a-permissions-error
226
227
228       --cpu-shares, -c=0
229
230
231       CPU shares (relative weight)
232
233
234       By  default, all containers get the same proportion of CPU cycles. This
235       proportion can be  modified  by  changing  the  container's  CPU  share
236       weighting relative to the weighting of all other running containers.
237
238
239       To modify the proportion from the default of 1024, use the --cpu-shares
240       flag to set the weighting to 2 or higher.
241
242
243       The proportion will only apply when CPU-intensive  processes  are  run‐
244       ning.   When  tasks in one container are idle, other containers can use
245       the left-over CPU time. The actual amount of CPU time will vary depend‐
246       ing on the number of containers running on the system.
247
248
249       For example, consider three containers, one has a cpu-share of 1024 and
250       two others have a cpu-share setting of 512. When processes in all three
251       containers  attempt  to  use 100% of CPU, the first container would re‐
252       ceive 50% of the total CPU time. If you add a fourth container  with  a
253       cpu-share  of  1024,  the first container only gets 33% of the CPU. The
254       remaining containers receive 16.5%, 16.5% and 33% of the CPU.
255
256
257       On a multi-core system, the shares of CPU time are distributed over all
258       CPU  cores.  Even  if  a  container is limited to less than 100% of CPU
259       time, it can use 100% of each individual CPU core.
260
261
262       For example, consider a system with more than three cores. If you start
263       one  container  {C0}  with -c=512 running one process, and another con‐
264       tainer {C1} with -c=1024 running two processes, this can result in  the
265       following division of CPU shares:
266
267
268              PID    container    CPU  CPU share
269              100    {C0}         0    100% of CPU0
270              101    {C1}         1    100% of CPU1
271              102    {C1}         2    100% of CPU2
272
273
274
275       --cpuset-cpus=""
276
277
278       CPUs in which to allow execution (0-3, 0,1)
279
280
281       --cpuset-mems=""
282
283
284       Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effec‐
285       tive on NUMA systems.
286
287
288       If you have four memory nodes  on  your  system  (0-3),  use  --cpuset-
289       mems=0,1 then processes in your container will only use memory from the
290       first two memory nodes.
291
292
293       --creds creds
294
295
296       The [username[:password]] to use to authenticate with the  registry  if
297       required.   If  one  or  both  values  are not supplied, a command line
298       prompt will appear and the value can be entered.  The password  is  en‐
299       tered without echo.
300
301
302       --decryption-key key[:passphrase]
303
304
305       The  [key[:passphrase]]  to  be  used for decryption of images. Key can
306       point to keys and/or certificates. Decryption will be  tried  with  all
307       keys.  If  the  key  is protected by a passphrase, it is required to be
308       passed in the argument and omitted otherwise.
309
310
311       --device=device
312
313
314       Add a host device to the container. Optional permissions parameter  can
315       be used to specify device permissions, it is combination of r for read,
316       w for write, and m for mknod(2).
317
318
319       Example: --device=/dev/sdc:/dev/xvdc:rwm.
320
321
322       Note: if _hostdevice is a symbolic link then it will be resolved first.
323       The  container  will only store the major and minor numbers of the host
324       device.
325
326
327       Note: if the user only has access rights via a group, accessing the de‐
328       vice  from  inside  a rootless container will fail. The crun(1) runtime
329       offers  a  workaround  for  this  by  adding  the  option  --annotation
330       run.oci.keep_original_groups=1.
331
332
333       --disable-compression, -D
334
335
336       Don't  compress  filesystem layers when building the image unless it is
337       required by the location where the image is being written.  This is the
338       default setting, because image layers are compressed automatically when
339       they are pushed to registries, and images being written to local  stor‐
340       age would only need to be decompressed again to be stored.  Compression
341       can be forced in all cases by specifying --disable-compression=false.
342
343
344       --disable-content-trust
345
346
347       This is a Docker specific option to disable  image  verification  to  a
348       Docker  registry  and is not supported by Buildah.  This flag is a NOOP
349       and provided solely for scripting compatibility.
350
351
352       --dns=[]
353
354
355       Set custom DNS servers
356
357
358       This option can be used to override the DNS configuration passed to the
359       container.  Typically this is necessary when the host DNS configuration
360       is invalid for the container (e.g., 127.0.0.1). When this is  the  case
361       the --dns flag is necessary for every run.
362
363
364       The special value none can be specified to disable creation of /etc/re‐
365       solv.conf in the container by Buildah. The /etc/resolv.conf file in the
366       image will be used without changes.
367
368
369       --dns-option=[]
370
371
372       Set custom DNS options
373
374
375       --dns-search=[]
376
377
378       Set custom DNS search domains
379
380
381       --file, -f Containerfile
382
383
384       Specifies  a Containerfile which contains instructions for building the
385       image, either a local file or an http or https URL.  If more  than  one
386       Containerfile  is  specified,  FROM  instructions will only be accepted
387       from the first specified file.
388
389
390       If a local file is specified as the Containerfile and it does  not  ex‐
391       ist, the context directory will be prepended to the local file value.
392
393
394       If  you  specify  -f  -,  the  Containerfile contents will be read from
395       stdin.
396
397
398       --force-rm bool-value
399
400
401       Always remove intermediate containers after a build, even if the  build
402       fails (default false).
403
404
405       --format
406
407
408       Control  the  format  for  the built image's manifest and configuration
409       data.  Recognized formats include oci (OCI  image-spec  v1.0,  the  de‐
410       fault) and docker (version 2, using schema format 2 for the manifest).
411
412
413       Note:  You  can  also  override the default format by setting the BUIL‐
414       DAH_FORMAT environment variable.  export BUILDAH_FORMAT=docker
415
416
417       --from
418
419
420       Overrides the first FROM  instruction  within  the  Containerfile.   If
421       there are multiple FROM instructions in a Containerfile, only the first
422       is changed.
423
424
425       -h, --help
426
427
428       Print usage statement
429
430
431       --http-proxy=true
432
433
434       By default proxy environment variables are passed into the container if
435       set  for  the  buildah  process.   This  can be disabled by setting the
436       --http-proxy option to false.  The environment variables passed in  in‐
437       clude  http_proxy, https_proxy, ftp_proxy, no_proxy, and also the upper
438       case versions of those.
439
440
441       --iidfile ImageIDfile
442
443
444       Write the built image's ID to the file.  When --platform  is  specified
445       more than once, attempting to use this option will trigger an error.
446
447
448       --ignorefile file
449
450
451       Path to an alternative .containerignore (.dockerignore) file.
452
453
454       --ipc how
455
456
457       Sets  the  configuration  for IPC namespaces when handling RUN instruc‐
458       tions.  The configured value can be ""  (the  empty  string)  or  "con‐
459       tainer"  to  indicate that a new IPC namespace should be created, or it
460       can be "host" to indicate that the IPC namespace in which  buildah  it‐
461       self  is  being  run  should be reused, or it can be the path to an IPC
462       namespace which is already in use by another process.
463
464
465       --isolation type
466
467
468       Controls what type of isolation is used for running processes  as  part
469       of RUN instructions.  Recognized types include oci (OCI-compatible run‐
470       time, the default), rootless (OCI-compatible runtime  invoked  using  a
471       modified configuration, with --no-new-keyring added to its create invo‐
472       cation, reusing the host's network and  UTS  namespaces,  and  creating
473       private  IPC, PID, mount, and user namespaces; the default for unprivi‐
474       leged users), and chroot (an internal wrapper that  leans  more  toward
475       chroot(1)  than container technology, reusing the host's control group,
476       network, IPC, and PID namespaces, and creating private  mount  and  UTS
477       namespaces, and creating user namespaces only when they're required for
478       ID mapping).
479
480
481       Note: You can also override the default isolation type by  setting  the
482       BUILDAH_ISOLATION environment variable.  export BUILDAH_ISOLATION=oci
483
484
485       --jobs N
486
487
488       Run  up  to  N concurrent stages in parallel.  If the number of jobs is
489       greater than 1, stdin will be read from /dev/null.  If 0 is  specified,
490       then there is no limit on the number of jobs that run in parallel.
491
492
493       --label label
494
495
496       Add  an  image  label  (e.g. label=value) to the image metadata. Can be
497       used multiple times.
498
499
500       Users can set a special LABEL io.containers.capabilities=CAP1,CAP2,CAP3
501       in  a  Containerfile  that specified the list of Linux capabilities re‐
502       quired for the container to run properly. This  label  specified  in  a
503       container  image  tells container engines, like Podman, to run the con‐
504       tainer with just these capabilities. The container engine launches  the
505       container with just the specified capabilities, as long as this list of
506       capabilities is a subset of the default list.
507
508
509       If the specified capabilities are not in the default set, container en‐
510       gines should print an error message and will run the container with the
511       default capabilities.
512
513
514       --layers bool-value
515
516
517       Cache intermediate images during the build process (Default is false).
518
519
520       Note: You can also override the default value of layers by setting  the
521       BUILDAH_LAYERS environment variable. export BUILDAH_LAYERS=true
522
523
524       --logfile filename
525
526
527       Log output which would be sent to standard output and standard error to
528       the specified file instead of to standard output and standard error.
529
530
531       --manifest "listName"
532
533
534       Name of the manifest list to which the built image will be added.  Cre‐
535       ates the manifest list if it does not exist.  This option is useful for
536       building multi architecture images.
537
538
539       --memory, -m=""
540
541
542       Memory limit (format: [], where unit = b, k, m or g)
543
544
545       Allows you to constrain the memory available to  a  container.  If  the
546       host  supports  swap  memory,  then the -m memory setting can be larger
547       than physical RAM. If a limit of 0 is specified  (not  using  -m),  the
548       container's  memory  is not limited. The actual limit may be rounded up
549       to a multiple of the operating system's page size (the value  would  be
550       very large, that's millions of trillions).
551
552
553       --memory-swap="LIMIT"
554
555
556       A  limit  value  equal  to  memory plus swap. Must be used with the  -m
557       (--memory) flag. The swap LIMIT should always be larger than -m (--mem‐
558       ory) value.  By default, the swap LIMIT will be set to double the value
559       of --memory.
560
561
562       The format of LIMIT is <number>[<unit>].  Unit  can  be  b  (bytes),  k
563       (kilobytes),  m  (megabytes),  or g (gigabytes). If you don't specify a
564       unit, b is used. Set LIMIT to -1 to enable unlimited swap.
565
566
567       --network, --net=mode
568
569
570       Sets the configuration for network namespaces  when  handling  RUN  in‐
571       structions.
572
573
574       Valid mode values are:
575
576
577none: no networking;
578
579host:  use  the  host network stack. Note: the host mode gives
580                the container full access to local system services such as  D-
581                bus and is therefore considered insecure;
582
583ns:path: path to a network namespace to join;
584
585private: create a new namespace for the container (default)
586
587
588
589       --no-cache
590
591
592       Do  not  use existing cached images for the container build. Build from
593       the start with a new set of cached layers.
594
595
596       --os="OS"
597
598
599       Set the OS of the image to be built, and that of the base image  to  be
600       pulled,  if  the build uses one, instead of using the current operating
601       system of the host.
602
603
604       --pid how
605
606
607       Sets the configuration for PID namespaces when  handling  RUN  instruc‐
608       tions.   The configured value can be "" (the empty string) or "private"
609       to indicate that a new PID namespace should be created, or  it  can  be
610       "host"  to  indicate  that the PID namespace in which buildah itself is
611       being run should be reused, or it can be the path to  a  PID  namespace
612       which is already in use by another process.
613
614
615       --platform="OS/ARCH[/VARIANT]"
616
617
618       Set  the  OS/ARCH of the built image (and its base image, if your build
619       uses one) to the provided value instead of using the current  operating
620       system and architecture of the host (for example linux/arm). If --plat‐
621       form is set, then the values of the --arch, --os, and --variant options
622       will be overridden.
623
624
625       The  --platform flag can be specified more than once, or given a comma-
626       separated list of values as its argument.  When more than one  platform
627       is specified, the --manifest option should be used instead of the --tag
628       option.
629
630
631       OS/ARCH pairs are those used by the Go Programming Language.   In  sev‐
632       eral  cases  the ARCH value for a platform differs from one produced by
633       other tools such as the arch command.  Valid OS and  architecture  name
634       combinations   are   listed   as   values  for  $GOOS  and  $GOARCH  at
635       https://golang.org/doc/install/source#environment,  and  can  also   be
636       found by running go tool dist list.
637
638
639       While  buildah bud is happy to use base images and build images for any
640       platform that exists, RUN instructions will  not  be  able  to  succeed
641       without  the  help  of  emulation  provided by packages like qemu-user-
642       static.
643
644
645       --pull
646
647
648       When the flag is enabled, attempt to pull the  latest  image  from  the
649       registries listed in registries.conf if a local image does not exist or
650       the image is newer than the one in storage. Raise an error if the image
651       is not in any listed registry and is not present locally.
652
653
654       If the flag is disabled (with --pull=false), do not pull the image from
655       the registry, unless there is no local image. Raise an error if the im‐
656       age is not in any registry and is not present locally.
657
658
659       Defaults to true.
660
661
662       --pull-always
663
664
665       Pull the image from the first registry it is found in as listed in reg‐
666       istries.conf.  Raise an error if not found in the registries,  even  if
667       the image is present locally.
668
669
670       --pull-never
671
672
673       Do  not  pull  the image from the registry, use only the local version.
674       Raise an error if the image is not present locally.
675
676
677       --quiet, -q
678
679
680       Suppress output messages which indicate which instruction is being pro‐
681       cessed,  and  of progress when pulling images from a registry, and when
682       writing the output image.
683
684
685       --rm bool-value
686
687
688       Remove intermediate containers after a successful build (default true).
689
690
691       --runtime path
692
693
694       The path to an alternate OCI-compatible runtime, which will be used  to
695       run commands specified by the RUN instruction. Default is runc, or crun
696       when machine is configured to use cgroups V2.
697
698
699       Note: You can also override the default runtime by  setting  the  BUIL‐
700       DAH_RUNTIME environment variable.  export BUILDAH_RUNTIME=/usr/bin/crun
701
702
703       --runtime-flag flag
704
705
706       Adds  global  flags  for  the  container  rutime. To list the supported
707       flags, please consult the manpages of the selected container runtime.
708
709
710       Note: Do not pass the leading -- to the flag. To  pass  the  runc  flag
711       --log-format  json  to  buildah build, the option given would be --run‐
712       time-flag log-format=json.
713
714
715       --secret=id=id,src=path
716
717
718       Pass secret information to be used in the  Containerfile  for  building
719       images in a safe way that will not end up stored in the final image, or
720       be seen in other stages.  The secret will be mounted in  the  container
721       at the default location of /run/secrets/id.
722
723
724       To  later  use  the  secret,  use the --mount flag in a RUN instruction
725       within a Containerfile:
726
727
728       RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret
729
730
731       --security-opt=[]
732
733
734       Security Options
735
736
737       "apparmor=unconfined" : Turn off apparmor confinement for the container
738         "apparmor=your-profile" : Set the apparmor  confinement  profile  for
739       the container
740
741
742       "label=user:USER"   : Set the label user for the container
743         "label=role:ROLE"   : Set the label role for the container
744         "label=type:TYPE"   : Set the label type for the container
745         "label=level:LEVEL" : Set the label level for the container
746         "label=disable"     : Turn off label confinement for the container
747         "no-new-privileges" : Not supported
748
749
750       "seccomp=unconfined" : Turn off seccomp confinement for the container
751         "seccomp=profile.json  :   White listed syscalls seccomp Json file to
752       be used as a seccomp filter
753
754
755       --shm-size=""
756
757
758       Size of /dev/shm. The format is <number><unit>. number must be  greater
759       than  0.   Unit  is  optional  and  can  be  b  (bytes), k (kilobytes),
760       m(megabytes), or g (gigabytes).  If you omit the unit, the system  uses
761       bytes. If you omit the size entirely, the system uses 64m.
762
763
764       --sign-by fingerprint
765
766
767       Sign  the built image using the GPG key that matches the specified fin‐
768       gerprint.
769
770
771       --squash
772
773
774       Squash all of the image's new layers into a single new layer; any  pre‐
775       existing layers are not squashed.
776
777
778       --ssh=default|id[=socket>|[,]
779
780
781       SSH  agent  socket or keys to expose to the build.  The socket path can
782       be left empty to use the value of default=$SSH_AUTH_SOCK
783
784
785       To later use the ssh agent, use the --mount flag in a  RUN  instruction
786       within a Containerfile:
787
788
789       RUN --mount=type=secret,id=id mycmd
790
791
792       --stdin
793
794
795       Pass  stdin into the RUN containers. Sometime commands being RUN within
796       a Containerfile want to request information from the user. For  example
797       apt  asking  for a confirmation for install.  Use --stdin to be able to
798       interact from the terminal during the build.
799
800
801       --tag, -t imageName
802
803
804       Specifies the name which will be assigned to the resulting image if the
805       build  process completes successfully.  If imageName does not include a
806       registry name component, the registry name localhost will be  prepended
807       to the image name.
808
809
810       --target stageName
811
812
813       Set  the  target  build  stage to build.  When building a Containerfile
814       with multiple build stages, --target can be used to specify an interme‐
815       diate  build  stage by name as the final stage for the resulting image.
816       Commands after the target stage will be skipped.
817
818
819       --timestamp seconds
820
821
822       Set the create timestamp to seconds since epoch to allow for  determin‐
823       istic builds (defaults to current time).  By default, the created time‐
824       stamp is changed and written into the image manifest with every commit,
825       causing the image's sha256 hash to be different even if the sources are
826       exactly the same otherwise.  When --timestamp is set, the created time‐
827       stamp  is  always  set to the time specified and therefore not changed,
828       allowing the image's sha256 to remain the same. All files committed  to
829       the layers of the image will be created with the timestamp.
830
831
832       --tls-verify bool-value
833
834
835       Require  HTTPS  and  verification  of certificates when talking to con‐
836       tainer registries (defaults to true).  TLS verification cannot be  used
837       when talking to an insecure registry.
838
839
840       --ulimit type=soft-limit[:hard-limit]
841
842
843       Specifies  resource limits to apply to processes launched when process‐
844       ing RUN instructions.  This option can  be  specified  multiple  times.
845       Recognized resource types include:
846         "core": maximum core dump size (ulimit -c)
847         "cpu": maximum CPU time (ulimit -t)
848         "data": maximum size of a process's data segment (ulimit -d)
849         "fsize": maximum size of new files (ulimit -f)
850         "locks": maximum number of file locks (ulimit -x)
851         "memlock": maximum amount of locked memory (ulimit -l)
852         "msgqueue": maximum amount of data in message queues (ulimit -q)
853         "nice": niceness adjustment (nice -n, ulimit -e)
854         "nofile": maximum number of open files (ulimit -n)
855         "nofile": maximum number of open files (1048576); when run by root
856         "nproc": maximum number of processes (ulimit -u)
857         "nproc": maximum number of processes (1048576); when run by root
858         "rss": maximum size of a process's (ulimit -m)
859         "rtprio": maximum real-time scheduling priority (ulimit -r)
860         "rttime":  maximum  amount  of  real-time  execution between blocking
861       syscalls
862         "sigpending": maximum number of pending signals (ulimit -i)
863         "stack": maximum stack size (ulimit -s)
864
865
866       --userns how
867
868
869       Sets the configuration for user namespaces when handling  RUN  instruc‐
870       tions.   The configured value can be "" (the empty string) or "private"
871       to indicate that a new user namespace should  be  created,  it  can  be
872       "host"  to  indicate that the user namespace in which buildah itself is
873       being run should be reused, or it can be the path to an user  namespace
874       which is already in use by another process.
875
876
877       --userns-uid-map-user user
878
879
880       Specifies  that a UID mapping which should be used to set ownership, at
881       the filesystem level, on the working container's contents, can be found
882       in  entries  in  the /etc/subuid file which correspond to the specified
883       user.  Commands run when handling RUN instructions will default to  be‐
884       ing  run in their own user namespaces, configured using the UID and GID
885       maps.  If --userns-gid-map-group is  specified,  but  --userns-uid-map-
886       user  is  not  specified,  buildah will assume that the specified group
887       name is also a suitable user name to use as  the  default  setting  for
888       this option.
889
890
891       Users can specify the maps directly using --userns-uid-map described in
892       the buildah(1) man page.
893
894
895       NOTE: When this option is specified by a rootless user,  the  specified
896       mappings  are  relative to the rootless usernamespace in the container,
897       rather than being relative to the host as it would be when run rootful.
898
899
900       --userns-gid-map-group group
901
902
903       Specifies that a GID mapping which should be used to set ownership,  at
904       the filesystem level, on the working container's contents, can be found
905       in entries in the /etc/subgid file which correspond  to  the  specified
906       group.  Commands run when handling RUN instructions will default to be‐
907       ing run in their own user namespaces, configured using the UID and  GID
908       maps.   If  --userns-uid-map-user  is  specified, but --userns-gid-map-
909       group is not specified, buildah will assume  that  the  specified  user
910       name  is  also  a suitable group name to use as the default setting for
911       this option.
912
913
914       Users can specify the maps directly using --userns-gid-map described in
915       the buildah(1) man page.
916
917
918       NOTE:  When  this option is specified by a rootless user, the specified
919       mappings are relative to the rootless usernamespace in  the  container,
920       rather than being relative to the host as it would be when run rootful.
921
922
923       --uts how
924
925
926       Sets  the  configuration  for  UTS namespaces when the handling RUN in‐
927       structions.  The configured value can be "" (the empty string) or "con‐
928       tainer"  to  indicate that a new UTS namespace should be created, or it
929       can be "host" to indicate that the UTS namespace in which  buildah  it‐
930       self  is  being  run  should  be reused, or it can be the path to a UTS
931       namespace which is already in use by another process.
932
933
934       --variant=""
935
936
937       Set the architecture variant of the image to be pulled.
938
939
940       --volume, -v[=[HOST-DIR:CONTAINER-DIR[:OPTIONS]]]
941
942
943       Create a bind mount. If you specify, -v /HOST-DIR:/CONTAINER-DIR, Buil‐
944       dah
945          bind mounts /HOST-DIR in the host to /CONTAINER-DIR in the Buildah
946          container.  The  OPTIONS  are a comma delimited list and can be: [1]
947       ⟨#Footnote1⟩
948
949
950              • [rw|ro]
951
952              • [U]
953
954              • [z|Z|O]
955
956              • [[r]shared|[r]slave|[r]private]
957
958
959
960       The CONTAINER-DIR must be an absolute path such as /src/docs. The HOST-
961       DIR  must be an absolute path as well. Buildah bind-mounts the HOST-DIR
962       to the path you specify. For example, if you supply /foo  as  the  host
963       path,  Buildah  copies the contents of /foo to the container filesystem
964       on the host and bind mounts that into the container.
965
966
967       You can specify multiple  -v options to mount one or more mounts  to  a
968       container.
969
970
971       Write Protected Volume Mounts
972
973
974       You  can add the :ro or :rw suffix to a volume to mount it read-only or
975       read-write mode, respectively. By  default,  the  volumes  are  mounted
976       read-write.  See examples.
977
978
979       Chowning Volume Mounts
980
981
982       By  default, Buildah does not change the owner and group of source vol‐
983       ume directories mounted into containers. If a container is created in a
984       new  user namespace, the UID and GID in the container may correspond to
985       another UID and GID on the host.
986
987
988       The :U suffix tells Buildah to use the correct host UID and  GID  based
989       on  the UID and GID within the container, to change the owner and group
990       of the source volume.
991
992
993       Labeling Volume Mounts
994
995
996       Labeling systems like SELinux require that proper labels are placed  on
997       volume  content mounted into a container. Without a label, the security
998       system might prevent the processes running inside  the  container  from
999       using  the  content. By default, Buildah does not change the labels set
1000       by the OS.
1001
1002
1003       To change a label in the container context, you can add either  of  two
1004       suffixes  :z  or :Z to the volume mount. These suffixes tell Buildah to
1005       relabel file objects on the shared volumes. The z option tells  Buildah
1006       that  two containers share the volume content. As a result, Buildah la‐
1007       bels the content with a shared content label. Shared volume labels  al‐
1008       low  all  containers to read/write content.  The Z option tells Buildah
1009       to label the content with a private unshared label.  Only  the  current
1010       container can use a private volume.
1011
1012
1013       Overlay Volume Mounts
1014
1015
1016       The  :O  flag  tells  Buildah to mount the directory from the host as a
1017       temporary storage using the Overlay file system. The RUN  command  con‐
1018       tainers  are  allowed  to modify contents within the mountpoint and are
1019       stored in the container storage in a separate directory.  In Overlay FS
1020       terms the source directory will be the lower, and the container storage
1021       directory will be the upper. Modifications to the mount point  are  de‐
1022       stroyed  when  the  RUN  command finishes executing, similar to a tmpfs
1023       mount point.
1024
1025
1026       Any subsequent execution of RUN commands sees the original  source  di‐
1027       rectory  content,  any changes from previous RUN commands no longer ex‐
1028       ists.
1029
1030
1031       One use case of the overlay mount is sharing the package cache from the
1032       host into the container to allow speeding up builds.
1033
1034
1035       Note:
1036
1037
1038               - The `O` flag is not allowed to be specified with the `Z` or `z` flags. Content mounted into the container is labeled with the private label.
1039                 On SELinux systems, labels in the source directory needs to be readable by the container label. If not, SELinux container separation must be disabled for the container to work.
1040               - Modification of the directory volume mounted into the container with an overlay mount can cause unexpected failures.  It is recommended that you do not modify the directory until the container finishes running.
1041
1042
1043
1044       By default bind mounted volumes are private. That means any mounts done
1045       inside container will not be visible on the host and vice  versa.  This
1046       behavior  can be changed by specifying a volume mount propagation prop‐
1047       erty.
1048
1049
1050       When the mount propagation policy is set to  shared,  any  mounts  com‐
1051       pleted  inside the container on that volume will be visible to both the
1052       host and container. When the mount propagation policy is set to  slave,
1053       one  way  mount  propagation is enabled and any mounts completed on the
1054       host for that volume will be visible only inside of the container.   To
1055       control   the   mount  propagation  property  of  the  volume  use  the
1056       :[r]shared, :[r]slave or :[r]private propagation flag. The  propagation
1057       property can be specified only for bind mounted volumes and not for in‐
1058       ternal volumes or named volumes. For mount propagation to work  on  the
1059       source  mount point (the mount point where source dir is mounted on) it
1060       has to have the right propagation properties. For shared  volumes,  the
1061       source  mount point has to be shared. And for slave volumes, the source
1062       mount has to be either shared or slave. [1] ⟨#Footnote1⟩
1063
1064
1065       Use df <source-dir> to determine the source mount and then use  findmnt
1066       -o TARGET,PROPAGATION <source-mount-dir> to determine propagation prop‐
1067       erties of source mount, if findmnt utility is not available, the source
1068       mount  point  can  be  determined  by  looking  at  the  mount entry in
1069       /proc/self/mountinfo. Look at optional fields and see if  any  propaga‐
1070       tion  properties  are  specified.   shared:X means the mount is shared,
1071       master:X means the mount is slave and if nothing is  there  that  means
1072       the mount is private. [1] ⟨#Footnote1⟩
1073
1074
1075       To  change  propagation  properties of a mount point use the mount com‐
1076       mand. For example, to bind mount the source  directory  /foo  do  mount
1077       --bind /foo /foo and mount --make-private --make-shared /foo. This will
1078       convert /foo into a shared mount point.  The propagation properties  of
1079       the  source  mount  can  be  changed directly. For instance if / is the
1080       source mount for /foo, then use mount --make-shared / to convert / into
1081       a shared mount.
1082
1083

BUILD TIME VARIABLES

1085       The  ENV  instruction in a Containerfile can be used to define variable
1086       values.  When the image is built, the values will persist in  the  con‐
1087       tainer  image.   At times it is more convenient to change the values in
1088       the Containerfile via a command-line option rather  than  changing  the
1089       values within the Containerfile itself.
1090
1091
1092       The following variables can be used in conjunction with the --build-arg
1093       option to override the corresponding values set  in  the  Containerfile
1094       using the ENV instruction.
1095
1096
1097              • HTTP_PROXY
1098
1099              • HTTPS_PROXY
1100
1101              • FTP_PROXY
1102
1103              • NO_PROXY
1104
1105
1106
1107       Please refer to the Using Build Time Variables ⟨#using-build-time-vari‐
1108       ables⟩ section of the Examples.
1109
1110

EXAMPLE

1112   Build an image using local Containerfiles
1113       buildah build .
1114
1115
1116       buildah build -f Containerfile .
1117
1118
1119       cat ~/Dockerfile | buildah build -f - .
1120
1121
1122       buildah build -f Dockerfile.simple -f Dockerfile.notsosimple .
1123
1124
1125       buildah build --timestamp=$(date '+%s') -t imageName .
1126
1127
1128       buildah build -t imageName .
1129
1130
1131       buildah build --tls-verify=true -t imageName -f Dockerfile.simple .
1132
1133
1134       buildah build --tls-verify=false -t imageName .
1135
1136
1137       buildah build --runtime-flag log-format=json .
1138
1139
1140       buildah build -f Containerfile --runtime-flag debug .
1141
1142
1143       buildah  build  --authfile  /tmp/auths/myauths.json  --cert-dir  ~/auth
1144       --tls-verify=true  --creds=username:password  -t  imageName  -f Docker‐
1145       file.simple .
1146
1147
1148       buildah  build  --memory  40m  --cpu-period  10000  --cpu-quota   50000
1149       --ulimit nofile=1024:1028 -t imageName .
1150
1151
1152       buildah  build  --security-opt label=level:s0:c100,c200 --cgroup-parent
1153       /path/to/cgroup/parent -t imageName .
1154
1155
1156       buildah build --arch=arm --variant v7 -t imageName .
1157
1158
1159       buildah build --volume /home/test:/myvol:ro,Z -t imageName .
1160
1161
1162       buildah build -v /home/test:/myvol:z,U -t imageName .
1163
1164
1165       buildah build -v /var/lib/dnf:/var/lib/dnf:O -t imageName .
1166
1167
1168       buildah build --layers -t imageName .
1169
1170
1171       buildah build --no-cache -t imageName .
1172
1173
1174       buildah build -f Containerfile --layers --force-rm -t imageName .
1175
1176
1177       buildah build --no-cache --rm=false -t imageName .
1178
1179
1180       buildah  build   --dns-search=example.com   --dns=223.5.5.5   --dns-op‐
1181       tion=use-vc .
1182
1183
1184       buildah build -f Containerfile.in -t imageName .
1185
1186
1187   Building  an multi-architecture image using the --manifest option (requires
1188       emulation software)
1189       buildah build --arch arm --manifest myimage /tmp/mysrc
1190
1191
1192       buildah build --arch amd64 --manifest myimage /tmp/mysrc
1193
1194
1195       buildah build --arch s390x --manifest myimage /tmp/mysrc
1196
1197
1198       buildah bud --platform linux/s390x,linux/ppc64le,linux/amd64 --manifest
1199       myimage /tmp/mysrc
1200
1201
1202       buildah  bud  --platform  linux/arm64 --platform linux/amd64 --manifest
1203       myimage /tmp/mysrc
1204
1205
1206   Building an image using a URL
1207       This will clone the specified GitHub repository from the URL and use it
1208       as  context. The Containerfile or Dockerfile at the root of the reposi‐
1209       tory is used as the context of the build. This only works if the GitHub
1210       repository is a dedicated repository.
1211
1212
1213       buildah build github.com/scollier/purpletest
1214
1215
1216       Note: You can set an arbitrary Git repository via the git:// scheme.
1217
1218
1219   Building an image using a URL to a tarball'ed context
1220       Buildah  will fetch the tarball archive, decompress it and use its con‐
1221       tents as the build context.  The Containerfile  or  Dockerfile  at  the
1222       root  of  the  archive and the rest of the archive will get used as the
1223       context of the build. If you pass an -f  PATH/Containerfile  option  as
1224       well,  the  system  will  look for that file inside the contents of the
1225       tarball.
1226
1227
1228       buildah  build  -f   dev/Containerfile   https://10.10.10.1/docker/con
1229       text.tar.gz
1230
1231
1232       Note:  supported  compression  formats  are  'xz',  'bzip2', 'gzip' and
1233       'identity' (no compression).
1234
1235
1236   Using Build Time Variables
1237   Replace the value set for the HTTP_PROXY environment  variable  within  the
1238       Containerfile.
1239       buildah build --build-arg=HTTP_PROXY="http://127.0.0.1:8321"
1240
1241

ENVIRONMENT

1243       BUILD_REGISTRY_SOURCES
1244
1245
1246       BUILD_REGISTRY_SOURCES,  if set, is treated as a JSON object which con‐
1247       tains lists  of  registry  names  under  the  keys  insecureRegistries,
1248       blockedRegistries, and allowedRegistries.
1249
1250
1251       When  pulling  an  image  from  a registry, if the name of the registry
1252       matches any of the items in the blockedRegistries list, the image  pull
1253       attempt  is  denied.   If there are registries in the allowedRegistries
1254       list, and the registry's name is not in the list, the pull  attempt  is
1255       denied.
1256
1257
1258       TMPDIR The TMPDIR environment variable allows the user to specify where
1259       temporary files are stored while pulling and pushing images.   Defaults
1260       to '/var/tmp'.
1261
1262

Files

1264   .containerignore/.dockerignore
1265       If the .containerignore/.dockerignore file exists in the context direc‐
1266       tory, buildah build reads its contents. If both exist, then .container‐
1267       ignore  is used.  Use the --ignorefile flag to override the ignore file
1268       path location. Buildah uses the content to exclude files  and  directo‐
1269       ries from the context directory, when executing COPY and ADD directives
1270       in the Containerfile/Dockerfile
1271
1272
1273       Users can specify a series of Unix shell globals in a
1274
1275
1276       Buildah supports a special wildcard string ** which matches any  number
1277       of  directories  (including  zero). For example, */.go will exclude all
1278       files that end with .go that are found in all directories.
1279
1280
1281       Example .containerignore file:
1282
1283
1284              # exclude this content for image
1285              */*.c
1286              **/output*
1287              src
1288
1289
1290
1291       */*.c Excludes files and directories whose names ends with  .c  in  any
1292       top  level  subdirectory.  For  example,  the source file include/root‐
1293       less.c.
1294
1295
1296       **/output* Excludes files and directories starting with output from any
1297       directory.
1298
1299
1300       src  Excludes files named src and the directory src as well as any con‐
1301       tent in it.
1302
1303
1304       Lines starting with ! (exclamation mark) can be used to make exceptions
1305       to  exclusions. The following is an example .containerignore/.dockerig‐
1306       nore file that uses this mechanism:
1307
1308
1309              *.doc
1310              !Help.doc
1311
1312
1313
1314       Exclude all doc files except Help.doc from the image.
1315
1316
1317       This functionality is compatible with  the  handling  of  .dockerignore
1318       files described here:
1319
1320
1321       https://docs.docker.com/engine/reference/builder/#dockerignore-file
1322
1323
1324       registries.conf (/etc/containers/registries.conf)
1325
1326
1327       registries.conf  is  the  configuration file which specifies which con‐
1328       tainer registries should be consulted when completing image names which
1329       do not include a registry or domain portion.
1330
1331
1332       policy.json (/etc/containers/policy.json)
1333
1334
1335       Signature policy file.  This defines the trust policy for container im‐
1336       ages.  Controls which container registries can be used for  image,  and
1337       whether or not the tool should trust the images.
1338
1339

SEE ALSO

1341       buildah(1),  cpp(1),  buildah-login(1), docker-login(1), namespaces(7),
1342       pid_namespaces(7),      containers-policy.json(5),      containers-reg‐
1343       istries.conf(5), user_namespaces(7), crun(1), runc(8)
1344
1345

FOOTNOTES

1347       1:  The  Buildah  project  is committed to inclusivity, a core value of
1348       open source. The master and slave mount  propagation  terminology  used
1349       here is problematic and divisive, and should be changed. However, these
1350       terms are currently used within the Linux kernel and must be used as-is
1351       at  this  time. When the kernel maintainers rectify this usage, Buildah
1352       will follow suit immediately.
1353
1354
1355
1356buildah                           April 2017                  buildah-build(1)
Impressum