1buildah-build(1) General Commands Manual buildah-build(1)
2
6 buildah-build - Build an image using instructions from Containerfiles
7
10 buildah build [options] [context]
11 buildah bud [options] [context]
14
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 The build context directory can be specified as the http(s) URL of an
25 archive, git repository or Containerfile.
26 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 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 When the URL is an archive, the contents of the URL is downloaded to a
43 temporary location and extracted before execution.
44 When the URL is a Containerfile, the file is downloaded to a temporary
47 location.
48 When a Git repository is set as the URL, the repository is cloned lo‐
51 cally and then used as the build context. A non-default branch (or
52 commit ID) and subdirectory of the cloned git repository can be used by
53 including their names at the end of the URL in the form myrepo.git#my‐
54 branch:subdir, myrepo.git#mycommit:subdir, or myrepo.git#:subdir if the
55 subdirectory should be used from the default branch.
56
59 --add-host=[]
60 Add a custom host-to-IP mapping (host:ip)
63 Add a line to /etc/hosts. The format is hostname:ip. The --add-host op‐
66 tion can be set multiple times. Conflicts with the --no-hosts option.
67 --all-platforms
70 Instead of building for a set of platforms specified using the --plat‐
73 form option, inspect the build's base images, and build for all of the
74 platforms for which they are all available. Stages that use scratch as
75 a starting point can not be inspected, so at least one non-scratch
76 stage must be present for detection to work usefully.
77 --annotation annotation[=value]
80 Add an image annotation (e.g. annotation=value) to the image metadata.
83 Can be used multiple times. If annotation is named, but neither = nor
84 a value is provided, then the annotation is set to an empty value.
85 Note: this information is not present in Docker image formats, so it is
88 discarded when writing images in Docker formats.
89 --arch="ARCH"
92 Set the ARCH of the image to be built, and that of the base image to be
95 pulled, if the build uses one, to the provided value instead of using
96 the architecture of the host. (Examples: arm, arm64, 386, amd64,
97 ppc64le, s390x)
98 --authfile path
101 Path of the authentication file. Default is ${XDG_\RUNTIME_DIR}/con‐
104 tainers/auth.json. If XDG_RUNTIME_DIR is not set, the default is
105 /run/containers/$UID/auth.json. This file is created using buildah lo‐
106 gin.
107 If the authorization state is not found there, $HOME/.docker/con‐
110 fig.json is checked, which is set using docker login.
111 Note: You can also override the default path of the authentication file
114 by setting the REGISTRY_AUTH_FILE environment variable. export REG‐
115 ISTRY_AUTH_FILE=path
116 --build-arg arg=value
119 Specifies a build argument and its value, which will be interpolated in
122 instructions read from the Containerfiles in the same way that environ‐
123 ment variables are, but which will not be added to environment variable
124 list in the resulting image's configuration.
125 Please refer to the BUILD TIME VARIABLES ⟨#build-time-variables⟩ sec‐
128 tion for the list of variables that can be overridden within the Con‐
129 tainerfile at run time.
130 --build-arg-file path
133 Specifies a file containing lines of build arguments of the form
136 arg=value. The suggested file name is argfile.conf.
137 Comment lines beginning with # are ignored, along with blank lines. All
140 others should be of the arg=value format passed to --build-arg.
141 If several arguments are provided via the --build-arg-file and --build-
144 arg options, the build arguments will be merged across all of the pro‐
145 vided files and command line arguments.
146 Any file provided in a --build-arg-file option will be read before the
149 arguments supplied via the --build-arg option.
150 When a given argument name is specified several times, the last in‐
153 stance is the one that is passed to the resulting builds. This means
154 --build-arg values always override those in a --build-arg-file.
155 --build-context name=value
158 Specify an additional build context using its short name and its loca‐
161 tion. Additional build contexts can be referenced in the same manner as
162 we access different stages in COPY instruction.
163 Valid values could be: * Local directory – e.g. --build-context
166 project2=../path/to/project2/src * HTTP URL to a tarball – e.g.
167 --build-context src=https://example.org/releases/src.tar * Container
168 image – specified with a container-image:// prefix, e.g. --build-con‐
169 text alpine=container-image://alpine:3.15, (also accepts docker://,
170 docker-image://)
171 On the Containerfile side, you can reference the build context on all
174 commands that accept the “from” parameter. Here’s how that might look:
175 FROM [name]
178 COPY --from=[name] ...
179 RUN --mount=from=[name] …
180 The value of [name] is matched with the following priority order:
184 • Named build context defined with --build-context [name]=..
187 • Stage defined with AS [name] inside Containerfile
189 • Image [name], either local or in a remote registry
191 --cache-from
195 Repository to utilize as a potential list of cache sources. When speci‐
198 fied, Buildah will try to look for cache images in the specified repos‐
199 itories and will attempt to pull cache images instead of actually exe‐
200 cuting the build steps locally. Buildah will only attempt to pull pre‐
201 viously cached images if they are considered as valid cache hits.
202 Use the --cache-to option to populate a remote repository or reposito‐
205 ries with cache content.
206 Example
209 # populate a cache and also consult it
212 buildah build -t test --layers --cache-to registry/myrepo/cache --cache-from registry/myrepo/cache .
213 Note: --cache-from option is ignored unless --layers is specified.
217 Note: Buildah's --cache-from option is designed differently than Docker
220 and BuildKit's --cache-from option. Buildah's distributed cache mecha‐
221 nism pulls intermediate images from the remote registry itself, unlike
222 Docker and BuildKit where the intermediate image is stored in the image
223 itself. Buildah's approach is similar to kaniko, which does not inflate
224 the size of the original image with intermediate images. Also, inter‐
225 mediate images can truly be kept distributed across one or more remote
226 registries using Buildah's caching mechanism.
227 --cache-to
230 Set this flag to specify list of remote repositories that will be used
233 to store cache images. Buildah will attempt to push newly built cache
234 image to the remote repositories.
235 Note: Use the --cache-from option in order to use cache content in a
238 remote repository.
239 Example
242 # populate a cache and also consult it
245 buildah build -t test --layers --cache-to registry/myrepo/cache --cache-from registry/myrepo/cache .
246 Note: --cache-to option is ignored unless --layers is specified.
250 Note: Buildah's --cache-to option is designed differently than Docker
253 and BuildKit's --cache-to option. Buildah's distributed cache mechanism
254 push intermediate images to the remote registry itself, unlike Docker
255 and BuildKit where the intermediate image is stored in the image it‐
256 self. Buildah's approach is similar to kaniko, which does not inflate
257 the size of the original image with intermediate images. Also, inter‐
258 mediate images can truly be kept distributed across one or more remote
259 registries using Buildah's caching mechanism.
260 --cache-ttl duration
263 Limit the use of cached images to only consider images with created
266 timestamps less than duration ago. For example if --cache-ttl=1h is
267 specified, Buildah will only consider intermediate cache images which
268 are created under the duration of one hour, and intermediate cache im‐
269 ages outside this duration will be ignored.
270 Note: Setting --cache-ttl=0 manually is equivalent to using --no-cache
273 in the implementation since this would effectively mean that user is
274 not willing to use cache at all.
275 --cap-add=CAP_xxx
278 When executing RUN instructions, run the command specified in the in‐
281 struction with the specified capability added to its capability set.
282 Certain capabilities are granted by default; this option can be used to
283 add more.
284 --cap-drop=CAP_xxx
287 When executing RUN instructions, run the command specified in the in‐
290 struction with the specified capability removed from its capability
291 set. The CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_FOWNER, CAP_FSETID,
292 CAP_KILL, CAP_NET_BIND_SERVICE, CAP_SETFCAP, CAP_SETGID, CAP_SETPCAP,
293 and CAP_SETUID capabilities are granted by default; this option can be
294 used to remove them. The list of default capabilities is managed in
295 containers.conf(5).
296 If a capability is specified to both the --cap-add and --cap-drop op‐
299 tions, it will be dropped, regardless of the order in which the options
300 were given.
301 --cert-dir path
304 Use certificates at path (*.crt, *.cert, *.key) to connect to the reg‐
307 istry. The default certificates directory is /etc/containers/certs.d.
308 --cgroup-parent=""
311 Path to cgroups under which the cgroup for the container will be cre‐
314 ated. If the path is not absolute, the path is considered to be rela‐
315 tive to the cgroups path of the init process. Cgroups will be created
316 if they do not already exist.
317 --cgroupns how
320 Sets the configuration for cgroup namespaces when handling RUN instruc‐
323 tions. The configured value can be "" (the empty string) or "private"
324 to indicate that a new cgroup namespace should be created, or it can be
325 "host" to indicate that the cgroup namespace in which buildah itself is
326 being run should be reused.
327 --compress
330 This option is added to be aligned with other containers CLIs. Buildah
333 doesn't send a copy of the context directory to a daemon or a remote
334 server. Thus, compressing the data before sending it is irrelevant to
335 Buildah.
336 --cpp-flag=""
339 Set additional flags to pass to the C Preprocessor cpp(1). Container‐
342 files ending with a ".in" suffix will be preprocessed via cpp(1). This
343 option can be used to pass additional flags to cpp. Note: You can also
344 set default CPPFLAGS by setting the BUILDAH_CPPFLAGS environment vari‐
345 able (e.g., export BUILDAH_CPPFLAGS="-DDEBUG").
346 --cpu-period=0
349 Set the CPU period for the Completely Fair Scheduler (CFS), which is a
352 duration in microseconds. Once the container's CPU quota is used up, it
353 will not be scheduled to run until the current period ends. Defaults to
354 100000 microseconds.
355 On some systems, changing the CPU limits may not be allowed for non-
358 root users. For more details, see https://github.com/containers/pod‐
359 man/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-
360 fails-with-a-permissions-error
361 --cpu-quota=0
364 Limit the CPU CFS (Completely Fair Scheduler) quota
367 Limit the container's CPU usage. By default, containers run with the
370 full CPU resource. This flag tells the kernel to restrict the con‐
371 tainer's CPU usage to the quota you specify.
372 On some systems, changing the CPU limits may not be allowed for non-
375 root users. For more details, see https://github.com/containers/pod‐
376 man/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-
377 fails-with-a-permissions-error
378 --cpu-shares, -c=0
381 CPU shares (relative weight)
384 By default, all containers get the same proportion of CPU cycles. This
387 proportion can be modified by changing the container's CPU share
388 weighting relative to the weighting of all other running containers.
389 To modify the proportion from the default of 1024, use the --cpu-shares
392 flag to set the weighting to 2 or higher.
393 The proportion will only apply when CPU-intensive processes are run‐
396 ning. When tasks in one container are idle, other containers can use
397 the left-over CPU time. The actual amount of CPU time will vary depend‐
398 ing on the number of containers running on the system.
399 For example, consider three containers, one has a cpu-share of 1024 and
402 two others have a cpu-share setting of 512. When processes in all three
403 containers attempt to use 100% of CPU, the first container would re‐
404 ceive 50% of the total CPU time. If you add a fourth container with a
405 cpu-share of 1024, the first container only gets 33% of the CPU. The
406 remaining containers receive 16.5%, 16.5% and 33% of the CPU.
407 On a multi-core system, the shares of CPU time are distributed over all
410 CPU cores. Even if a container is limited to less than 100% of CPU
411 time, it can use 100% of each individual CPU core.
412 For example, consider a system with more than three cores. If you start
415 one container {C0} with -c=512 running one process, and another con‐
416 tainer {C1} with -c=1024 running two processes, this can result in the
417 following division of CPU shares:
418 PID container CPU CPU share
421 100 {C0} 0 100% of CPU0
422 101 {C1} 1 100% of CPU1
423 102 {C1} 2 100% of CPU2
424 --cpuset-cpus=""
428 CPUs in which to allow execution (0-3, 0,1)
431 --cpuset-mems=""
434 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effec‐
437 tive on NUMA systems.
438 If you have four memory nodes on your system (0-3), use --cpuset-
441 mems=0,1 then processes in your container will only use memory from the
442 first two memory nodes.
443 --creds creds
446 The [username[:password]] to use to authenticate with the registry if
449 required. If one or both values are not supplied, a command line
450 prompt will appear and the value can be entered. The password is en‐
451 tered without echo.
452 --cw options
455 Produce an image suitable for use as a confidential workload running in
458 a trusted execution environment (TEE) using krun (i.e., crun built with
459 the libkrun feature enabled and invoked as krun). Instead of the con‐
460 ventional contents, the root filesystem of the image will contain an
461 encrypted disk image and configuration information for krun.
462 The value for options is a comma-separated list of key=value pairs,
465 supplying configuration information which is needed for producing the
466 additional data which will be included in the container image.
467 Recognized keys are:
470 attestation_url: The location of a key broker / attestation server. If
473 a value is specified, the new image's workload ID, along with the
474 passphrase used to encrypt the disk image, will be registered with the
475 server, and the server's location will be stored in the container im‐
476 age. At run-time, krun is expected to contact the server to retrieve
477 the passphrase using the workload ID, which is also stored in the con‐
478 tainer image. If no value is specified, a passphrase value must be
479 specified.
480 cpus: The number of virtual CPUs which the image expects to be run with
483 at run-time. If not specified, a default value will be supplied.
484 firmware_library: The location of the libkrunfw-sev shared library. If
487 not specified, buildah checks for its presence in a number of hard-
488 coded locations.
489 memory: The amount of memory which the image expects to be run with at
492 run-time, as a number of megabytes. If not specified, a default value
493 will be supplied.
494 passphrase: The passphrase to use to encrypt the disk image which will
497 be included in the container image. If no value is specified, but an
498 attestation_url value is specified, a randomly-generated passphrase
499 will be used. The authors recommend setting an attestation_url but not
500 a passphrase.
501 slop: Extra space to allocate for the disk image compared to the size
504 of the container image's contents, expressed either as a percentage
505 (..%) or a size value (bytes, or larger units if suffixes like KB or MB
506 are present), or a sum of two or more such specifications. If not
507 specified, buildah guesses that 25% more space than the contents will
508 be enough, but this option is provided in case its guess is wrong.
509 type: The type of trusted execution environment (TEE) which the image
512 should be marked for use with. Accepted values are "SEV" (AMD Secure
513 Encrypted Virtualization - Encrypted State) and "SNP" (AMD Secure En‐
514 crypted Virtualization - Secure Nested Paging). If not specified, de‐
515 faults to "SNP".
516 workload_id: A workload identifier which will be recorded in the con‐
519 tainer image, to be used at run-time for retrieving the passphrase
520 which was used to encrypt the disk image. If not specified, a semi-
521 random value will be derived from the base image's image ID.
522 --decryption-key key[:passphrase]
525 The [key[:passphrase]] to be used for decryption of images. Key can
528 point to keys and/or certificates. Decryption will be tried with all
529 keys. If the key is protected by a passphrase, it is required to be
530 passed in the argument and omitted otherwise.
531 --device=device
534 Add a host device to the container. Optional permissions parameter can
537 be used to specify device permissions, it is combination of r for read,
538 w for write, and m for mknod(2).
539 Example: --device=/dev/sdc:/dev/xvdc:rwm.
542 Note: if _hostdevice is a symbolic link then it will be resolved first.
545 The container will only store the major and minor numbers of the host
546 device.
547 Note: if the user only has access rights via a group, accessing the de‐
550 vice from inside a rootless container will fail. The crun(1) runtime
551 offers a workaround for this by adding the option --annotation
552 run.oci.keep_original_groups=1.
553 --disable-compression, -D
556 Don't compress filesystem layers when building the image unless it is
559 required by the location where the image is being written. This is the
560 default setting, because image layers are compressed automatically when
561 they are pushed to registries, and images being written to local stor‐
562 age would only need to be decompressed again to be stored. Compression
563 can be forced in all cases by specifying --disable-compression=false.
564 --disable-content-trust
567 This is a Docker specific option to disable image verification to a
570 Container registry and is not supported by Buildah. This flag is a
571 NOOP and provided solely for scripting compatibility.
572 --dns=[]
575 Set custom DNS servers. Invalid if using --dns with --network=none.
578 This option can be used to override the DNS configuration passed to the
581 container. Typically this is necessary when the host DNS configuration
582 is invalid for the container (e.g., 127.0.0.1). When this is the case
583 the --dns flag is necessary for every run.
584 The special value none can be specified to disable creation of /etc/re‐
587 solv.conf in the container by Buildah. The /etc/resolv.conf file in the
588 image will be used without changes.
589 --dns-option=[]
592 Set custom DNS options. Invalid if using --dns-option with --net‐
595 work=none.
596 --dns-search=[]
599 Set custom DNS search domains. Invalid if using --dns-search with
602 --network=none.
603 --env env[=value]
606 Add a value (e.g. env=value) to the built image. Can be used multiple
609 times. If neither = nor a *value* are specified, but env is set in the
610 current environment, the value from the current environment will be
611 added to the image. The value of env can be overridden by ENV instruc‐
612 tions in the Containerfile. To remove an environment variable from the
613 built image, use the --unsetenv option.
614 --file, -f Containerfile
617 Specifies a Containerfile which contains instructions for building the
620 image, either a local file or an http or https URL. If more than one
621 Containerfile is specified, FROM instructions will only be accepted
622 from the last specified file.
623 If a local file is specified as the Containerfile and it does not ex‐
626 ist, the context directory will be prepended to the local file value.
627 If you specify -f -, the Containerfile contents will be read from
630 stdin.
631 --force-rm bool-value
634 Always remove intermediate containers after a build, even if the build
637 fails (default false).
638 --format
641 Control the format for the built image's manifest and configuration
644 data. Recognized formats include oci (OCI image-spec v1.0, the de‐
645 fault) and docker (version 2, using schema format 2 for the manifest).
646 Note: You can also override the default format by setting the BUIL‐
649 DAH_FORMAT environment variable. export BUILDAH_FORMAT=docker
650 --from
653 Overrides the first FROM instruction within the Containerfile. If
656 there are multiple FROM instructions in a Containerfile, only the first
657 is changed.
658 --group-add=group | keep-groups
661 Assign additional groups to the primary user running within the con‐
664 tainer process.
665 • keep-groups is a special flag that tells Buildah to keep the
668 supplementary group access.
669 Allows container to use the user's supplementary group access. If file
673 systems or devices are only accessible by the rootless user's group,
674 this flag tells the OCI runtime to pass the group access into the con‐
675 tainer. Currently only available with the crun OCI runtime. Note: keep-
676 groups is exclusive, other groups cannot be specified with this flag.
677 --help, -h
680 Print usage statement
683 --hooks-dir path
686 Each *.json file in the path configures a hook for buildah build con‐
689 tainers. For more details on the syntax of the JSON files and the se‐
690 mantics of hook injection, see oci-hooks(5). Buildah currently support
691 both the 1.0.0 and 0.1.0 hook schemas, although the 0.1.0 schema is
692 deprecated.
693 This option may be set multiple times; paths from later options have
696 higher precedence (oci-hooks(5) discusses directory precedence).
697 For the annotation conditions, buildah uses any annotations set in the
700 generated OCI configuration.
701 For the bind-mount conditions, only mounts explicitly requested by the
704 caller via --volume are considered. Bind mounts that buildah inserts by
705 default (e.g. /dev/shm) are not considered.
706 If --hooks-dir is unset for root callers, Buildah will currently de‐
709 fault to /usr/share/containers/oci/hooks.d and /etc/contain‐
710 ers/oci/hooks.d in order of increasing precedence. Using these defaults
711 is deprecated, and callers should migrate to explicitly setting
712 --hooks-dir.
713 --http-proxy=true
716 By default proxy environment variables are passed into the container if
719 set for the buildah process. This can be disabled by setting the
720 --http-proxy option to false. The environment variables passed in in‐
721 clude http_proxy, https_proxy, ftp_proxy, no_proxy, and also the upper
722 case versions of those.
723 --identity-label bool-value
726 Adds default identity label io.buildah.version if set. (default true).
729 --ignorefile file
732 Path to an alternative .containerignore (.dockerignore) file.
735 --iidfile ImageIDfile
738 Write the built image's ID to the file. When --platform is specified
741 more than once, attempting to use this option will trigger an error.
742 --ipc how
745 Sets the configuration for IPC namespaces when handling RUN instruc‐
748 tions. The configured value can be "" (the empty string) or "con‐
749 tainer" to indicate that a new IPC namespace should be created, or it
750 can be "host" to indicate that the IPC namespace in which buildah it‐
751 self is being run should be reused, or it can be the path to an IPC
752 namespace which is already in use by another process.
753 --isolation type
756 Controls what type of isolation is used for running processes as part
759 of RUN instructions. Recognized types include oci (OCI-compatible run‐
760 time, the default), rootless (OCI-compatible runtime invoked using a
761 modified configuration, with --no-new-keyring added to its create invo‐
762 cation, reusing the host's network and UTS namespaces, and creating
763 private IPC, PID, mount, and user namespaces; the default for unprivi‐
764 leged users), and chroot (an internal wrapper that leans more toward
765 chroot(1) than container technology, reusing the host's control group,
766 network, IPC, and PID namespaces, and creating private mount and UTS
767 namespaces, and creating user namespaces only when they're required for
768 ID mapping).
769 Note: You can also override the default isolation type by setting the
772 BUILDAH_ISOLATION environment variable. export BUILDAH_ISOLATION=oci
773 --jobs N
776 Run up to N concurrent stages in parallel. If the number of jobs is
779 greater than 1, stdin will be read from /dev/null. If 0 is specified,
780 then there is no limit on the number of jobs that run in parallel.
781 --label label[=value]
784 Add an image label (e.g. label=value) to the image metadata. Can be
787 used multiple times. If label is named, but neither = nor a value is
788 provided, then the label is set to an empty value.
789 Users can set a special LABEL io.containers.capabilities=CAP1,CAP2,CAP3
792 in a Containerfile that specifies the list of Linux capabilities re‐
793 quired for the container to run properly. This label specified in a
794 container image tells container engines, like Podman, to run the con‐
795 tainer with just these capabilities. The container engine launches the
796 container with just the specified capabilities, as long as this list of
797 capabilities is a subset of the default list.
798 If the specified capabilities are not in the default set, container en‐
801 gines should print an error message and will run the container with the
802 default capabilities.
803 --layer-label label[=value]
806 Add an intermediate image label (e.g. label=value) to the intermediate
809 image metadata. It can be used multiple times. If label is named, but
810 neither = nor a value is provided, then the label is set to an empty
811 value.
812 --layers bool-value
815 Cache intermediate images during the build process (Default is false).
818 Note: You can also override the default value of layers by setting the
821 BUILDAH_LAYERS environment variable. export BUILDAH_LAYERS=true
822 --logfile filename
825 Log output which would be sent to standard output and standard error to
828 the specified file instead of to standard output and standard error.
829 --logsplit bool-value
832 If --logfile and --platform is specified following flag allows end-
835 users to split log file for each platform into different files with
836 naming convention as ${logfile}_${platform-os}_${platform-arch}.
837 --manifest listName
840 Name of the manifest list to which the built image will be added. Cre‐
843 ates the manifest list if it does not exist. This option is useful for
844 building multi architecture images. If listName does not include a
845 registry name component, the registry name localhost will be prepended
846 to the list name.
847 --memory, -m=""
850 Memory limit (format: [], where unit = b, k, m or g)
853 Allows you to constrain the memory available to a container. If the
856 host supports swap memory, then the -m memory setting can be larger
857 than physical RAM. If a limit of 0 is specified (not using -m), the
858 container's memory is not limited. The actual limit may be rounded up
859 to a multiple of the operating system's page size (the value would be
860 very large, that's millions of trillions).
861 --memory-swap="LIMIT"
864 A limit value equal to memory plus swap. Must be used with the -m
867 (--memory) flag. The swap LIMIT should always be larger than -m (--mem‐
868 ory) value. By default, the swap LIMIT will be set to double the value
869 of --memory.
870 The format of LIMIT is <number>[<unit>]. Unit can be b (bytes), k
873 (kilobytes), m (megabytes), or g (gigabytes). If you don't specify a
874 unit, b is used. Set LIMIT to -1 to enable unlimited swap.
875 --network, --net=mode
878 Sets the configuration for network namespaces when handling RUN in‐
881 structions.
882 Valid mode values are:
885 • none: no networking. Invalid if using --dns, --dns-opt, or
888 --dns-search;
889 • host: use the host network stack. Note: the host mode gives
891 the container full access to local system services such as D-
892 bus and is therefore considered insecure;
893 • ns:path: path to a network namespace to join;
895 • private: create a new namespace for the container (default)
897 • <network name|ID>: Join the network with the given name or ID,
899 e.g. use --network mynet to join the network with the name
900 mynet. Only supported for rootful users.
901 • slirp4netns[:OPTIONS,...]: use slirp4netns(1) to create a user
903 network stack. This is the default for rootless containers. It
904 is possible to specify these additional options, they can also
905 be set with network_cmd_options in containers.conf:
906 • allow_host_loopback=true|false: Allow slirp4netns to reach
908 the host loopback IP (default is 10.0.2.2 or the second IP
909 from slirp4netns cidr subnet when changed, see the cidr op‐
910 tion below). The default is false.
911 • mtu=MTU: Specify the MTU to use for this network. (Default
913 is 65520).
914 • cidr=CIDR: Specify ip range to use for this network. (De‐
916 fault is 10.0.2.0/24).
917 • enable_ipv6=true|false: Enable IPv6. Default is true. (Re‐
919 quired for outbound_addr6).
920 • outbound_addr=INTERFACE: Specify the outbound interface
922 slirp binds to (ipv4 traffic only).
923 • outbound_addr=IPv4: Specify the outbound ipv4 address slirp
925 binds to.
926 • outbound_addr6=INTERFACE: Specify the outbound interface
928 slirp binds to (ipv6 traffic only).
929 • outbound_addr6=IPv6: Specify the outbound ipv6 address slirp
931 binds to.
932 • pasta[:OPTIONS,...]: use pasta(1) to create a user-mode net‐
936 working stack.
937 This is only supported in rootless mode.
938 By default, IPv4 and IPv6 addresses and routes, as well as the
939 pod interface name, are copied from the host. If port forward‐
940 ing isn't configured, ports are forwarded dynamically as ser‐
941 vices are bound on either side (init namespace or container
942 namespace). Port forwarding preserves the original source IP
943 address. Options described in pasta(1) can be specified as
944 comma-separated arguments.
945 In terms of pasta(1) options, --config-net is given by de‐
946 fault, in order to configure networking when the container is
947 started, and --no-map-gw is also assumed by default, to avoid
948 direct access from container to host using the gateway ad‐
949 dress. The latter can be overridden by passing --map-gw in the
950 pasta-specific options (despite not being an actual pasta(1)
951 option).
952 Also, -t none and -u none are passed to disable automatic port
953 forwarding based on bound ports. Similarly, -T none and -U
954 none are given to disable the same functionality from con‐
955 tainer to host.
956 Some examples:
957 • pasta:--map-gw: Allow the container to directly reach the
959 host using the gateway address.
960 • pasta:--mtu,1500: Specify a 1500 bytes MTU for the tap in‐
962 terface in the container.
963 • pasta:--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-for‐
965 ward,10.0.2.3,-m,1500,--no-ndp,--no-dhcpv6,--no-dhcp, equiv‐
966 alent to default slirp4netns(1) options: disable IPv6, as‐
967 sign 10.0.2.0/24 to the tap0 interface in the container,
968 with gateway 10.0.2.3, enable DNS forwarder reachable at
969 10.0.2.3, set MTU to 1500 bytes, disable NDP, DHCPv6 and
970 DHCP support.
971 • pasta:-I,tap0,--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-
973 forward,10.0.2.3,--no-ndp,--no-dhcpv6,--no-dhcp, equivalent
974 to default slirp4netns(1) options with Podman overrides:
975 same as above, but leave the MTU to 65520 bytes
976 • pasta:-t,auto,-u,auto,-T,auto,-U,auto: enable automatic port
978 forwarding based on observed bound ports from both host and
979 container sides
980 • pasta:-T,5201: enable forwarding of TCP port 5201 from con‐
982 tainer to host, using the loopback interface instead of the
983 tap interface for improved performance
984 --no-cache
990 Do not use existing cached images for the container build. Build from
993 the start with a new set of cached layers.
994 --no-hostname
997 Do not create the /etc/hostname file in the container for RUN instruc‐
1000 tions.
1001 By default, Buildah manages the /etc/hostname file, adding the con‐
1004 tainer's own hostname. When the --no-hostname option is set, the im‐
1005 age's /etc/hostname will be preserved unmodified if it exists.
1006 --no-hosts
1009 Do not create the /etc/hosts file in the container for RUN instruc‐
1012 tions.
1013 By default, Buildah manages /etc/hosts, adding the container's own IP
1016 address. --no-hosts disables this, and the image's /etc/hosts will be
1017 preserved unmodified. Conflicts with the --add-host option.
1018 --omit-history bool-value
1021 Omit build history information in the built image. (default false).
1024 This option is useful for the cases where end users explicitly want to
1027 set --omit-history to omit the optional History from built images or
1028 when working with images built using build tools that do not include
1029 History information in their images.
1030 --os="OS"
1033 Set the OS of the image to be built, and that of the base image to be
1036 pulled, if the build uses one, instead of using the current operating
1037 system of the host.
1038 --os-feature feature
1041 Set the name of a required operating system feature for the image which
1044 will be built. By default, if the image is not based on scratch, the
1045 base image's required OS feature list is kept, if the base image speci‐
1046 fied any. This option is typically only meaningful when the image's OS
1047 is Windows.
1048 If feature has a trailing -, then the feature is removed from the set
1051 of required features which will be listed in the image.
1052 --os-version version
1055 Set the exact required operating system version for the image which
1058 will be built. By default, if the image is not based on scratch, the
1059 base image's required OS version is kept, if the base image specified
1060 one. This option is typically only meaningful when the image's OS is
1061 Windows, and is typically set in Windows base images, so using this op‐
1062 tion is usually unnecessary.
1063 --output, -o=""
1066 Output destination (format: type=local,dest=path)
1069 The --output (or -o) option extends the default behavior of building a
1072 container image by allowing users to export the contents of the image
1073 as files on the local filesystem, which can be useful for generating
1074 local binaries, code generation, etc.
1075 The value for --output is a comma-separated sequence of key=value
1078 pairs, defining the output type and options.
1079 Supported keys are: - dest: Destination path for exported output. Valid
1082 value is absolute or relative path, - means the standard output. -
1083 type: Defines the type of output to be used. Valid values is documented
1084 below.
1085 Valid type values are: - local: write the resulting build files to a
1088 directory on the client-side. - tar: write the resulting files as a
1089 single tarball (.tar).
1090 If no type is specified, the value defaults to local. Alternatively,
1093 instead of a comma-separated sequence, the value of --output can be
1094 just a destination (in the **dest** format) (e.g.--output some-
1095 path,--output -) where--output some-pathis treated as if **type=local**
1096 and--output -` is treated as if type=tar.
1097 --pid how
1100 Sets the configuration for PID namespaces when handling RUN instruc‐
1103 tions. The configured value can be "" (the empty string) or "private"
1104 to indicate that a new PID namespace should be created, or it can be
1105 "host" to indicate that the PID namespace in which buildah itself is
1106 being run should be reused, or it can be the path to a PID namespace
1107 which is already in use by another process.
1108 --platform="OS/ARCH[/VARIANT]"
1111 Set the OS/ARCH of the built image (and its base image, if your build
1114 uses one) to the provided value instead of using the current operating
1115 system and architecture of the host (for example linux/arm,
1116 linux/arm64, linux/amd64).
1117 The --platform flag can be specified more than once, or given a comma-
1120 separated list of values as its argument. When more than one platform
1121 is specified, the --manifest option should be used instead of the --tag
1122 option.
1123 OS/ARCH pairs are those used by the Go Programming Language. In sev‐
1126 eral cases the ARCH value for a platform differs from one produced by
1127 other tools such as the arch command. Valid OS and architecture name
1128 combinations are listed as values for $GOOS and $GOARCH at
1129 https://golang.org/doc/install/source#environment, and can also be
1130 found by running go tool dist list.
1131 The buildah build command allows building images for all Linux archi‐
1134 tectures, even non-native architectures. When building images for a
1135 different architecture, the RUN instructions require emulation soft‐
1136 ware installed on the host provided by packages like qemu-user-static.
1137 Note: it is always preferred to build images on the native architecture
1138 if possible.
1139 NOTE: The --platform option may not be used in combination with the
1142 --arch, --os, or --variant options.
1143 --pull
1146 When the flag is enabled or set explicitly to true (with --pull=true),
1149 attempt to pull the latest image from the registries listed in reg‐
1150 istries.conf if a local image does not exist or the image is newer than
1151 the one in storage. Raise an error if the image is not in any listed
1152 registry and is not present locally.
1153 If the flag is disabled (with --pull=false), do not pull the image from
1156 the registry, use only the local version. Raise an error if the image
1157 is not present locally.
1158 If the pull flag is set to always (with --pull=always), pull the image
1161 from the first registry it is found in as listed in registries.conf.
1162 Raise an error if not found in the registries, even if the image is
1163 present locally.
1164 If the pull flag is set to missing (with --pull=missing), pull the im‐
1167 age only if it could not be found in the local containers storage.
1168 Raise an error if no image could be found and the pull fails.
1169 If the pull flag is set to never (with --pull=never), Do not pull the
1172 image from the registry, use only the local version. Raise an error if
1173 the image is not present locally.
1174 Defaults to true.
1177 --quiet, -q
1180 Suppress output messages which indicate which instruction is being pro‐
1183 cessed, and of progress when pulling images from a registry, and when
1184 writing the output image.
1185 --retry attempts
1188 Number of times to retry in case of failure when performing push/pull
1191 of images to/from registry.
1192 Defaults to 3.
1195 --retry-delay duration
1198 Duration of delay between retry attempts in case of failure when per‐
1201 forming push/pull of images to/from registry.
1202 Defaults to 2s.
1205 --rm bool-value
1208 Remove intermediate containers after a successful build (default true).
1211 --runtime path
1214 The path to an alternate OCI-compatible runtime, which will be used to
1217 run commands specified by the RUN instruction. Default is runc, or crun
1218 when machine is configured to use cgroups V2.
1219 Note: You can also override the default runtime by setting the BUIL‐
1222 DAH_RUNTIME environment variable. export BUILDAH_RUNTIME=/usr/bin/crun
1223 --runtime-flag flag
1226 Adds global flags for the container rutime. To list the supported
1229 flags, please consult the manpages of the selected container runtime.
1230 Note: Do not pass the leading -- to the flag. To pass the runc flag
1233 --log-format json to buildah build, the option given would be --run‐
1234 time-flag log-format=json.
1235 --secret=id=id,src=path
1238 Pass secret information to be used in the Containerfile for building
1241 images in a safe way that will not end up stored in the final image, or
1242 be seen in other stages. The secret will be mounted in the container
1243 at the default location of /run/secrets/id.
1244 To later use the secret, use the --mount flag in a RUN instruction
1247 within a Containerfile:
1248 RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret
1251 Note: Changing the contents of secret files will not trigger a rebuild
1254 of layers that use said secrets.
1255 --security-opt=[]
1258 Security Options
1261 "apparmor=unconfined" : Turn off apparmor confinement for the container
1264 "apparmor=your-profile" : Set the apparmor confinement profile for
1265 the container
1266 "label=user:USER" : Set the label user for the container
1269 "label=role:ROLE" : Set the label role for the container
1270 "label=type:TYPE" : Set the label type for the container
1271 "label=level:LEVEL" : Set the label level for the container
1272 "label=disable" : Turn off label confinement for the container
1273 "no-new-privileges" : Disable container processes from gaining addi‐
1274 tional privileges
1275 "seccomp=unconfined" : Turn off seccomp confinement for the container
1278 "seccomp=profile.json : White listed syscalls seccomp Json file to
1279 be used as a seccomp filter
1280 --shm-size=""
1283 Size of /dev/shm. The format is <number><unit>. number must be greater
1286 than 0. Unit is optional and can be b (bytes), k (kilobytes),
1287 m(megabytes), or g (gigabytes). If you omit the unit, the system uses
1288 bytes. If you omit the size entirely, the system uses 64m.
1289 --sign-by fingerprint
1292 Sign the built image using the GPG key that matches the specified fin‐
1295 gerprint.
1296 --skip-unused-stages bool-value
1299 Skip stages in multi-stage builds which don't affect the target stage.
1302 (Default is true).
1303 --squash
1306 Squash all layers, including those from base image(s), into one single
1309 layer. (Default is false).
1310 By default, Buildah preserves existing base-image layers and adds only
1313 one new layer on a build. The --layers option can be used to preserve
1314 intermediate build layers.
1315 --ssh=default|id[=socket>|[,]
1318 SSH agent socket or keys to expose to the build. The socket path can
1321 be left empty to use the value of default=$SSH_AUTH_SOCK
1322 To later use the ssh agent, use the --mount flag in a RUN instruction
1325 within a Containerfile:
1326 RUN --mount=type=secret,id=id mycmd
1329 --stdin
1332 Pass stdin into the RUN containers. Sometimes commands being RUN within
1335 a Containerfile want to request information from the user. For example
1336 apt asking for a confirmation for install. Use --stdin to be able to
1337 interact from the terminal during the build.
1338 --tag, -t imageName
1341 Specifies the name which will be assigned to the resulting image if the
1344 build process completes successfully. If imageName does not include a
1345 registry name component, the registry name localhost will be prepended
1346 to the image name.
1347 --target stageName
1350 Set the target build stage to build. When building a Containerfile
1353 with multiple build stages, --target can be used to specify an interme‐
1354 diate build stage by name as the final stage for the resulting image.
1355 Commands after the target stage will be skipped.
1356 --timestamp seconds
1359 Set the create timestamp to seconds since epoch to allow for determin‐
1362 istic builds (defaults to current time). By default, the created time‐
1363 stamp is changed and written into the image manifest with every commit,
1364 causing the image's sha256 hash to be different even if the sources are
1365 exactly the same otherwise. When --timestamp is set, the created time‐
1366 stamp is always set to the time specified and therefore not changed,
1367 allowing the image's sha256 to remain the same. All files committed to
1368 the layers of the image will be created with the timestamp.
1369 --tls-verify bool-value
1372 Require HTTPS and verification of certificates when talking to con‐
1375 tainer registries (defaults to true). TLS verification cannot be used
1376 when talking to an insecure registry.
1377 --ulimit type=soft-limit[:hard-limit]
1380 Specifies resource limits to apply to processes launched when process‐
1383 ing RUN instructions. This option can be specified multiple times.
1384 Recognized resource types include:
1385 "core": maximum core dump size (ulimit -c)
1386 "cpu": maximum CPU time (ulimit -t)
1387 "data": maximum size of a process's data segment (ulimit -d)
1388 "fsize": maximum size of new files (ulimit -f)
1389 "locks": maximum number of file locks (ulimit -x)
1390 "memlock": maximum amount of locked memory (ulimit -l)
1391 "msgqueue": maximum amount of data in message queues (ulimit -q)
1392 "nice": niceness adjustment (nice -n, ulimit -e)
1393 "nofile": maximum number of open files (ulimit -n)
1394 "nofile": maximum number of open files (1048576); when run by root
1395 "nproc": maximum number of processes (ulimit -u)
1396 "nproc": maximum number of processes (1048576); when run by root
1397 "rss": maximum size of a process's (ulimit -m)
1398 "rtprio": maximum real-time scheduling priority (ulimit -r)
1399 "rttime": maximum amount of real-time execution between blocking
1400 syscalls
1401 "sigpending": maximum number of pending signals (ulimit -i)
1402 "stack": maximum stack size (ulimit -s)
1403 --unsetenv env
1406 Unset environment variables from the final image.
1409 --unsetlabel label
1412 Unset the image label, causing the label not to be inherited from the
1415 base image.
1416 --userns how
1419 Sets the configuration for user namespaces when handling RUN instruc‐
1422 tions. The configured value can be "" (the empty string) , "private"
1423 or "auto" to indicate that a new user namespace should be created, it
1424 can be "host" to indicate that the user namespace in which buildah it‐
1425 self is being run should be reused, or it can be the path to an user
1426 namespace which is already in use by another process.
1427 auto: automatically create a unique user namespace.
1430 The --userns=auto flag, requires that the user name containers and a
1433 range of subordinate user ids that the build container is allowed to
1434 use be specified in the /etc/subuid and /etc/subgid files.
1435 Example: containers:2147483647:2147483648.
1438 Buildah allocates unique ranges of UIDs and GIDs from the containers
1441 subordinate user ids. The size of the ranges is based on the number of
1442 UIDs required in the image. The number of UIDs and GIDs can be overrid‐
1443 den with the size option.
1444 Valid auto options:
1447 • gidmapping=CONTAINER_GID:HOST_GID:SIZE: to force a GID mapping
1450 to be present in the user namespace.
1451 • size=SIZE: to specify an explicit size for the automatic user
1453 namespace. e.g. --userns=auto:size=8192. If size is not speci‐
1454 fied, auto will estimate a size for the user namespace.
1455 • uidmapping=CONTAINER_UID:HOST_UID:SIZE: to force a UID mapping
1457 to be present in the user namespace.
1458 --userns-gid-map mapping
1462 Directly specifies a GID mapping which should be used to set ownership,
1465 at the filesystem level, on the working container's contents. Commands
1466 run when handling RUN instructions will default to being run in their
1467 own user namespaces, configured using the UID and GID maps.
1468 Entries in this map take the form of one or more colon-separated
1471 triples of a starting in-container GID, a corresponding starting host-
1472 level GID, and the number of consecutive IDs which the map entry repre‐
1473 sents.
1474 This option overrides the remap-gids setting in the options section of
1477 /etc/containers/storage.conf.
1478 If this option is not specified, but a global --userns-gid-map setting
1481 is supplied, settings from the global option will be used.
1482 --userns-gid-map-group group
1485 Specifies that a GID mapping which should be used to set ownership, at
1488 the filesystem level, on the working container's contents, can be found
1489 in entries in the /etc/subgid file which correspond to the specified
1490 group. Commands run when handling RUN instructions will default to be‐
1491 ing run in their own user namespaces, configured using the UID and GID
1492 maps. If --userns-uid-map-user is specified, but --userns-gid-map-
1493 group is not specified, buildah will assume that the specified user
1494 name is also a suitable group name to use as the default setting for
1495 this option.
1496 Users can specify the maps directly using --userns-gid-map described in
1499 the buildah(1) man page.
1500 NOTE: When this option is specified by a rootless user, the specified
1503 mappings are relative to the rootless usernamespace in the container,
1504 rather than being relative to the host as it would be when run rootful.
1505 --userns-uid-map mapping
1508 Directly specifies a UID mapping which should be used to set ownership,
1511 at the filesystem level, on the working container's contents. Commands
1512 run when handling RUN instructions will default to being run in their
1513 own user namespaces, configured using the UID and GID maps.
1514 Entries in this map take the form of one or more colon-separated
1517 triples of a starting in-container UID, a corresponding starting host-
1518 level UID, and the number of consecutive IDs which the map entry repre‐
1519 sents.
1520 This option overrides the remap-uids setting in the options section of
1523 /etc/containers/storage.conf.
1524 If this option is not specified, but a global --userns-uid-map setting
1527 is supplied, settings from the global option will be used.
1528 --userns-uid-map-user user
1531 Specifies that a UID mapping which should be used to set ownership, at
1534 the filesystem level, on the working container's contents, can be found
1535 in entries in the /etc/subuid file which correspond to the specified
1536 user. Commands run when handling RUN instructions will default to be‐
1537 ing run in their own user namespaces, configured using the UID and GID
1538 maps. If --userns-gid-map-group is specified, but --userns-uid-map-
1539 user is not specified, buildah will assume that the specified group
1540 name is also a suitable user name to use as the default setting for
1541 this option.
1542 NOTE: When this option is specified by a rootless user, the specified
1545 mappings are relative to the rootless usernamespace in the container,
1546 rather than being relative to the host as it would be when run rootful.
1547 --uts how
1550 Sets the configuration for UTS namespaces when handling RUN instruc‐
1553 tions. The configured value can be "" (the empty string) or "con‐
1554 tainer" to indicate that a new UTS namespace should be created, or it
1555 can be "host" to indicate that the UTS namespace in which buildah it‐
1556 self is being run should be reused, or it can be the path to a UTS
1557 namespace which is already in use by another process.
1558 --variant=""
1561 Set the architecture variant of the image to be pulled.
1564 --volume, -v[=[HOST-DIR:CONTAINER-DIR[:OPTIONS]]]
1567 Mount a host directory into containers when executing RUN instructions
1570 during the build. The OPTIONS are a comma delimited list and can be:
1571 [1] ⟨#Footnote1⟩
1572 • [rw|ro]
1575 • [U]
1577 • [z|Z|O]
1579 • [[r]shared|[r]slave|[r]private]
1581 The CONTAINER-DIR must be an absolute path such as /src/docs. The HOST-
1585 DIR must be an absolute path as well. Buildah bind-mounts the HOST-DIR
1586 to the path you specify. For example, if you supply /foo as the host
1587 path, Buildah copies the contents of /foo to the container filesystem
1588 on the host and bind mounts that into the container.
1589 You can specify multiple -v options to mount one or more mounts to a
1592 container.
1593 Write Protected Volume Mounts
1596 You can add the :ro or :rw suffix to a volume to mount it read-only or
1599 read-write mode, respectively. By default, the volumes are mounted
1600 read-write. See examples.
1601 Chowning Volume Mounts
1604 By default, Buildah does not change the owner and group of source vol‐
1607 ume directories mounted into containers. If a container is created in a
1608 new user namespace, the UID and GID in the container may correspond to
1609 another UID and GID on the host.
1610 The :U suffix tells Buildah to use the correct host UID and GID based
1613 on the UID and GID within the container, to change the owner and group
1614 of the source volume.
1615 Labeling Volume Mounts
1618 Labeling systems like SELinux require that proper labels are placed on
1621 volume content mounted into a container. Without a label, the security
1622 system might prevent the processes running inside the container from
1623 using the content. By default, Buildah does not change the labels set
1624 by the OS.
1625 To change a label in the container context, you can add either of two
1628 suffixes :z or :Z to the volume mount. These suffixes tell Buildah to
1629 relabel file objects on the shared volumes. The z option tells Buildah
1630 that two containers share the volume content. As a result, Buildah la‐
1631 bels the content with a shared content label. Shared volume labels al‐
1632 low all containers to read/write content. The Z option tells Buildah
1633 to label the content with a private unshared label. Only the current
1634 container can use a private volume.
1635 Overlay Volume Mounts
1638 The :O flag tells Buildah to mount the directory from the host as a
1641 temporary storage using the Overlay file system. The RUN command con‐
1642 tainers are allowed to modify contents within the mountpoint and are
1643 stored in the container storage in a separate directory. In Overlay FS
1644 terms the source directory will be the lower, and the container storage
1645 directory will be the upper. Modifications to the mount point are de‐
1646 stroyed when the RUN command finishes executing, similar to a tmpfs
1647 mount point.
1648 Any subsequent execution of RUN commands sees the original source di‐
1651 rectory content, any changes from previous RUN commands no longer ex‐
1652 ist.
1653 One use case of the overlay mount is sharing the package cache from the
1656 host into the container to allow speeding up builds.
1657 Note:
1660 - 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.
1663 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.
1664 - 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.
1665 By default bind mounted volumes are private. That means any mounts done
1669 inside container will not be visible on the host and vice versa. This
1670 behavior can be changed by specifying a volume mount propagation prop‐
1671 erty.
1672 When the mount propagation policy is set to shared, any mounts com‐
1675 pleted inside the container on that volume will be visible to both the
1676 host and container. When the mount propagation policy is set to slave,
1677 one way mount propagation is enabled and any mounts completed on the
1678 host for that volume will be visible only inside of the container. To
1679 control the mount propagation property of the volume use the
1680 :[r]shared, :[r]slave or :[r]private propagation flag. The propagation
1681 property can be specified only for bind mounted volumes and not for in‐
1682 ternal volumes or named volumes. For mount propagation to work on the
1683 source mount point (the mount point where source dir is mounted on) it
1684 has to have the right propagation properties. For shared volumes, the
1685 source mount point has to be shared. And for slave volumes, the source
1686 mount has to be either shared or slave. [1] ⟨#Footnote1⟩
1687 Use df <source-dir> to determine the source mount and then use findmnt
1690 -o TARGET,PROPAGATION <source-mount-dir> to determine propagation prop‐
1691 erties of source mount, if findmnt utility is not available, the source
1692 mount point can be determined by looking at the mount entry in
1693 /proc/self/mountinfo. Look at optional fields and see if any propaga‐
1694 tion properties are specified. shared:X means the mount is shared,
1695 master:X means the mount is slave and if nothing is there that means
1696 the mount is private. [1] ⟨#Footnote1⟩
1697 To change propagation properties of a mount point use the mount com‐
1700 mand. For example, to bind mount the source directory /foo do mount
1701 --bind /foo /foo and mount --make-private --make-shared /foo. This will
1702 convert /foo into a shared mount point. The propagation properties of
1703 the source mount can be changed directly. For instance if / is the
1704 source mount for /foo, then use mount --make-shared / to convert / into
1705 a shared mount.
1706
1709 The ENV instruction in a Containerfile can be used to define variable
1710 values. When the image is built, the values will persist in the con‐
1711 tainer image. At times it is more convenient to change the values in
1712 the Containerfile via a command-line option rather than changing the
1713 values within the Containerfile itself.
1714 The following variables can be used in conjunction with the --build-arg
1717 option to override the corresponding values set in the Containerfile
1718 using the ENV instruction.
1719 • HTTP_PROXY
1722 • HTTPS_PROXY
1724 • FTP_PROXY
1726 • NO_PROXY
1728 Please refer to the Using Build Time Variables ⟨#using-build-time-vari‐
1732 ables⟩ section of the Examples.
1733
1736 Build an image using local Containerfiles
1737 buildah build .
1738 buildah build -f Containerfile .
1741 cat ~/Containerfile | buildah build -f - .
1744 buildah build -f Containerfile.simple -f Containerfile.notsosimple .
1747 buildah build --timestamp=$(date '+%s') -t imageName .
1750 buildah build -t imageName .
1753 buildah build --tls-verify=true -t imageName -f Containerfile.simple .
1756 buildah build --tls-verify=false -t imageName .
1759 buildah build --runtime-flag log-format=json .
1762 buildah build -f Containerfile --runtime-flag debug .
1765 buildah build --authfile /tmp/auths/myauths.json --cert-dir ~/auth
1768 --tls-verify=true --creds=username:password -t imageName -f Container‐
1769 file.simple .
1770 buildah build --memory 40m --cpu-period 10000 --cpu-quota 50000
1773 --ulimit nofile=1024:1028 -t imageName .
1774 buildah build --security-opt label=level:s0:c100,c200 --cgroup-parent
1777 /path/to/cgroup/parent -t imageName .
1778 buildah build --arch=arm --variant v7 -t imageName .
1781 buildah build --volume /home/test:/myvol:ro,Z -t imageName .
1784 buildah build -v /home/test:/myvol:z,U -t imageName .
1787 buildah build -v /var/lib/dnf:/var/lib/dnf:O -t imageName .
1790 buildah build --layers -t imageName .
1793 buildah build --no-cache -t imageName .
1796 buildah build -f Containerfile --layers --force-rm -t imageName .
1799 buildah build --no-cache --rm=false -t imageName .
1802 buildah build --dns-search=example.com --dns=223.5.5.5 --dns-op‐
1805 tion=use-vc .
1806 buildah build -f Containerfile.in --cpp-flag="-DDEBUG" -t imageName .
1809 buildah build --network mynet .
1812 buildah build --env LANG=en_US.UTF-8 -t imageName .
1815 buildah build --env EDITOR -t imageName .
1818 buildah build --unsetenv LANG -t imageName .
1821 buildah build --os-version 10.0.19042.1645 -t imageName .
1824 buildah build --os-feature win32k -t imageName .
1827 buildah build --os-feature win32k- -t imageName .
1830 Building an multi-architecture image using the --manifest option (requires
1833 emulation software)
1834 buildah build --arch arm --manifest myimage /tmp/mysrc
1835 buildah build --arch amd64 --manifest myimage /tmp/mysrc
1838 buildah build --arch s390x --manifest myimage /tmp/mysrc
1841 buildah bud --platform linux/s390x,linux/ppc64le,linux/amd64 --manifest
1844 myimage /tmp/mysrc
1845 buildah build --platform linux/arm64 --platform linux/amd64 --manifest
1848 myimage /tmp/mysrc
1849 buildah bud --all-platforms --manifest myimage /tmp/mysrc
1852 Building an image using (--output) custom build output
1855 buildah build -o out .
1856 buildah build --output type=local,dest=out .
1859 buildah build --output type=tar,dest=out.tar .
1862 buildah build -o - . > out.tar
1865 Building an image using a URL
1868 This will clone the specified GitHub repository from the URL and use it
1869 as context. The Containerfile or Dockerfile at the root of the reposi‐
1870 tory is used as the context of the build. This only works if the GitHub
1871 repository is a dedicated repository.
1872 buildah build https://github.com/containers/PodmanHello.git
1875 Note: Github does not support using git:// for performing clone opera‐
1878 tion due to recent changes in their security guidance
1879 (https://github.blog/2021-09-01-improving-git-protocol-security-
1880 github/). Use an https:// URL if the source repository is hosted on
1881 Github.
1882 Building an image using a URL to a tarball'ed context
1885 Buildah will fetch the tarball archive, decompress it and use its con‐
1886 tents as the build context. The Containerfile or Dockerfile at the
1887 root of the archive and the rest of the archive will get used as the
1888 context of the build. If you pass an -f PATH/Containerfile option as
1889 well, the system will look for that file inside the contents of the
1890 tarball.
1891 buildah build -f dev/Containerfile https://10.10.10.1/buildah/con‐
1894 text.tar.gz
1895 Note: supported compression formats are 'xz', 'bzip2', 'gzip' and
1898 'identity' (no compression).
1899 Using Build Time Variables
1902 Replace the value set for the HTTP_PROXY environment variable within the
1903 Containerfile.
1904 buildah build --build-arg=HTTP_PROXY="http://127.0.0.1:8321"
1905
1908 BUILD_REGISTRY_SOURCES
1909 BUILD_REGISTRY_SOURCES, if set, is treated as a JSON object which con‐
1912 tains lists of registry names under the keys insecureRegistries,
1913 blockedRegistries, and allowedRegistries.
1914 When pulling an image from a registry, if the name of the registry
1917 matches any of the items in the blockedRegistries list, the image pull
1918 attempt is denied. If there are registries in the allowedRegistries
1919 list, and the registry's name is not in the list, the pull attempt is
1920 denied.
1921 TMPDIR The TMPDIR environment variable allows the user to specify where
1924 temporary files are stored while pulling and pushing images. Defaults
1925 to '/var/tmp'.
1926
1929 .containerignore/.dockerignore
1930 If the .containerignore/.dockerignore file exists in the context direc‐
1931 tory, buildah build reads its contents. If both exist, then .container‐
1932 ignore is used. Use the --ignorefile flag to override the ignore file
1933 path location. Buildah uses the content to exclude files and directo‐
1934 ries from the context directory, when executing COPY and ADD directives
1935 in the Containerfile/Dockerfile
1936 Users can specify a series of Unix shell globals in a
1939 Buildah supports a special wildcard string ** which matches any number
1942 of directories (including zero). For example, */.go will exclude all
1943 files that end with .go that are found in all directories.
1944 Example .containerignore file:
1947 # exclude this content for image
1950 */*.c
1951 **/output*
1952 src
1953 */*.c Excludes files and directories whose names end with .c in any top
1957 level subdirectory. For example, the source file include/rootless.c.
1958 **/output* Excludes files and directories starting with output from any
1961 directory.
1962 src Excludes files named src and the directory src as well as any con‐
1965 tent in it.
1966 Lines starting with ! (exclamation mark) can be used to make exceptions
1969 to exclusions. The following is an example .containerignore/.dockerig‐
1970 nore file that uses this mechanism:
1971 *.doc
1974 !Help.doc
1975 Exclude all doc files except Help.doc from the image.
1979 This functionality is compatible with the handling of .containerignore
1982 files described here:
1983 https://github.com/containers/buildah/blob/main/docs/containerig‐
1986 nore.5.md
1987 registries.conf (/etc/containers/registries.conf)
1990 registries.conf is the configuration file which specifies which con‐
1993 tainer registries should be consulted when completing image names which
1994 do not include a registry or domain portion.
1995 policy.json (/etc/containers/policy.json)
1998 Signature policy file. This defines the trust policy for container im‐
2001 ages. Controls which container registries can be used for image, and
2002 whether or not the tool should trust the images.
2003
2006 buildah(1), cpp(1), buildah-login(1), docker-login(1), namespaces(7),
2007 pid_namespaces(7), containers-policy.json(5), containers-reg‐
2008 istries.conf(5), user_namespaces(7), crun(1), runc(8), contain‐
2009 ers.conf(5), oci-hooks(5)
2010
2013 1: The Buildah project is committed to inclusivity, a core value of
2014 open source. The master and slave mount propagation terminology used
2015 here is problematic and divisive, and should be changed. However, these
2016 terms are currently used within the Linux kernel and must be used as-is
2017 at this time. When the kernel maintainers rectify this usage, Buildah
2018 will follow suit immediately.
2019buildah April 2017 buildah-build(1)