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 buildah build-using-dockerfile [options] [context]
17 build has aliases bud and build-using-dockerfile.
20
23 Builds an image using instructions from one or more Containerfiles or
24 Dockerfiles and a specified build context directory. A Containerfile
25 uses the same syntax as a Dockerfile internally. For this document, a
26 file referred to as a Containerfile can be a file named either 'Con‐
27 tainerfile' or 'Dockerfile'.
28 The build context directory can be specified as the http(s) URL of an
31 archive, git repository or Containerfile.
32 If no context directory is specified, then Buildah will assume the cur‐
35 rent working directory as build context, which should contain a Con‐
36 tainerfile.
37 Containerfiles ending with a ".in" suffix will be preprocessed via
40 cpp(1). This can be useful to decompose Containerfiles into several
41 reusable parts that can be used via CPP's #include directive. Notice,
42 a Containerfile.in file can still be used by other tools when manually
43 preprocessing them via cpp -E. Any comments ( Lines beginning with # )
44 in included Containerfile(s) that are not preprocess commands, will be
45 printed as warnings during builds.
46 When the URL is an archive, the contents of the URL is downloaded to a
49 temporary location and extracted before execution.
50 When the URL is a Containerfile, the file is downloaded to a temporary
53 location.
54 When a Git repository is set as the URL, the repository is cloned lo‐
57 cally and then set as the context.
58
61 --add-host=[]
62 Add a custom host-to-IP mapping (host:ip)
65 Add a line to /etc/hosts. The format is hostname:ip. The --add-host op‐
68 tion can be set multiple times.
69 --annotation annotation
72 Add an image annotation (e.g. annotation=value) to the image metadata.
75 Can be used multiple times.
76 Note: this information is not present in Docker image formats, so it is
79 discarded when writing images in Docker formats.
80 --arch="ARCH"
83 Set the ARCH of the image to be built, and that of the base image to be
86 pulled, if the build uses one, to the provided value instead of using
87 the architecture of the host. (Examples: arm, arm64, 386, amd64,
88 ppc64le, s390x)
89 --authfile path
92 Path of the authentication file. Default is ${XDG_\RUNTIME_DIR}/con‐
95 tainers/auth.json. If XDG_RUNTIME_DIR is not set, the default is
96 /run/containers/$UID/auth.json. This file is created using using buil‐
97 dah login.
98 If the authorization state is not found there, $HOME/.docker/con‐
101 fig.json is checked, which is set using docker login.
102 Note: You can also override the default path of the authentication file
105 by setting the REGISTRY_AUTH_FILE environment variable. export REG‐
106 ISTRY_AUTH_FILE=path
107 --build-arg arg=value
110 Specifies a build argument and its value, which will be interpolated in
113 instructions read from the Containerfiles in the same way that environ‐
114 ment variables are, but which will not be added to environment variable
115 list in the resulting image's configuration.
116 Please refer to the BUILD TIME VARIABLES ⟨#build-time-variables⟩ sec‐
119 tion for the list of variables that can be overridden within the Con‐
120 tainerfile at run time.
121 --cache-from
124 Images to utilise as potential cache sources. Buildah does not cur‐
127 rently support --cache-from so this is a NOOP.
128 --cap-add=CAP_xxx
131 When executing RUN instructions, run the command specified in the in‐
134 struction with the specified capability added to its capability set.
135 Certain capabilities are granted by default; this option can be used to
136 add more.
137 --cap-drop=CAP_xxx
140 When executing RUN instructions, run the command specified in the in‐
143 struction with the specified capability removed from its capability
144 set. The CAP_AUDIT_WRITE, CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_FOWNER,
145 CAP_FSETID, CAP_KILL, CAP_MKNOD, CAP_NET_BIND_SERVICE, CAP_SETFCAP,
146 CAP_SETGID, CAP_SETPCAP, CAP_SETUID, and CAP_SYS_CHROOT capabilities
147 are granted by default; this option can be used to remove them.
148 If a capability is specified to both the --cap-add and --cap-drop op‐
151 tions, it will be dropped, regardless of the order in which the options
152 were given.
153 --cert-dir path
156 Use certificates at path (*.crt, *.cert, *.key) to connect to the reg‐
159 istry. The default certificates directory is /etc/containers/certs.d.
160 --cgroup-parent=""
163 Path to cgroups under which the cgroup for the container will be cre‐
166 ated. If the path is not absolute, the path is considered to be rela‐
167 tive to the cgroups path of the init process. Cgroups will be created
168 if they do not already exist.
169 --compress
172 This option is added to be aligned with other containers CLIs. Buildah
175 doesn't send a copy of the context directory to a daemon or a remote
176 server. Thus, compressing the data before sending it is irrelevant to
177 Buildah.
178 --cni-config-dir=directory
181 Location of CNI configuration files which will dictate which plugins
184 will be used to configure network interfaces and routing for containers
185 created for handling RUN instructions, if those containers will be run
186 in their own network namespaces, and networking is not disabled.
187 --cni-plugin-path=directory[:directory[:directory[...]]]
190 List of directories in which the CNI plugins which will be used for
193 configuring network namespaces can be found.
194 --cpu-period=0
197 Set the CPU period for the Completely Fair Scheduler (CFS), which is a
200 duration in microseconds. Once the container's CPU quota is used up, it
201 will not be scheduled to run until the current period ends. Defaults to
202 100000 microseconds.
203 On some systems, changing the CPU limits may not be allowed for non-
206 root users. For more details, see https://github.com/containers/pod‐
207 man/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-
208 fails-with-a-permissions-error
209 --cpu-quota=0
212 Limit the CPU CFS (Completely Fair Scheduler) quota
215 Limit the container's CPU usage. By default, containers run with the
218 full CPU resource. This flag tell the kernel to restrict the con‐
219 tainer's CPU usage to the quota you specify.
220 On some systems, changing the CPU limits may not be allowed for non-
223 root users. For more details, see https://github.com/containers/pod‐
224 man/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-
225 fails-with-a-permissions-error
226 --cpu-shares, -c=0
229 CPU shares (relative weight)
232 By default, all containers get the same proportion of CPU cycles. This
235 proportion can be modified by changing the container's CPU share
236 weighting relative to the weighting of all other running containers.
237 To modify the proportion from the default of 1024, use the --cpu-shares
240 flag to set the weighting to 2 or higher.
241 The proportion will only apply when CPU-intensive processes are run‐
244 ning. When tasks in one container are idle, other containers can use
245 the left-over CPU time. The actual amount of CPU time will vary depend‐
246 ing on the number of containers running on the system.
247 For example, consider three containers, one has a cpu-share of 1024 and
250 two others have a cpu-share setting of 512. When processes in all three
251 containers attempt to use 100% of CPU, the first container would re‐
252 ceive 50% of the total CPU time. If you add a fourth container with a
253 cpu-share of 1024, the first container only gets 33% of the CPU. The
254 remaining containers receive 16.5%, 16.5% and 33% of the CPU.
255 On a multi-core system, the shares of CPU time are distributed over all
258 CPU cores. Even if a container is limited to less than 100% of CPU
259 time, it can use 100% of each individual CPU core.
260 For example, consider a system with more than three cores. If you start
263 one container {C0} with -c=512 running one process, and another con‐
264 tainer {C1} with -c=1024 running two processes, this can result in the
265 following division of CPU shares:
266 PID container CPU CPU share
269 100 {C0} 0 100% of CPU0
270 101 {C1} 1 100% of CPU1
271 102 {C1} 2 100% of CPU2
272 --cpuset-cpus=""
276 CPUs in which to allow execution (0-3, 0,1)
279 --cpuset-mems=""
282 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effec‐
285 tive on NUMA systems.
286 If you have four memory nodes on your system (0-3), use --cpuset-
289 mems=0,1 then processes in your container will only use memory from the
290 first two memory nodes.
291 --creds creds
294 The [username[:password]] to use to authenticate with the registry if
297 required. If one or both values are not supplied, a command line
298 prompt will appear and the value can be entered. The password is en‐
299 tered without echo.
300 --decryption-key key[:passphrase]
303 The [key[:passphrase]] to be used for decryption of images. Key can
306 point to keys and/or certificates. Decryption will be tried with all
307 keys. If the key is protected by a passphrase, it is required to be
308 passed in the argument and omitted otherwise.
309 --device=device
312 Add a host device to the container. Optional permissions parameter can
315 be used to specify device permissions, it is combination of r for read,
316 w for write, and m for mknod(2).
317 Example: --device=/dev/sdc:/dev/xvdc:rwm.
320 Note: if _hostdevice is a symbolic link then it will be resolved first.
323 The container will only store the major and minor numbers of the host
324 device.
325 Note: if the user only has access rights via a group, accessing the de‐
328 vice from inside a rootless container will fail. The crun(1) runtime
329 offers a workaround for this by adding the option --annotation
330 run.oci.keep_original_groups=1.
331 --disable-compression, -D
334 Don't compress filesystem layers when building the image unless it is
337 required by the location where the image is being written. This is the
338 default setting, because image layers are compressed automatically when
339 they are pushed to registries, and images being written to local stor‐
340 age would only need to be decompressed again to be stored. Compression
341 can be forced in all cases by specifying --disable-compression=false.
342 --disable-content-trust
345 This is a Docker specific option to disable image verification to a
348 Docker registry and is not supported by Buildah. This flag is a NOOP
349 and provided solely for scripting compatibility.
350 --dns=[]
353 Set custom DNS servers
356 This option can be used to override the DNS configuration passed to the
359 container. Typically this is necessary when the host DNS configuration
360 is invalid for the container (e.g., 127.0.0.1). When this is the case
361 the --dns flag is necessary for every run.
362 The special value none can be specified to disable creation of /etc/re‐
365 solv.conf in the container by Buildah. The /etc/resolv.conf file in the
366 image will be used without changes.
367 --dns-option=[]
370 Set custom DNS options
373 --dns-search=[]
376 Set custom DNS search domains
379 --file, -f Containerfile
382 Specifies a Containerfile which contains instructions for building the
385 image, either a local file or an http or https URL. If more than one
386 Containerfile is specified, FROM instructions will only be accepted
387 from the first specified file.
388 If a local file is specified as the Containerfile and it does not ex‐
391 ist, the context directory will be prepended to the local file value.
392 If you specify -f -, the Containerfile contents will be read from
395 stdin.
396 --force-rm bool-value
399 Always remove intermediate containers after a build, even if the build
402 fails (default false).
403 --format
406 Control the format for the built image's manifest and configuration
409 data. Recognized formats include oci (OCI image-spec v1.0, the de‐
410 fault) and docker (version 2, using schema format 2 for the manifest).
411 Note: You can also override the default format by setting the BUIL‐
414 DAH_FORMAT environment variable. export BUILDAH_FORMAT=docker
415 --from
418 Overrides the first FROM instruction within the Containerfile. If
421 there are multiple FROM instructions in a Containerfile, only the first
422 is changed.
423 -h, --help
426 Print usage statement
429 --http-proxy=true
432 By default proxy environment variables are passed into the container if
435 set for the buildah process. This can be disabled by setting the
436 --http-proxy option to false. The environment variables passed in in‐
437 clude http_proxy, https_proxy, ftp_proxy, no_proxy, and also the upper
438 case versions of those.
439 --iidfile ImageIDfile
442 Write the built image's ID to the file. When --platform is specified
445 more than once, attempting to use this option will trigger an error.
446 --ignorefile file
449 Path to an alternative .containerignore (.dockerignore) file.
452 --ipc how
455 Sets the configuration for IPC namespaces when handling RUN instruc‐
458 tions. The configured value can be "" (the empty string) or "con‐
459 tainer" to indicate that a new IPC namespace should be created, or it
460 can be "host" to indicate that the IPC namespace in which buildah it‐
461 self is being run should be reused, or it can be the path to an IPC
462 namespace which is already in use by another process.
463 --isolation type
466 Controls what type of isolation is used for running processes as part
469 of RUN instructions. Recognized types include oci (OCI-compatible run‐
470 time, the default), rootless (OCI-compatible runtime invoked using a
471 modified configuration, with --no-new-keyring added to its create invo‐
472 cation, reusing the host's network and UTS namespaces, and creating
473 private IPC, PID, mount, and user namespaces; the default for unprivi‐
474 leged users), and chroot (an internal wrapper that leans more toward
475 chroot(1) than container technology, reusing the host's control group,
476 network, IPC, and PID namespaces, and creating private mount and UTS
477 namespaces, and creating user namespaces only when they're required for
478 ID mapping).
479 Note: You can also override the default isolation type by setting the
482 BUILDAH_ISOLATION environment variable. export BUILDAH_ISOLATION=oci
483 --jobs N
486 Run up to N concurrent stages in parallel. If the number of jobs is
489 greater than 1, stdin will be read from /dev/null. If 0 is specified,
490 then there is no limit on the number of jobs that run in parallel.
491 --label label
494 Add an image label (e.g. label=value) to the image metadata. Can be
497 used multiple times.
498 Users can set a special LABEL io.containers.capabilities=CAP1,CAP2,CAP3
501 in a Containerfile that specified the list of Linux capabilities re‐
502 quired for the container to run properly. This label specified in a
503 container image tells container engines, like Podman, to run the con‐
504 tainer with just these capabilities. The container engine launches the
505 container with just the specified capabilities, as long as this list of
506 capabilities is a subset of the default list.
507 If the specified capabilities are not in the default set, container en‐
510 gines should print an error message and will run the container with the
511 default capabilities.
512 --layers bool-value
515 Cache intermediate images during the build process (Default is false).
518 Note: You can also override the default value of layers by setting the
521 BUILDAH_LAYERS environment variable. export BUILDAH_LAYERS=true
522 --logfile filename
525 Log output which would be sent to standard output and standard error to
528 the specified file instead of to standard output and standard error.
529 --manifest "listName"
532 Name of the manifest list to which the built image will be added. Cre‐
535 ates the manifest list if it does not exist. This option is useful for
536 building multi architecture images.
537 --memory, -m=""
540 Memory limit (format: [], where unit = b, k, m or g)
543 Allows you to constrain the memory available to a container. If the
546 host supports swap memory, then the -m memory setting can be larger
547 than physical RAM. If a limit of 0 is specified (not using -m), the
548 container's memory is not limited. The actual limit may be rounded up
549 to a multiple of the operating system's page size (the value would be
550 very large, that's millions of trillions).
551 --memory-swap="LIMIT"
554 A limit value equal to memory plus swap. Must be used with the -m
557 (--memory) flag. The swap LIMIT should always be larger than -m (--mem‐
558 ory) value. By default, the swap LIMIT will be set to double the value
559 of --memory.
560 The format of LIMIT is <number>[<unit>]. Unit can be b (bytes), k
563 (kilobytes), m (megabytes), or g (gigabytes). If you don't specify a
564 unit, b is used. Set LIMIT to -1 to enable unlimited swap.
565 --network, --net=mode
568 Sets the configuration for network namespaces when handling RUN in‐
571 structions.
572 Valid mode values are:
575 • none: no networking;
578 • host: use the host network stack. Note: the host mode gives
580 the container full access to local system services such as D-
581 bus and is therefore considered insecure;
582 • ns:path: path to a network namespace to join;
584 • private: create a new namespace for the container (default)
586 --no-cache
590 Do not use existing cached images for the container build. Build from
593 the start with a new set of cached layers.
594 --os="OS"
597 Set the OS of the image to be built, and that of the base image to be
600 pulled, if the build uses one, instead of using the current operating
601 system of the host.
602 --pid how
605 Sets the configuration for PID namespaces when handling RUN instruc‐
608 tions. The configured value can be "" (the empty string) or "private"
609 to indicate that a new PID namespace should be created, or it can be
610 "host" to indicate that the PID namespace in which buildah itself is
611 being run should be reused, or it can be the path to a PID namespace
612 which is already in use by another process.
613 --platform="OS/ARCH[/VARIANT]"
616 Set the OS/ARCH of the built image (and its base image, if your build
619 uses one) to the provided value instead of using the current operating
620 system and architecture of the host (for example linux/arm). If --plat‐
621 form is set, then the values of the --arch, --os, and --variant options
622 will be overridden.
623 The --platform flag can be specified more than once, or given a comma-
626 separated list of values as its argument. When more than one platform
627 is specified, the --manifest option should be used instead of the --tag
628 option.
629 OS/ARCH pairs are those used by the Go Programming Language. In sev‐
632 eral cases the ARCH value for a platform differs from one produced by
633 other tools such as the arch command. Valid OS and architecture name
634 combinations are listed as values for $GOOS and $GOARCH at
635 https://golang.org/doc/install/source#environment, and can also be
636 found by running go tool dist list.
637 While buildah bud is happy to use base images and build images for any
640 platform that exists, RUN instructions will not be able to succeed
641 without the help of emulation provided by packages like qemu-user-
642 static.
643 --pull
646 When the flag is enabled, attempt to pull the latest image from the
649 registries listed in registries.conf if a local image does not exist or
650 the image is newer than the one in storage. Raise an error if the image
651 is not in any listed registry and is not present locally.
652 If the flag is disabled (with --pull=false), do not pull the image from
655 the registry, unless there is no local image. Raise an error if the im‐
656 age is not in any registry and is not present locally.
657 Defaults to true.
660 --pull-always
663 Pull the image from the first registry it is found in as listed in reg‐
666 istries.conf. Raise an error if not found in the registries, even if
667 the image is present locally.
668 --pull-never
671 Do not pull the image from the registry, use only the local version.
674 Raise an error if the image is not present locally.
675 --quiet, -q
678 Suppress output messages which indicate which instruction is being pro‐
681 cessed, and of progress when pulling images from a registry, and when
682 writing the output image.
683 --rm bool-value
686 Remove intermediate containers after a successful build (default true).
689 --runtime path
692 The path to an alternate OCI-compatible runtime, which will be used to
695 run commands specified by the RUN instruction. Default is runc, or crun
696 when machine is configured to use cgroups V2.
697 Note: You can also override the default runtime by setting the BUIL‐
700 DAH_RUNTIME environment variable. export BUILDAH_RUNTIME=/usr/bin/crun
701 --runtime-flag flag
704 Adds global flags for the container rutime. To list the supported
707 flags, please consult the manpages of the selected container runtime.
708 Note: Do not pass the leading -- to the flag. To pass the runc flag
711 --log-format json to buildah build, the option given would be --run‐
712 time-flag log-format=json.
713 --secret=id=id,src=path
716 Pass secret information to be used in the Containerfile for building
719 images in a safe way that will not end up stored in the final image, or
720 be seen in other stages. The secret will be mounted in the container
721 at the default location of /run/secrets/id.
722 To later use the secret, use the --mount flag in a RUN instruction
725 within a Containerfile:
726 RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret
729 --security-opt=[]
732 Security Options
735 "apparmor=unconfined" : Turn off apparmor confinement for the container
738 "apparmor=your-profile" : Set the apparmor confinement profile for
739 the container
740 "label=user:USER" : Set the label user for the container
743 "label=role:ROLE" : Set the label role for the container
744 "label=type:TYPE" : Set the label type for the container
745 "label=level:LEVEL" : Set the label level for the container
746 "label=disable" : Turn off label confinement for the container
747 "no-new-privileges" : Not supported
748 "seccomp=unconfined" : Turn off seccomp confinement for the container
751 "seccomp=profile.json : White listed syscalls seccomp Json file to
752 be used as a seccomp filter
753 --shm-size=""
756 Size of /dev/shm. The format is <number><unit>. number must be greater
759 than 0. Unit is optional and can be b (bytes), k (kilobytes),
760 m(megabytes), or g (gigabytes). If you omit the unit, the system uses
761 bytes. If you omit the size entirely, the system uses 64m.
762 --sign-by fingerprint
765 Sign the built image using the GPG key that matches the specified fin‐
768 gerprint.
769 --squash
772 Squash all of the image's new layers into a single new layer; any pre‐
775 existing layers are not squashed.
776 --ssh=default|id[=socket>|[,]
779 SSH agent socket or keys to expose to the build. The socket path can
782 be left empty to use the value of default=$SSH_AUTH_SOCK
783 To later use the ssh agent, use the --mount flag in a RUN instruction
786 within a Containerfile:
787 RUN --mount=type=secret,id=id mycmd
790 --stdin
793 Pass stdin into the RUN containers. Sometime commands being RUN within
796 a Containerfile want to request information from the user. For example
797 apt asking for a confirmation for install. Use --stdin to be able to
798 interact from the terminal during the build.
799 --tag, -t imageName
802 Specifies the name which will be assigned to the resulting image if the
805 build process completes successfully. If imageName does not include a
806 registry name component, the registry name localhost will be prepended
807 to the image name.
808 --target stageName
811 Set the target build stage to build. When building a Containerfile
814 with multiple build stages, --target can be used to specify an interme‐
815 diate build stage by name as the final stage for the resulting image.
816 Commands after the target stage will be skipped.
817 --timestamp seconds
820 Set the create timestamp to seconds since epoch to allow for determin‐
823 istic builds (defaults to current time). By default, the created time‐
824 stamp is changed and written into the image manifest with every commit,
825 causing the image's sha256 hash to be different even if the sources are
826 exactly the same otherwise. When --timestamp is set, the created time‐
827 stamp is always set to the time specified and therefore not changed,
828 allowing the image's sha256 to remain the same. All files committed to
829 the layers of the image will be created with the timestamp.
830 --tls-verify bool-value
833 Require HTTPS and verification of certificates when talking to con‐
836 tainer registries (defaults to true). TLS verification cannot be used
837 when talking to an insecure registry.
838 --ulimit type=soft-limit[:hard-limit]
841 Specifies resource limits to apply to processes launched when process‐
844 ing RUN instructions. This option can be specified multiple times.
845 Recognized resource types include:
846 "core": maximum core dump size (ulimit -c)
847 "cpu": maximum CPU time (ulimit -t)
848 "data": maximum size of a process's data segment (ulimit -d)
849 "fsize": maximum size of new files (ulimit -f)
850 "locks": maximum number of file locks (ulimit -x)
851 "memlock": maximum amount of locked memory (ulimit -l)
852 "msgqueue": maximum amount of data in message queues (ulimit -q)
853 "nice": niceness adjustment (nice -n, ulimit -e)
854 "nofile": maximum number of open files (ulimit -n)
855 "nofile": maximum number of open files (1048576); when run by root
856 "nproc": maximum number of processes (ulimit -u)
857 "nproc": maximum number of processes (1048576); when run by root
858 "rss": maximum size of a process's (ulimit -m)
859 "rtprio": maximum real-time scheduling priority (ulimit -r)
860 "rttime": maximum amount of real-time execution between blocking
861 syscalls
862 "sigpending": maximum number of pending signals (ulimit -i)
863 "stack": maximum stack size (ulimit -s)
864 --userns how
867 Sets the configuration for user namespaces when handling RUN instruc‐
870 tions. The configured value can be "" (the empty string) or "private"
871 to indicate that a new user namespace should be created, it can be
872 "host" to indicate that the user namespace in which buildah itself is
873 being run should be reused, or it can be the path to an user namespace
874 which is already in use by another process.
875 --userns-uid-map-user user
878 Specifies that a UID mapping which should be used to set ownership, at
881 the filesystem level, on the working container's contents, can be found
882 in entries in the /etc/subuid file which correspond to the specified
883 user. Commands run when handling RUN instructions will default to be‐
884 ing run in their own user namespaces, configured using the UID and GID
885 maps. If --userns-gid-map-group is specified, but --userns-uid-map-
886 user is not specified, buildah will assume that the specified group
887 name is also a suitable user name to use as the default setting for
888 this option.
889 Users can specify the maps directly using --userns-uid-map described in
892 the buildah(1) man page.
893 NOTE: When this option is specified by a rootless user, the specified
896 mappings are relative to the rootless usernamespace in the container,
897 rather than being relative to the host as it would be when run rootful.
898 --userns-gid-map-group group
901 Specifies that a GID mapping which should be used to set ownership, at
904 the filesystem level, on the working container's contents, can be found
905 in entries in the /etc/subgid file which correspond to the specified
906 group. Commands run when handling RUN instructions will default to be‐
907 ing run in their own user namespaces, configured using the UID and GID
908 maps. If --userns-uid-map-user is specified, but --userns-gid-map-
909 group is not specified, buildah will assume that the specified user
910 name is also a suitable group name to use as the default setting for
911 this option.
912 Users can specify the maps directly using --userns-gid-map described in
915 the buildah(1) man page.
916 NOTE: When this option is specified by a rootless user, the specified
919 mappings are relative to the rootless usernamespace in the container,
920 rather than being relative to the host as it would be when run rootful.
921 --uts how
924 Sets the configuration for UTS namespaces when the handling RUN in‐
927 structions. The configured value can be "" (the empty string) or "con‐
928 tainer" to indicate that a new UTS namespace should be created, or it
929 can be "host" to indicate that the UTS namespace in which buildah it‐
930 self is being run should be reused, or it can be the path to a UTS
931 namespace which is already in use by another process.
932 --variant=""
935 Set the architecture variant of the image to be pulled.
938 --volume, -v[=[HOST-DIR:CONTAINER-DIR[:OPTIONS]]]
941 Create a bind mount. If you specify, -v /HOST-DIR:/CONTAINER-DIR, Buil‐
944 dah
945 bind mounts /HOST-DIR in the host to /CONTAINER-DIR in the Buildah
946 container. The OPTIONS are a comma delimited list and can be: [1]
947 ⟨#Footnote1⟩
948 • [rw|ro]
951 • [U]
953 • [z|Z|O]
955 • [[r]shared|[r]slave|[r]private]
957 The CONTAINER-DIR must be an absolute path such as /src/docs. The HOST-
961 DIR must be an absolute path as well. Buildah bind-mounts the HOST-DIR
962 to the path you specify. For example, if you supply /foo as the host
963 path, Buildah copies the contents of /foo to the container filesystem
964 on the host and bind mounts that into the container.
965 You can specify multiple -v options to mount one or more mounts to a
968 container.
969 Write Protected Volume Mounts
972 You can add the :ro or :rw suffix to a volume to mount it read-only or
975 read-write mode, respectively. By default, the volumes are mounted
976 read-write. See examples.
977 Chowning Volume Mounts
980 By default, Buildah does not change the owner and group of source vol‐
983 ume directories mounted into containers. If a container is created in a
984 new user namespace, the UID and GID in the container may correspond to
985 another UID and GID on the host.
986 The :U suffix tells Buildah to use the correct host UID and GID based
989 on the UID and GID within the container, to change the owner and group
990 of the source volume.
991 Labeling Volume Mounts
994 Labeling systems like SELinux require that proper labels are placed on
997 volume content mounted into a container. Without a label, the security
998 system might prevent the processes running inside the container from
999 using the content. By default, Buildah does not change the labels set
1000 by the OS.
1001 To change a label in the container context, you can add either of two
1004 suffixes :z or :Z to the volume mount. These suffixes tell Buildah to
1005 relabel file objects on the shared volumes. The z option tells Buildah
1006 that two containers share the volume content. As a result, Buildah la‐
1007 bels the content with a shared content label. Shared volume labels al‐
1008 low all containers to read/write content. The Z option tells Buildah
1009 to label the content with a private unshared label. Only the current
1010 container can use a private volume.
1011 Overlay Volume Mounts
1014 The :O flag tells Buildah to mount the directory from the host as a
1017 temporary storage using the Overlay file system. The RUN command con‐
1018 tainers are allowed to modify contents within the mountpoint and are
1019 stored in the container storage in a separate directory. In Overlay FS
1020 terms the source directory will be the lower, and the container storage
1021 directory will be the upper. Modifications to the mount point are de‐
1022 stroyed when the RUN command finishes executing, similar to a tmpfs
1023 mount point.
1024 Any subsequent execution of RUN commands sees the original source di‐
1027 rectory content, any changes from previous RUN commands no longer ex‐
1028 ists.
1029 One use case of the overlay mount is sharing the package cache from the
1032 host into the container to allow speeding up builds.
1033 Note:
1036 - The `O` flag is not allowed to be specified with the `Z` or `z` flags. Content mounted into the container is labeled with the private label.
1039 On SELinux systems, labels in the source directory needs to be readable by the container label. If not, SELinux container separation must be disabled for the container to work.
1040 - Modification of the directory volume mounted into the container with an overlay mount can cause unexpected failures. It is recommended that you do not modify the directory until the container finishes running.
1041 By default bind mounted volumes are private. That means any mounts done
1045 inside container will not be visible on the host and vice versa. This
1046 behavior can be changed by specifying a volume mount propagation prop‐
1047 erty.
1048 When the mount propagation policy is set to shared, any mounts com‐
1051 pleted inside the container on that volume will be visible to both the
1052 host and container. When the mount propagation policy is set to slave,
1053 one way mount propagation is enabled and any mounts completed on the
1054 host for that volume will be visible only inside of the container. To
1055 control the mount propagation property of the volume use the
1056 :[r]shared, :[r]slave or :[r]private propagation flag. The propagation
1057 property can be specified only for bind mounted volumes and not for in‐
1058 ternal volumes or named volumes. For mount propagation to work on the
1059 source mount point (the mount point where source dir is mounted on) it
1060 has to have the right propagation properties. For shared volumes, the
1061 source mount point has to be shared. And for slave volumes, the source
1062 mount has to be either shared or slave. [1] ⟨#Footnote1⟩
1063 Use df <source-dir> to determine the source mount and then use findmnt
1066 -o TARGET,PROPAGATION <source-mount-dir> to determine propagation prop‐
1067 erties of source mount, if findmnt utility is not available, the source
1068 mount point can be determined by looking at the mount entry in
1069 /proc/self/mountinfo. Look at optional fields and see if any propaga‐
1070 tion properties are specified. shared:X means the mount is shared,
1071 master:X means the mount is slave and if nothing is there that means
1072 the mount is private. [1] ⟨#Footnote1⟩
1073 To change propagation properties of a mount point use the mount com‐
1076 mand. For example, to bind mount the source directory /foo do mount
1077 --bind /foo /foo and mount --make-private --make-shared /foo. This will
1078 convert /foo into a shared mount point. The propagation properties of
1079 the source mount can be changed directly. For instance if / is the
1080 source mount for /foo, then use mount --make-shared / to convert / into
1081 a shared mount.
1082
1085 The ENV instruction in a Containerfile can be used to define variable
1086 values. When the image is built, the values will persist in the con‐
1087 tainer image. At times it is more convenient to change the values in
1088 the Containerfile via a command-line option rather than changing the
1089 values within the Containerfile itself.
1090 The following variables can be used in conjunction with the --build-arg
1093 option to override the corresponding values set in the Containerfile
1094 using the ENV instruction.
1095 • HTTP_PROXY
1098 • HTTPS_PROXY
1100 • FTP_PROXY
1102 • NO_PROXY
1104 Please refer to the Using Build Time Variables ⟨#using-build-time-vari‐
1108 ables⟩ section of the Examples.
1109
1112 Build an image using local Containerfiles
1113 buildah build .
1114 buildah build -f Containerfile .
1117 cat ~/Dockerfile | buildah build -f - .
1120 buildah build -f Dockerfile.simple -f Dockerfile.notsosimple .
1123 buildah build --timestamp=$(date '+%s') -t imageName .
1126 buildah build -t imageName .
1129 buildah build --tls-verify=true -t imageName -f Dockerfile.simple .
1132 buildah build --tls-verify=false -t imageName .
1135 buildah build --runtime-flag log-format=json .
1138 buildah build -f Containerfile --runtime-flag debug .
1141 buildah build --authfile /tmp/auths/myauths.json --cert-dir ~/auth
1144 --tls-verify=true --creds=username:password -t imageName -f Docker‐
1145 file.simple .
1146 buildah build --memory 40m --cpu-period 10000 --cpu-quota 50000
1149 --ulimit nofile=1024:1028 -t imageName .
1150 buildah build --security-opt label=level:s0:c100,c200 --cgroup-parent
1153 /path/to/cgroup/parent -t imageName .
1154 buildah build --arch=arm --variant v7 -t imageName .
1157 buildah build --volume /home/test:/myvol:ro,Z -t imageName .
1160 buildah build -v /home/test:/myvol:z,U -t imageName .
1163 buildah build -v /var/lib/dnf:/var/lib/dnf:O -t imageName .
1166 buildah build --layers -t imageName .
1169 buildah build --no-cache -t imageName .
1172 buildah build -f Containerfile --layers --force-rm -t imageName .
1175 buildah build --no-cache --rm=false -t imageName .
1178 buildah build --dns-search=example.com --dns=223.5.5.5 --dns-op‐
1181 tion=use-vc .
1182 buildah build -f Containerfile.in -t imageName .
1185 Building an multi-architecture image using the --manifest option (requires
1188 emulation software)
1189 buildah build --arch arm --manifest myimage /tmp/mysrc
1190 buildah build --arch amd64 --manifest myimage /tmp/mysrc
1193 buildah build --arch s390x --manifest myimage /tmp/mysrc
1196 buildah bud --platform linux/s390x,linux/ppc64le,linux/amd64 --manifest
1199 myimage /tmp/mysrc
1200 buildah bud --platform linux/arm64 --platform linux/amd64 --manifest
1203 myimage /tmp/mysrc
1204 Building an image using a URL
1207 This will clone the specified GitHub repository from the URL and use it
1208 as context. The Containerfile or Dockerfile at the root of the reposi‐
1209 tory is used as the context of the build. This only works if the GitHub
1210 repository is a dedicated repository.
1211 buildah build github.com/scollier/purpletest
1214 Note: You can set an arbitrary Git repository via the git:// scheme.
1217 Building an image using a URL to a tarball'ed context
1220 Buildah will fetch the tarball archive, decompress it and use its con‐
1221 tents as the build context. The Containerfile or Dockerfile at the
1222 root of the archive and the rest of the archive will get used as the
1223 context of the build. If you pass an -f PATH/Containerfile option as
1224 well, the system will look for that file inside the contents of the
1225 tarball.
1226 buildah build -f dev/Containerfile https://10.10.10.1/docker/con‐
1229 text.tar.gz
1230 Note: supported compression formats are 'xz', 'bzip2', 'gzip' and
1233 'identity' (no compression).
1234 Using Build Time Variables
1237 Replace the value set for the HTTP_PROXY environment variable within the
1238 Containerfile.
1239 buildah build --build-arg=HTTP_PROXY="http://127.0.0.1:8321"
1240
1243 BUILD_REGISTRY_SOURCES
1244 BUILD_REGISTRY_SOURCES, if set, is treated as a JSON object which con‐
1247 tains lists of registry names under the keys insecureRegistries,
1248 blockedRegistries, and allowedRegistries.
1249 When pulling an image from a registry, if the name of the registry
1252 matches any of the items in the blockedRegistries list, the image pull
1253 attempt is denied. If there are registries in the allowedRegistries
1254 list, and the registry's name is not in the list, the pull attempt is
1255 denied.
1256 TMPDIR The TMPDIR environment variable allows the user to specify where
1259 temporary files are stored while pulling and pushing images. Defaults
1260 to '/var/tmp'.
1261
1264 .containerignore/.dockerignore
1265 If the .containerignore/.dockerignore file exists in the context direc‐
1266 tory, buildah build reads its contents. If both exist, then .container‐
1267 ignore is used. Use the --ignorefile flag to override the ignore file
1268 path location. Buildah uses the content to exclude files and directo‐
1269 ries from the context directory, when executing COPY and ADD directives
1270 in the Containerfile/Dockerfile
1271 Users can specify a series of Unix shell globals in a
1274 Buildah supports a special wildcard string ** which matches any number
1277 of directories (including zero). For example, */.go will exclude all
1278 files that end with .go that are found in all directories.
1279 Example .containerignore file:
1282 # exclude this content for image
1285 */*.c
1286 **/output*
1287 src
1288 */*.c Excludes files and directories whose names ends with .c in any
1292 top level subdirectory. For example, the source file include/root‐
1293 less.c.
1294 **/output* Excludes files and directories starting with output from any
1297 directory.
1298 src Excludes files named src and the directory src as well as any con‐
1301 tent in it.
1302 Lines starting with ! (exclamation mark) can be used to make exceptions
1305 to exclusions. The following is an example .containerignore/.dockerig‐
1306 nore file that uses this mechanism:
1307 *.doc
1310 !Help.doc
1311 Exclude all doc files except Help.doc from the image.
1315 This functionality is compatible with the handling of .dockerignore
1318 files described here:
1319 https://docs.docker.com/engine/reference/builder/#dockerignore-file
1322 registries.conf (/etc/containers/registries.conf)
1325 registries.conf is the configuration file which specifies which con‐
1328 tainer registries should be consulted when completing image names which
1329 do not include a registry or domain portion.
1330 policy.json (/etc/containers/policy.json)
1333 Signature policy file. This defines the trust policy for container im‐
1336 ages. Controls which container registries can be used for image, and
1337 whether or not the tool should trust the images.
1338
1341 buildah(1), cpp(1), buildah-login(1), docker-login(1), namespaces(7),
1342 pid_namespaces(7), containers-policy.json(5), containers-reg‐
1343 istries.conf(5), user_namespaces(7), crun(1), runc(8)
1344
1347 1: The Buildah project is committed to inclusivity, a core value of
1348 open source. The master and slave mount propagation terminology used
1349 here is problematic and divisive, and should be changed. However, these
1350 terms are currently used within the Linux kernel and must be used as-is
1351 at this time. When the kernel maintainers rectify this usage, Buildah
1352 will follow suit immediately.
1353buildah April 2017 buildah-build(1)