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

DESCRIPTION

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

OPTIONS

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

BUILD TIME VARIABLES

1180       The ENV instruction in a Containerfile can be used to  define  variable
1181       values.   When  the image is built, the values will persist in the con‐
1182       tainer image.  At times it is more convenient to change the  values  in
1183       the  Containerfile  via  a command-line option rather than changing the
1184       values within the Containerfile itself.
1185
1186
1187       The following variables can be used in conjunction with the --build-arg
1188       option  to  override  the corresponding values set in the Containerfile
1189       using the ENV instruction.
1190
1191
1192              • HTTP_PROXY
1193
1194              • HTTPS_PROXY
1195
1196              • FTP_PROXY
1197
1198              • NO_PROXY
1199
1200
1201
1202       Please refer to the Using Build Time Variables ⟨#using-build-time-vari‐
1203       ables⟩ section of the Examples.
1204
1205

EXAMPLE

1207   Build an image using local Containerfiles
1208       buildah build .
1209
1210
1211       buildah build -f Containerfile .
1212
1213
1214       cat ~/Containerfile | buildah build -f - .
1215
1216
1217       buildah build -f Containerfile.simple -f Containerfile.notsosimple .
1218
1219
1220       buildah build --timestamp=$(date '+%s') -t imageName .
1221
1222
1223       buildah build -t imageName .
1224
1225
1226       buildah build --tls-verify=true -t imageName -f Containerfile.simple .
1227
1228
1229       buildah build --tls-verify=false -t imageName .
1230
1231
1232       buildah build --runtime-flag log-format=json .
1233
1234
1235       buildah build -f Containerfile --runtime-flag debug .
1236
1237
1238       buildah  build  --authfile  /tmp/auths/myauths.json  --cert-dir  ~/auth
1239       --tls-verify=true --creds=username:password -t imageName -f  Container‐
1240       file.simple .
1241
1242
1243       buildah   build  --memory  40m  --cpu-period  10000  --cpu-quota  50000
1244       --ulimit nofile=1024:1028 -t imageName .
1245
1246
1247       buildah build --security-opt  label=level:s0:c100,c200  --cgroup-parent
1248       /path/to/cgroup/parent -t imageName .
1249
1250
1251       buildah build --arch=arm --variant v7 -t imageName .
1252
1253
1254       buildah build --volume /home/test:/myvol:ro,Z -t imageName .
1255
1256
1257       buildah build -v /home/test:/myvol:z,U -t imageName .
1258
1259
1260       buildah build -v /var/lib/dnf:/var/lib/dnf:O -t imageName .
1261
1262
1263       buildah build --layers -t imageName .
1264
1265
1266       buildah build --no-cache -t imageName .
1267
1268
1269       buildah build -f Containerfile --layers --force-rm -t imageName .
1270
1271
1272       buildah build --no-cache --rm=false -t imageName .
1273
1274
1275       buildah   build   --dns-search=example.com   --dns=223.5.5.5  --dns-op‐
1276       tion=use-vc .
1277
1278
1279       buildah build -f Containerfile.in -t imageName .
1280
1281
1282       buildah build --network mynet .
1283
1284
1285       buildah build --env LANG=en_US.UTF-8 -t imageName .
1286
1287
1288       buildah build --env EDITOR -t imageName .
1289
1290
1291       buildah build --unsetenv LANG -t imageName .
1292
1293
1294       buildah build --os-version 10.0.19042.1645 -t imageName .
1295
1296
1297       buildah build --os-feature win32k -t imageName .
1298
1299
1300       buildah build --os-feature win32k- -t imageName .
1301
1302
1303   Building an multi-architecture image using the --manifest option  (requires
1304       emulation software)
1305       buildah build --arch arm --manifest myimage /tmp/mysrc
1306
1307
1308       buildah build --arch amd64 --manifest myimage /tmp/mysrc
1309
1310
1311       buildah build --arch s390x --manifest myimage /tmp/mysrc
1312
1313
1314       buildah bud --platform linux/s390x,linux/ppc64le,linux/amd64 --manifest
1315       myimage /tmp/mysrc
1316
1317
1318       buildah bud --platform linux/arm64  --platform  linux/amd64  --manifest
1319       myimage /tmp/mysrc
1320
1321
1322       buildah bud --all-platforms --manifest myimage /tmp/mysrc
1323
1324
1325   Building an image using (--output) custom build output
1326       buildah build -o out .
1327
1328
1329       buildah build --output type=local,dest=out .
1330
1331
1332       buildah build --output type=tar,dest=out.tar .
1333
1334
1335       buildah build -o - . > out.tar
1336
1337
1338   Building an image using a URL
1339       This will clone the specified GitHub repository from the URL and use it
1340       as context. The Containerfile or Dockerfile at the root of the  reposi‐
1341       tory is used as the context of the build. This only works if the GitHub
1342       repository is a dedicated repository.
1343
1344
1345       buildah build github.com/scollier/purpletest
1346
1347
1348       Note: You can set an arbitrary Git repository via the git:// scheme.
1349
1350
1351   Building an image using a URL to a tarball'ed context
1352       Buildah will fetch the tarball archive, decompress it and use its  con‐
1353       tents  as  the  build  context.  The Containerfile or Dockerfile at the
1354       root of the archive and the rest of the archive will get  used  as  the
1355       context  of  the  build. If you pass an -f PATH/Containerfile option as
1356       well, the system will look for that file inside  the  contents  of  the
1357       tarball.
1358
1359
1360       buildah   build  -f  dev/Containerfile  https://10.10.10.1/buildah/con
1361       text.tar.gz
1362
1363
1364       Note: supported compression  formats  are  'xz',  'bzip2',  'gzip'  and
1365       'identity' (no compression).
1366
1367
1368   Using Build Time Variables
1369   Replace  the  value  set for the HTTP_PROXY environment variable within the
1370       Containerfile.
1371       buildah build --build-arg=HTTP_PROXY="http://127.0.0.1:8321"
1372
1373

ENVIRONMENT

1375       BUILD_REGISTRY_SOURCES
1376
1377
1378       BUILD_REGISTRY_SOURCES, if set, is treated as a JSON object which  con‐
1379       tains  lists  of  registry  names  under  the  keys insecureRegistries,
1380       blockedRegistries, and allowedRegistries.
1381
1382
1383       When pulling an image from a registry, if  the  name  of  the  registry
1384       matches  any of the items in the blockedRegistries list, the image pull
1385       attempt is denied.  If there are registries  in  the  allowedRegistries
1386       list,  and  the registry's name is not in the list, the pull attempt is
1387       denied.
1388
1389
1390       TMPDIR The TMPDIR environment variable allows the user to specify where
1391       temporary  files are stored while pulling and pushing images.  Defaults
1392       to '/var/tmp'.
1393
1394

Files

1396   .containerignore/.dockerignore
1397       If the .containerignore/.dockerignore file exists in the context direc‐
1398       tory, buildah build reads its contents. If both exist, then .container‐
1399       ignore is used.  Use the --ignorefile flag to override the ignore  file
1400       path  location.  Buildah uses the content to exclude files and directo‐
1401       ries from the context directory, when executing COPY and ADD directives
1402       in the Containerfile/Dockerfile
1403
1404
1405       Users can specify a series of Unix shell globals in a
1406
1407
1408       Buildah  supports a special wildcard string ** which matches any number
1409       of directories (including zero). For example, */.go  will  exclude  all
1410       files that end with .go that are found in all directories.
1411
1412
1413       Example .containerignore file:
1414
1415
1416              # exclude this content for image
1417              */*.c
1418              **/output*
1419              src
1420
1421
1422
1423       */*.c Excludes files and directories whose names end with .c in any top
1424       level subdirectory. For example, the source file include/rootless.c.
1425
1426
1427       **/output* Excludes files and directories starting with output from any
1428       directory.
1429
1430
1431       src  Excludes files named src and the directory src as well as any con‐
1432       tent in it.
1433
1434
1435       Lines starting with ! (exclamation mark) can be used to make exceptions
1436       to  exclusions. The following is an example .containerignore/.dockerig‐
1437       nore file that uses this mechanism:
1438
1439
1440              *.doc
1441              !Help.doc
1442
1443
1444
1445       Exclude all doc files except Help.doc from the image.
1446
1447
1448       This functionality is compatible with the handling of  .containerignore
1449       files described here:
1450
1451
1452       https://github.com/containers/buildah/blob/main/docs/containerig
1453       nore.5.md
1454
1455
1456       registries.conf (/etc/containers/registries.conf)
1457
1458
1459       registries.conf is the configuration file which  specifies  which  con‐
1460       tainer registries should be consulted when completing image names which
1461       do not include a registry or domain portion.
1462
1463
1464       policy.json (/etc/containers/policy.json)
1465
1466
1467       Signature policy file.  This defines the trust policy for container im‐
1468       ages.   Controls  which container registries can be used for image, and
1469       whether or not the tool should trust the images.
1470
1471

SEE ALSO

1473       buildah(1), cpp(1), buildah-login(1),  docker-login(1),  namespaces(7),
1474       pid_namespaces(7),      containers-policy.json(5),      containers-reg‐
1475       istries.conf(5), user_namespaces(7), crun(1), runc(8)
1476
1477

FOOTNOTES

1479       1: The Buildah project is committed to inclusivity,  a  core  value  of
1480       open  source.  The  master and slave mount propagation terminology used
1481       here is problematic and divisive, and should be changed. However, these
1482       terms are currently used within the Linux kernel and must be used as-is
1483       at this time. When the kernel maintainers rectify this  usage,  Buildah
1484       will follow suit immediately.
1485
1486
1487
1488buildah                           April 2017                  buildah-build(1)
Impressum