1buildah-bud(1) General Commands Manual buildah-bud(1)
2
6 buildah-bud - Build an image using instructions from Containerfiles
7
10 buildah build-using-dockerfile [options] [context]
11 buildah bud [options] [context]
14 bud is an alias for build-using-dockerfile.
17
20 Builds an image using instructions from one or more Containerfiles or
21 Dockerfiles and a specified build context directory. A Containerfile
22 uses the same syntax as a Dockerfile internally. For this document, a
23 file referred to as a Containerfile can be a file named either 'Con‐
24 tainerfile' or 'Dockerfile'.
25 The build context directory can be specified as the http(s) URL of an
28 archive, git repository or Containerfile.
29 If no context directory is specified, then Buildah will assume the cur‐
32 rent working directory as build context, which should contain a Con‐
33 tainerfile.
34 Containerfiles ending with a ".in" suffix will be preprocessed via
37 cpp(1). This can be useful to decompose Containerfiles into several
38 reusable parts that can be used via CPP's #include directive. Notice,
39 a Containerfile.in file can still be used by other tools when manually
40 preprocessing them via cpp -E. Any comments ( Lines beginning with # )
41 in included Containerfile(s) that are not preprocess commands, will be
42 printed as warnings during builds.
43 When the URL is an archive, the contents of the URL is downloaded to a
46 temporary location and extracted before execution.
47 When the URL is a Containerfile, the file is downloaded to a temporary
50 location.
51 When a Git repository is set as the URL, the repository is cloned lo‐
54 cally and then set as the context.
55
58 --add-host=[]
59 Add a custom host-to-IP mapping (host:ip)
62 Add a line to /etc/hosts. The format is hostname:ip. The --add-host op‐
65 tion can be set multiple times.
66 --annotation annotation
69 Add an image annotation (e.g. annotation=value) to the image metadata.
72 Can be used multiple times.
73 Note: this information is not present in Docker image formats, so it is
76 discarded when writing images in Docker formats.
77 --arch="ARCH"
80 Set the ARCH of the image to be pulled to the provided value instead of
83 using the architecture of the host. (Examples: aarch64, arm, i686,
84 ppc64le, s390x, x86_64)
85 --authfile path
88 Path of the authentication file. Default is ${XDG_\RUNTIME_DIR}/con‐
91 tainers/auth.json. If XDG_RUNTIME_DIR is not set, the default is
92 /run/containers/$UID/auth.json. This file is created using using buil‐
93 dah login.
94 If the authorization state is not found there, $HOME/.docker/con‐
97 fig.json is checked, which is set using docker login.
98 Note: You can also override the default path of the authentication file
101 by setting the REGISTRY_AUTH_FILE environment variable. export REG‐
102 ISTRY_AUTH_FILE=path
103 --build-arg arg=value
106 Specifies a build argument and its value, which will be interpolated in
109 instructions read from the Containerfiles in the same way that environ‐
110 ment variables are, but which will not be added to environment variable
111 list in the resulting image's configuration.
112 Please refer to the BUILD TIME VARIABLES ⟨#build-time-variables⟩ sec‐
115 tion for the list of variables that can be overridden within the Con‐
116 tainerfile at run time.
117 --cache-from
120 Images to utilise as potential cache sources. Buildah does not cur‐
123 rently support --cache-from so this is a NOOP.
124 --cap-add=CAP_xxx
127 When executing RUN instructions, run the command specified in the in‐
130 struction with the specified capability added to its capability set.
131 Certain capabilities are granted by default; this option can be used to
132 add more.
133 --cap-drop=CAP_xxx
136 When executing RUN instructions, run the command specified in the in‐
139 struction with the specified capability removed from its capability
140 set. The CAP_AUDIT_WRITE, CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_FOWNER,
141 CAP_FSETID, CAP_KILL, CAP_MKNOD, CAP_NET_BIND_SERVICE, CAP_SETFCAP,
142 CAP_SETGID, CAP_SETPCAP, CAP_SETUID, and CAP_SYS_CHROOT capabilities
143 are granted by default; this option can be used to remove them.
144 If a capability is specified to both the --cap-add and --cap-drop op‐
147 tions, it will be dropped, regardless of the order in which the options
148 were given.
149 --cert-dir path
152 Use certificates at path (*.crt, *.cert, *.key) to connect to the reg‐
155 istry. The default certificates directory is /etc/containers/certs.d.
156 --cgroup-parent=""
159 Path to cgroups under which the cgroup for the container will be cre‐
162 ated. If the path is not absolute, the path is considered to be rela‐
163 tive to the cgroups path of the init process. Cgroups will be created
164 if they do not already exist.
165 --compress
168 This option is added to be aligned with other containers CLIs. Buildah
171 doesn't send a copy of the context directory to a daemon or a remote
172 server. Thus, compressing the data before sending it is irrelevant to
173 Buildah.
174 --cni-config-dir=directory
177 Location of CNI configuration files which will dictate which plugins
180 will be used to configure network interfaces and routing for containers
181 created for handling RUN instructions, if those containers will be run
182 in their own network namespaces, and networking is not disabled.
183 --cni-plugin-path=directory[:directory[:directory[...]]]
186 List of directories in which the CNI plugins which will be used for
189 configuring network namespaces can be found.
190 --cpu-period=0
193 Set the CPU period for the Completely Fair Scheduler (CFS), which is a
196 duration in microseconds. Once the container's CPU quota is used up, it
197 will not be scheduled to run until the current period ends. Defaults to
198 100000 microseconds.
199 On some systems, changing the CPU limits may not be allowed for
202 non-root users. For more details, see https://github.com/contain‐
203 ers/podman/blob/master/troubleshooting.md#26-running-contain‐
204 ers-with-cpu-limits-fails-with-a-permissions-error
205 --cpu-quota=0
208 Limit the CPU CFS (Completely Fair Scheduler) quota
211 Limit the container's CPU usage. By default, containers run with the
214 full CPU resource. This flag tell the kernel to restrict the con‐
215 tainer's CPU usage to the quota you specify.
216 On some systems, changing the CPU limits may not be allowed for
219 non-root users. For more details, see https://github.com/contain‐
220 ers/podman/blob/master/troubleshooting.md#26-running-contain‐
221 ers-with-cpu-limits-fails-with-a-permissions-error
222 --cpu-shares, -c=0
225 CPU shares (relative weight)
228 By default, all containers get the same proportion of CPU cycles. This
231 proportion can be modified by changing the container's CPU share
232 weighting relative to the weighting of all other running containers.
233 To modify the proportion from the default of 1024, use the --cpu-shares
236 flag to set the weighting to 2 or higher.
237 The proportion will only apply when CPU-intensive processes are run‐
240 ning. When tasks in one container are idle, other containers can use
241 the left-over CPU time. The actual amount of CPU time will vary depend‐
242 ing on the number of containers running on the system.
243 For example, consider three containers, one has a cpu-share of 1024 and
246 two others have a cpu-share setting of 512. When processes in all three
247 containers attempt to use 100% of CPU, the first container would re‐
248 ceive 50% of the total CPU time. If you add a fourth container with a
249 cpu-share of 1024, the first container only gets 33% of the CPU. The
250 remaining containers receive 16.5%, 16.5% and 33% of the CPU.
251 On a multi-core system, the shares of CPU time are distributed over all
254 CPU cores. Even if a container is limited to less than 100% of CPU
255 time, it can use 100% of each individual CPU core.
256 For example, consider a system with more than three cores. If you start
259 one container {C0} with -c=512 running one process, and another con‐
260 tainer {C1} with -c=1024 running two processes, this can result in the
261 following division of CPU shares:
262 PID container CPU CPU share
265 100 {C0} 0 100% of CPU0
266 101 {C1} 1 100% of CPU1
267 102 {C1} 2 100% of CPU2
268 --cpuset-cpus=""
272 CPUs in which to allow execution (0-3, 0,1)
275 --cpuset-mems=""
278 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effec‐
281 tive on NUMA systems.
282 If you have four memory nodes on your system (0-3), use
285 --cpuset-mems=0,1 then processes in your container will only use memory
286 from the first two memory nodes.
287 --creds creds
290 The [username[:password]] to use to authenticate with the registry if
293 required. If one or both values are not supplied, a command line
294 prompt will appear and the value can be entered. The password is en‐
295 tered without echo.
296 --decryption-key key[:passphrase]
299 The [key[:passphrase]] to be used for decryption of images. Key can
302 point to keys and/or certificates. Decryption will be tried with all
303 keys. If the key is protected by a passphrase, it is required to be
304 passed in the argument and omitted otherwise.
305 --device=device
308 Add a host device to the container. Optional permissions parameter can
311 be used to specify device permissions, it is combination of r for read,
312 w for write, and m for mknod(2).
313 Example: --device=/dev/sdc:/dev/xvdc:rwm.
316 Note: if _hostdevice is a symbolic link then it will be resolved first.
319 The container will only store the major and minor numbers of the host
320 device.
321 Note: if the user only has access rights via a group, accessing the de‐
324 vice from inside a rootless container will fail. The crun(1) runtime
325 offers a workaround for this by adding the option --annotation
326 run.oci.keep_original_groups=1.
327 --disable-compression, -D Don't compress filesystem layers when build‐
330 ing the image unless it is required by the location where the image is
331 being written. This is the default setting, because image layers are
332 compressed automatically when they are pushed to registries, and images
333 being written to local storage would only need to be decompressed again
334 to be stored. Compression can be forced in all cases by specifying
335 --disable-compression=false.
336 --disable-content-trust
339 This is a Docker specific option to disable image verification to a
342 Docker registry and is not supported by Buildah. This flag is a NOOP
343 and provided solely for scripting compatibility.
344 --dns=[]
347 Set custom DNS servers
350 This option can be used to override the DNS configuration passed to the
353 container. Typically this is necessary when the host DNS configuration
354 is invalid for the container (e.g., 127.0.0.1). When this is the case
355 the --dns flag is necessary for every run.
356 The special value none can be specified to disable creation of /etc/re‐
359 solv.conf in the container by Buildah. The /etc/resolv.conf file in the
360 image will be used without changes.
361 --dns-option=[]
364 Set custom DNS options
367 --dns-search=[]
370 Set custom DNS search domains
373 --file, -f Containerfile
376 Specifies a Containerfile which contains instructions for building the
379 image, either a local file or an http or https URL. If more than one
380 Containerfile is specified, FROM instructions will only be accepted
381 from the first specified file.
382 If a local file is specified as the Containerfile and it does not ex‐
385 ist, the context directory will be prepended to the local file value.
386 If you specify -f -, the Containerfile contents will be read from
389 stdin.
390 --force-rm bool-value
393 Always remove intermediate containers after a build, even if the build
396 fails (default false).
397 --format
400 Control the format for the built image's manifest and configuration
403 data. Recognized formats include oci (OCI image-spec v1.0, the de‐
404 fault) and docker (version 2, using schema format 2 for the manifest).
405 Note: You can also override the default format by setting the BUIL‐
408 DAH_FORMAT environment variable. export BUILDAH_FORMAT=docker
409 --from
412 Overrides the first FROM instruction within the Containerfile. If
415 there are multiple FROM instructions in a Containerfile, only the first
416 is changed.
417 -h, --help
420 Print usage statement
423 --http-proxy=true
426 By default proxy environment variables are passed into the container if
429 set for the buildah process. This can be disabled by setting the
430 --http-proxy option to false. The environment variables passed in in‐
431 clude http_proxy, https_proxy, ftp_proxy, no_proxy, and also the upper
432 case versions of those.
433 --iidfile ImageIDfile
436 Write the image ID to the file.
439 --ignorefile
442 Path to an alternative .containerignore (.dockerignore) file.
445 --ipc how
448 Sets the configuration for IPC namespaces when handling RUN instruc‐
451 tions. The configured value can be "" (the empty string) or "con‐
452 tainer" to indicate that a new IPC namespace should be created, or it
453 can be "host" to indicate that the IPC namespace in which buildah it‐
454 self is being run should be reused, or it can be the path to an IPC
455 namespace which is already in use by another process.
456 --isolation type
459 Controls what type of isolation is used for running processes as part
462 of RUN instructions. Recognized types include oci (OCI-compatible run‐
463 time, the default), rootless (OCI-compatible runtime invoked using a
464 modified configuration, with --no-new-keyring added to its create invo‐
465 cation, with network and UTS namespaces disabled, and IPC, PID, and
466 user namespaces enabled; the default for unprivileged users), and ch‐
467 root (an internal wrapper that leans more toward chroot(1) than con‐
468 tainer technology).
469 Note: You can also override the default isolation type by setting the
472 BUILDAH_ISOLATION environment variable. export BUILDAH_ISOLATION=oci
473 --jobs N
476 Run up to N concurrent stages in parallel. If the number of jobs is
479 greater than 1, stdin will be read from /dev/null. If 0 is specified,
480 then there is no limit in the number of jobs that run in parallel.
481 --label label
484 Add an image label (e.g. label=value) to the image metadata. Can be
487 used multiple times.
488 Users can set a special LABEL io.containers.capabilities=CAP1,CAP2,CAP3
491 in a Containerfile that specified the list of Linux capabilities re‐
492 quired for the container to run properly. This label specified in a
493 container image tells container engines, like Podman, to run the con‐
494 tainer with just these capabilities. The container engine launches the
495 container with just the specified capabilities, as long as this list of
496 capabilities is a subset of the default list.
497 If the specified capabilities are not in the default set, container en‐
500 gines should print an error message and will run the container with the
501 default capabilities.
502 --layers bool-value
505 Cache intermediate images during the build process (Default is false).
508 Note: You can also override the default value of layers by setting the
511 BUILDAH_LAYERS environment variable. export BUILDAH_LAYERS=true
512 --logfile filename
515 Log output which would be sent to standard output and standard error to
518 the specified file instead of to standard output and standard error.
519 --manifest "manifest"
522 Name of the manifest list to which the image will be added. Creates the
525 manifest list if it does not exist. This option is useful for building
526 multi architecture images.
527 --memory, -m=""
530 Memory limit (format: [], where unit = b, k, m or g)
533 Allows you to constrain the memory available to a container. If the
536 host supports swap memory, then the -m memory setting can be larger
537 than physical RAM. If a limit of 0 is specified (not using -m), the
538 container's memory is not limited. The actual limit may be rounded up
539 to a multiple of the operating system's page size (the value would be
540 very large, that's millions of trillions).
541 --memory-swap="LIMIT"
544 A limit value equal to memory plus swap. Must be used with the -m
547 (--memory) flag. The swap LIMIT should always be larger than -m (--mem‐
548 ory) value. By default, the swap LIMIT will be set to double the value
549 of --memory.
550 The format of LIMIT is <number>[<unit>]. Unit can be b (bytes), k
553 (kilobytes), m (megabytes), or g (gigabytes). If you don't specify a
554 unit, b is used. Set LIMIT to -1 to enable unlimited swap.
555 --network, --net=mode
558 Sets the configuration for network namespaces when handling RUN in‐
561 structions.
562 Valid mode values are:
565 • none: no networking;
568 • host: use the host network stack. Note: the host mode gives
570 the container full access to local system services such as
571 D-bus and is therefore considered insecure;
572 • ns:path: path to a network namespace to join;
574 • private: create a new namespace for the container (default)
576 --no-cache
580 Do not use existing cached images for the container build. Build from
583 the start with a new set of cached layers.
584 --os="OS"
587 Set the OS of the image to be pulled instead of using the current oper‐
590 ating system of the host.
591 --pid how
594 Sets the configuration for PID namespaces when handling RUN instruc‐
597 tions. The configured value can be "" (the empty string) or "private"
598 to indicate that a new PID namespace should be created, or it can be
599 "host" to indicate that the PID namespace in which buildah itself is
600 being run should be reused, or it can be the path to a PID namespace
601 which is already in use by another process.
602 --platform="OS/ARCH"
605 Set the OS/ARCH of the image to the provided value instead of using the
608 current operating system and architecture of the host (for example
609 linux/arm). If --platform is set, then the values of the --arch and
610 --os options will be overridden.
611 --pull
614 When the flag is enabled, attempt to pull the latest image from the
617 registries listed in registries.conf if a local image does not exist or
618 the image is newer than the one in storage. Raise an error if the image
619 is not in any listed registry and is not present locally.
620 If the flag is disabled (with --pull=false), do not pull the image from
623 the registry, unless there is no local image. Raise an error if the im‐
624 age is not in any registry and is not present locally.
625 Defaults to true.
628 --pull-always
631 Pull the image from the first registry it is found in as listed in reg‐
634 istries.conf. Raise an error if not found in the registries, even if
635 the image is present locally.
636 --pull-never
639 Do not pull the image from the registry, use only the local version.
642 Raise an error if the image is not present locally.
643 --quiet, -q
646 Suppress output messages which indicate which instruction is being pro‐
649 cessed, and of progress when pulling images from a registry, and when
650 writing the output image.
651 --rm bool-value
654 Remove intermediate containers after a successful build (default true).
657 --runtime path
660 The path to an alternate OCI-compatible runtime, which will be used to
663 run commands specified by the RUN instruction. Default is runc, or crun
664 when machine is configured to use cgroups V2.
665 Note: You can also override the default runtime by setting the BUIL‐
668 DAH_RUNTIME environment variable. export BUILDAH_RUNTIME=/usr/bin/crun
669 --runtime-flag flag
672 Adds global flags for the container rutime. To list the supported
675 flags, please consult the manpages of the selected container runtime.
676 Note: Do not pass the leading -- to the flag. To pass the runc flag
679 --log-format json to buildah bud, the option given would be --run‐
680 time-flag log-format=json.
681 --secret=id=id,src=path Pass secret information to be used in the Con‐
684 tainerfile for building images in a safe way that will not end up
685 stored in the final image, or be seen in other stages. The secret will
686 be mounted in the container at the default location of /run/secrets/id.
687 To later use the secret, use the --mount flag in a RUN instruction
690 within a Containerfile:
691 RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret
694 --security-opt=[]
697 Security Options
700 "apparmor=unconfined" : Turn off apparmor confinement for the container
703 "apparmor=your-profile" : Set the apparmor confinement profile for
704 the container
705 "label=user:USER" : Set the label user for the container
708 "label=role:ROLE" : Set the label role for the container
709 "label=type:TYPE" : Set the label type for the container
710 "label=level:LEVEL" : Set the label level for the container
711 "label=disable" : Turn off label confinement for the container
712 "no-new-privileges" : Not supported
713 "seccomp=unconfined" : Turn off seccomp confinement for the container
716 "seccomp=profile.json : White listed syscalls seccomp Json file to
717 be used as a seccomp filter
718 --shm-size=""
721 Size of /dev/shm. The format is <number><unit>. number must be greater
724 than 0. Unit is optional and can be b (bytes), k (kilobytes),
725 m(megabytes), or g (gigabytes). If you omit the unit, the system uses
726 bytes. If you omit the size entirely, the system uses 64m.
727 --sign-by fingerprint
730 Sign the built image using the GPG key that matches the specified fin‐
733 gerprint.
734 --squash
737 Squash all of the image's new layers into a single new layer; any pre‐
740 existing layers are not squashed.
741 --stdin
744 Pass stdin into the RUN containers. Sometime commands being RUN within
747 a Containerfile want to request information from the user. For example
748 apt asking for a confirmation for install. Use --stdin to be able to
749 interact from the terminal during the build.
750 --tag, -t imageName
753 Specifies the name which will be assigned to the resulting image if the
756 build process completes successfully. If imageName does not include a
757 registry name, the registry name localhost will be prepended to the im‐
758 age name.
759 --target stageName
762 Set the target build stage to build. When building a Containerfile
765 with multiple build stages, --target can be used to specify an interme‐
766 diate build stage by name as the final stage for the resulting image.
767 Commands after the target stage will be skipped.
768 --timestamp seconds
771 Set the create timestamp to seconds since epoch to allow for determin‐
774 istic builds (defaults to current time). By default, the created time‐
775 stamp is changed and written into the image manifest with every commit,
776 causing the image's sha256 hash to be different even if the sources are
777 exactly the same otherwise. When --timestamp is set, the created time‐
778 stamp is always set to the time specified and therefore not changed,
779 allowing the image's sha256 to remain the same. All files committed to
780 the layers of the image will be created with the timestamp.
781 --tls-verify bool-value
784 Require HTTPS and verification of certificates when talking to con‐
787 tainer registries (defaults to true). TLS verification cannot be used
788 when talking to an insecure registry.
789 --ulimit type=soft-limit[:hard-limit]
792 Specifies resource limits to apply to processes launched when process‐
795 ing RUN instructions. This option can be specified multiple times.
796 Recognized resource types include:
797 "core": maximum core dump size (ulimit -c)
798 "cpu": maximum CPU time (ulimit -t)
799 "data": maximum size of a process's data segment (ulimit -d)
800 "fsize": maximum size of new files (ulimit -f)
801 "locks": maximum number of file locks (ulimit -x)
802 "memlock": maximum amount of locked memory (ulimit -l)
803 "msgqueue": maximum amount of data in message queues (ulimit -q)
804 "nice": niceness adjustment (nice -n, ulimit -e)
805 "nofile": maximum number of open files (ulimit -n)
806 "nofile": maximum number of open files (1048576); when run by root
807 "nproc": maximum number of processes (ulimit -u)
808 "nproc": maximum number of processes (1048576); when run by root
809 "rss": maximum size of a process's (ulimit -m)
810 "rtprio": maximum real-time scheduling priority (ulimit -r)
811 "rttime": maximum amount of real-time execution between blocking
812 syscalls
813 "sigpending": maximum number of pending signals (ulimit -i)
814 "stack": maximum stack size (ulimit -s)
815 --userns how
818 Sets the configuration for user namespaces when handling RUN instruc‐
821 tions. The configured value can be "" (the empty string) or "private"
822 to indicate that a new user namespace should be created, it can be
823 "host" to indicate that the user namespace in which buildah itself is
824 being run should be reused, or it can be the path to an user namespace
825 which is already in use by another process.
826 --userns-uid-map-user user
829 Specifies that a UID mapping which should be used to set ownership, at
832 the filesystem level, on the working container's contents, can be found
833 in entries in the /etc/subuid file which correspond to the specified
834 user. Commands run when handling RUN instructions will default to be‐
835 ing run in their own user namespaces, configured using the UID and GID
836 maps. If --userns-gid-map-group is specified, but
837 --userns-uid-map-user is not specified, buildah will assume that the
838 specified group name is also a suitable user name to use as the default
839 setting for this option.
840 Users can specify the maps directly using --userns-uid-map described in
843 the buildah(1) man page.
844 NOTE: When this option is specified by a rootless user, the specified
847 mappings are relative to the rootless usernamespace in the container,
848 rather than being relative to the host as it would be when run rootful.
849 --userns-gid-map-group group
852 Specifies that a GID mapping which should be used to set ownership, at
855 the filesystem level, on the working container's contents, can be found
856 in entries in the /etc/subgid file which correspond to the specified
857 group. Commands run when handling RUN instructions will default to be‐
858 ing run in their own user namespaces, configured using the UID and GID
859 maps. If --userns-uid-map-user is specified, but
860 --userns-gid-map-group is not specified, buildah will assume that the
861 specified user name is also a suitable group name to use as the default
862 setting for this option.
863 Users can specify the maps directly using --userns-gid-map described in
866 the buildah(1) man page.
867 NOTE: When this option is specified by a rootless user, the specified
870 mappings are relative to the rootless usernamespace in the container,
871 rather than being relative to the host as it would be when run rootful.
872 --uts how
875 Sets the configuration for UTS namespaces when the handling RUN in‐
878 structions. The configured value can be "" (the empty string) or "con‐
879 tainer" to indicate that a new UTS namespace should be created, or it
880 can be "host" to indicate that the UTS namespace in which buildah it‐
881 self is being run should be reused, or it can be the path to a UTS
882 namespace which is already in use by another process.
883 --variant=""
886 Set the architecture variant of the image to be pulled.
889 --volume, -v[=[HOST-DIR:CONTAINER-DIR[:OPTIONS]]]
892 Create a bind mount. If you specify, -v /HOST-DIR:/CONTAINER-DIR, Buil‐
895 dah
896 bind mounts /HOST-DIR in the host to /CONTAINER-DIR in the Buildah
897 container. The OPTIONS are a comma delimited list and can be: [1]
898 ⟨#Footnote1⟩
899 • [rw|ro]
902 • [U]
904 • [z|Z|O]
906 • [[r]shared|[r]slave|[r]private]
908 The CONTAINER-DIR must be an absolute path such as /src/docs. The
912 HOST-DIR must be an absolute path as well. Buildah bind-mounts the
913 HOST-DIR to the path you specify. For example, if you supply /foo as
914 the host path, Buildah copies the contents of /foo to the container
915 filesystem on the host and bind mounts that into the container.
916 You can specify multiple -v options to mount one or more mounts to a
919 container.
920 Write Protected Volume Mounts
923 You can add the :ro or :rw suffix to a volume to mount it read-only or
926 read-write mode, respectively. By default, the volumes are mounted
927 read-write. See examples.
928 Chowning Volume Mounts
931 By default, Buildah does not change the owner and group of source vol‐
934 ume directories mounted into containers. If a container is created in a
935 new user namespace, the UID and GID in the container may correspond to
936 another UID and GID on the host.
937 The :U suffix tells Buildah to use the correct host UID and GID based
940 on the UID and GID within the container, to change the owner and group
941 of the source volume.
942 Labeling Volume Mounts
945 Labeling systems like SELinux require that proper labels are placed on
948 volume content mounted into a container. Without a label, the security
949 system might prevent the processes running inside the container from
950 using the content. By default, Buildah does not change the labels set
951 by the OS.
952 To change a label in the container context, you can add either of two
955 suffixes :z or :Z to the volume mount. These suffixes tell Buildah to
956 relabel file objects on the shared volumes. The z option tells Buildah
957 that two containers share the volume content. As a result, Buildah la‐
958 bels the content with a shared content label. Shared volume labels al‐
959 low all containers to read/write content. The Z option tells Buildah
960 to label the content with a private unshared label. Only the current
961 container can use a private volume.
962 Overlay Volume Mounts
965 The :O flag tells Buildah to mount the directory from the host as a
968 temporary storage using the Overlay file system. The RUN command con‐
969 tainers are allowed to modify contents within the mountpoint and are
970 stored in the container storage in a separate directory. In Overlay FS
971 terms the source directory will be the lower, and the container storage
972 directory will be the upper. Modifications to the mount point are de‐
973 stroyed when the RUN command finishes executing, similar to a tmpfs
974 mount point.
975 Any subsequent execution of RUN commands sees the original source di‐
978 rectory content, any changes from previous RUN commands no longer ex‐
979 ists.
980 One use case of the overlay mount is sharing the package cache from the
983 host into the container to allow speeding up builds.
984 Note:
987 - 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.
990 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.
991 - 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.
992 By default bind mounted volumes are private. That means any mounts done
996 inside container will not be visible on the host and vice versa. This
997 behavior can be changed by specifying a volume mount propagation prop‐
998 erty.
999 When the mount propagation policy is set to shared, any mounts com‐
1002 pleted inside the container on that volume will be visible to both the
1003 host and container. When the mount propagation policy is set to slave,
1004 one way mount propagation is enabled and any mounts completed on the
1005 host for that volume will be visible only inside of the container. To
1006 control the mount propagation property of the volume use the
1007 :[r]shared, :[r]slave or :[r]private propagation flag. The propagation
1008 property can be specified only for bind mounted volumes and not for in‐
1009 ternal volumes or named volumes. For mount propagation to work on the
1010 source mount point (the mount point where source dir is mounted on) it
1011 has to have the right propagation properties. For shared volumes, the
1012 source mount point has to be shared. And for slave volumes, the source
1013 mount has to be either shared or slave. [1] ⟨#Footnote1⟩
1014 Use df <source-dir> to determine the source mount and then use findmnt
1017 -o TARGET,PROPAGATION <source-mount-dir> to determine propagation prop‐
1018 erties of source mount, if findmnt utility is not available, the source
1019 mount point can be determined by looking at the mount entry in
1020 /proc/self/mountinfo. Look at optional fields and see if any propaga‐
1021 tion properties are specified. shared:X means the mount is shared,
1022 master:X means the mount is slave and if nothing is there that means
1023 the mount is private. [1] ⟨#Footnote1⟩
1024 To change propagation properties of a mount point use the mount com‐
1027 mand. For example, to bind mount the source directory /foo do mount
1028 --bind /foo /foo and mount --make-private --make-shared /foo. This will
1029 convert /foo into a shared mount point. The propagation properties of
1030 the source mount can be changed directly. For instance if / is the
1031 source mount for /foo, then use mount --make-shared / to convert / into
1032 a shared mount.
1033
1036 The ENV instruction in a Containerfile can be used to define variable
1037 values. When the image is built, the values will persist in the con‐
1038 tainer image. At times it is more convenient to change the values in
1039 the Containerfile via a command-line option rather than changing the
1040 values within the Containerfile itself.
1041 The following variables can be used in conjunction with the --build-arg
1044 option to override the corresponding values set in the Containerfile
1045 using the ENV instruction.
1046 • HTTP_PROXY
1049 • HTTPS_PROXY
1051 • FTP_PROXY
1053 • NO_PROXY
1055 Please refer to the Using Build Time Variables ⟨#using-build-time-vari‐
1059 ables⟩ section of the Examples.
1060
1063 Build an image using local Containerfiles
1064 buildah bud .
1065 buildah bud -f Containerfile .
1068 cat ~/Dockerfile | buildah bud -f - .
1071 buildah bud -f Dockerfile.simple -f Dockerfile.notsosimple .
1074 buildah bud --timestamp=$(date '+%s') -t imageName .
1077 buildah bud -t imageName .
1080 buildah bud --tls-verify=true -t imageName -f Dockerfile.simple .
1083 buildah bud --tls-verify=false -t imageName .
1086 buildah bud --runtime-flag log-format=json .
1089 buildah bud -f Containerfile --runtime-flag debug .
1092 buildah bud --authfile /tmp/auths/myauths.json --cert-dir ~/auth
1095 --tls-verify=true --creds=username:password -t imageName -f Docker‐
1096 file.simple .
1097 buildah bud --memory 40m --cpu-period 10000 --cpu-quota 50000 --ulimit
1100 nofile=1024:1028 -t imageName .
1101 buildah bud --security-opt label=level:s0:c100,c200 --cgroup-parent
1104 /path/to/cgroup/parent -t imageName .
1105 buildah bud --arch=arm --variant v7 -t imageName .
1108 buildah bud --volume /home/test:/myvol:ro,Z -t imageName .
1111 buildah bud -v /home/test:/myvol:z,U -t imageName .
1114 buildah bud -v /var/lib/dnf:/var/lib/dnf:O -t imageName .
1117 buildah bud --layers -t imageName .
1120 buildah bud --no-cache -t imageName .
1123 buildah bud -f Containerfile --layers --force-rm -t imageName .
1126 buildah bud --no-cache --rm=false -t imageName .
1129 buildah bud --dns-search=example.com --dns=223.5.5.5 --dns-op‐
1132 tion=use-vc .
1133 buildah bud -f Containerfile.in -t imageName .
1136 Building an multi-architecture image using a --manifest option (Requires
1139 emulation software)
1140 buildah bud --arch arm --manifest myimage /tmp/mysrc buildah bud --arch
1141 amd64 --manifest myimage /tmp/mysrc buildah bud --arch s390x --manifest
1142 myimage /tmp/mysrc
1143 Building an image using a URL
1146 This will clone the specified GitHub repository from the URL and use it
1147 as context. The Containerfile or Dockerfile at the root of the reposi‐
1148 tory is used as the context of the build. This only works if the GitHub
1149 repository is a dedicated repository.
1150 buildah bud github.com/scollier/purpletest
1153 Note: You can set an arbitrary Git repository via the git:// scheme.
1156 Building an image using a URL to a tarball'ed context
1159 Buildah will fetch the tarball archive, decompress it and use its con‐
1160 tents as the build context. The Containerfile or Dockerfile at the
1161 root of the archive and the rest of the archive will get used as the
1162 context of the build. If you pass an -f PATH/Containerfile option as
1163 well, the system will look for that file inside the contents of the
1164 tarball.
1165 buildah bud -f dev/Containerfile https://10.10.10.1/docker/con‐
1168 text.tar.gz
1169 Note: supported compression formats are 'xz', 'bzip2', 'gzip' and
1172 'identity' (no compression).
1173 Using Build Time Variables
1176 Replace the value set for the HTTP_PROXY environment variable within the
1177 Containerfile.
1178 buildah bud --build-arg=HTTP_PROXY="http://127.0.0.1:8321"
1179
1182 BUILD_REGISTRY_SOURCES
1183 BUILD_REGISTRY_SOURCES, if set, is treated as a JSON object which con‐
1186 tains lists of registry names under the keys insecureRegistries,
1187 blockedRegistries, and allowedRegistries.
1188 When pulling an image from a registry, if the name of the registry
1191 matches any of the items in the blockedRegistries list, the image pull
1192 attempt is denied. If there are registries in the allowedRegistries
1193 list, and the registry's name is not in the list, the pull attempt is
1194 denied.
1195 TMPDIR The TMPDIR environment variable allows the user to specify where
1198 temporary files are stored while pulling and pushing images. Defaults
1199 to '/var/tmp'.
1200
1203 .containerignore/.dockerignore
1204 If the .containerignore/.dockerignore file exists in the context direc‐
1205 tory, buildah bud reads its contents. If both exist, then .containerig‐
1206 nore is used. Use the --ignorefile flag to override the ignore file
1207 path location. Buildah uses the content to exclude files and directo‐
1208 ries from the context directory, when executing COPY and ADD directives
1209 in the Containerfile/Dockerfile
1210 Users can specify a series of Unix shell globals in a
1213 Buildah supports a special wildcard string ** which matches any number
1216 of directories (including zero). For example, */.go will exclude all
1217 files that end with .go that are found in all directories.
1218 Example .containerignore file:
1221 # exclude this content for image
1224 */*.c
1225 **/output*
1226 src
1227 */*.c Excludes files and directories whose names ends with .c in any
1231 top level subdirectory. For example, the source file include/root‐
1232 less.c.
1233 **/output* Excludes files and directories starting with output from any
1236 directory.
1237 src Excludes files named src and the directory src as well as any con‐
1240 tent in it.
1241 Lines starting with ! (exclamation mark) can be used to make exceptions
1244 to exclusions. The following is an example .containerignore/.dockerig‐
1245 nore file that uses this mechanism:
1246 *.doc
1249 !Help.doc
1250 Exclude all doc files except Help.doc from the image.
1254 This functionality is compatible with the handling of .dockerignore
1257 files described here:
1258 https://docs.docker.com/engine/reference/builder/#dockerignore-file
1261 registries.conf (/etc/containers/registries.conf)
1264 registries.conf is the configuration file which specifies which con‐
1267 tainer registries should be consulted when completing image names which
1268 do not include a registry or domain portion.
1269 policy.json (/etc/containers/policy.json)
1272 Signature policy file. This defines the trust policy for container im‐
1275 ages. Controls which container registries can be used for image, and
1276 whether or not the tool should trust the images.
1277
1280 buildah(1), cpp(1), buildah-login(1), docker-login(1), namespaces(7),
1281 pid_namespaces(7), containers-policy.json(5), containers-reg‐
1282 istries.conf(5), user_namespaces(7), crun(1), runc(8)
1283
1286 1: The Buildah project is committed to inclusivity, a core value of
1287 open source. The master and slave mount propagation terminology used
1288 here is problematic and divisive, and should be changed. However, these
1289 terms are currently used within the Linux kernel and must be used as-is
1290 at this time. When the kernel maintainers rectify this usage, Buildah
1291 will follow suit immediately.
1292buildah April 2017 buildah-bud(1)