1buildah-from(1) General Commands Manual buildah-from(1)
2
6 buildah-from - Creates a new working container, either from scratch or
7 using a specified image as a starting point.
8
11 buildah from [options] image
12
15 Creates a working container based upon the specified image name. If
16 the supplied image name is "scratch" a new empty container is created.
17 Image names use a "transport":"details" format.
18 Multiple transports are supported:
21 dir:path
24 An existing local directory path containing the manifest, layer tar‐
25 balls, and signatures in individual files. This is a non-standardized
26 format, primarily useful for debugging or noninvasive image inspection.
27 docker://docker-reference (Default)
30 An image in a registry implementing the "Docker Registry HTTP API
31 V2". By default, uses the authorization state in $XDG\_RUN‐
32 TIME\_DIR/containers/auth.json, which is set using (buildah login). If
33 XDG_RUNTIME_DIR is not set, the default is /run/contain‐
34 ers/$UID/auth.json. If the authorization state is not found there,
35 $HOME/.docker/config.json is checked, which is set using (docker lo‐
36 gin).
37 If docker-reference does not include a registry name, localhost will
38 be consulted first, followed by any registries named in the registries
39 configuration.
40 docker-archive:path
43 An image is retrieved as a podman load formatted file.
44 docker-daemon:docker-reference
47 An image docker-reference stored in the docker daemon's internal
48 storage. docker-reference must include either a tag or a digest. Al‐
49 ternatively, when reading images, the format can also be docker-dae‐
50 mon:algo:digest (an image ID).
51 oci:path:tag**
54 An image tag in a directory compliant with "Open Container Image Lay‐
55 out Specification" at path.
56 oci-archive:path:tag
59 An image tag in a directory compliant with "Open Container Image Lay‐
60 out Specification" at path.
61 DEPENDENCIES
64 Buildah resolves the path to the registry to pull from by using the
65 /etc/containers/registries.conf file, containers-registries.conf(5).
66 If the buildah from command fails with an "image not known" error,
67 first verify that the registries.conf file is installed and configured
68 appropriately.
69
72 The container ID of the container that was created. On error 1 is re‐
73 turned.
74
77 --add-host=[]
78 Add a custom host-to-IP mapping (host:ip)
81 Add a line to /etc/hosts. The format is hostname:ip. The --add-host op‐
84 tion can be set multiple times.
85 --arch="ARCH"
88 Set the ARCH of the image to be pulled to the provided value instead of
91 using the architecture of the host. (Examples: arm, arm64, 386, amd64,
92 ppc64le, s390x)
93 --authfile path
96 Path of the authentication file. Default is ${XDG_\RUNTIME_DIR}/con‐
99 tainers/auth.json. If XDG_RUNTIME_DIR is not set, the default is
100 /run/containers/$UID/auth.json. This file is created using buildah lo‐
101 gin.
102 If the authorization state is not found there, $HOME/.docker/con‐
105 fig.json is checked, which is set using docker login.
106 Note: You can also override the default path of the authentication file
109 by setting the REGISTRY_AUTH_FILE environment variable. export REG‐
110 ISTRY_AUTH_FILE=path
111 --cap-add=CAP_xxx
114 Add the specified capability to the default set of capabilities which
117 will be supplied for subsequent buildah run invocations which use this
118 container. Certain capabilities are granted by default; this option
119 can be used to add more.
120 --cap-drop=CAP_xxx
123 Remove the specified capability from the default set of capabilities
126 which will be supplied for subsequent buildah run invocations which use
127 this container. The CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_FOWNER,
128 CAP_FSETID, CAP_KILL, CAP_NET_BIND_SERVICE, CAP_SETFCAP, CAP_SETGID,
129 CAP_SETPCAP, and CAP_SETUID capabilities are granted by default; this
130 option can be used to remove them. The list of default capabilities is
131 managed in containers.conf(5).
132 If a capability is specified to both the --cap-add and --cap-drop op‐
135 tions, it will be dropped, regardless of the order in which the options
136 were given.
137 --cert-dir path
140 Use certificates at path (*.crt, *.cert, *.key) to connect to the reg‐
143 istry. The default certificates directory is /etc/containers/certs.d.
144 --cgroup-parent=""
147 Path to cgroups under which the cgroup for the container will be cre‐
150 ated. If the path is not absolute, the path is considered to be rela‐
151 tive to the cgroups path of the init process. Cgroups will be created
152 if they do not already exist.
153 --cgroupns how
156 Sets the configuration for IPC namespaces when the container is subse‐
159 quently used for buildah run. The configured value can be "" (the
160 empty string) or "private" to indicate that a new cgroup namespace
161 should be created, or it can be "host" to indicate that the cgroup
162 namespace in which buildah itself is being run should be reused.
163 --cidfile ContainerIDFile
166 Write the container ID to the file.
169 --cpu-period=0
172 Limit the CPU CFS (Completely Fair Scheduler) period
175 Limit the container's CPU usage. This flag tells the kernel to restrict
178 the container's CPU usage to the period you specify.
179 --cpu-quota=0
182 Limit the CPU CFS (Completely Fair Scheduler) quota
185 Limit the container's CPU usage. By default, containers run with the
188 full CPU resource. This flag tells the kernel to restrict the con‐
189 tainer's CPU usage to the quota you specify.
190 --cpu-shares, -c=0
193 CPU shares (relative weight)
196 By default, all containers get the same proportion of CPU cycles. This
199 proportion can be modified by changing the container's CPU share
200 weighting relative to the weighting of all other running containers.
201 To modify the proportion from the default of 1024, use the --cpu-shares
204 flag to set the weighting to 2 or higher.
205 The proportion will only apply when CPU-intensive processes are run‐
208 ning. When tasks in one container are idle, other containers can use
209 the left-over CPU time. The actual amount of CPU time will vary depend‐
210 ing on the number of containers running on the system.
211 For example, consider three containers, one has a cpu-share of 1024 and
214 two others have a cpu-share setting of 512. When processes in all three
215 containers attempt to use 100% of CPU, the first container would re‐
216 ceive 50% of the total CPU time. If you add a fourth container with a
217 cpu-share of 1024, the first container only gets 33% of the CPU. The
218 remaining containers receive 16.5%, 16.5% and 33% of the CPU.
219 On a multi-core system, the shares of CPU time are distributed over all
222 CPU cores. Even if a container is limited to less than 100% of CPU
223 time, it can use 100% of each individual CPU core.
224 For example, consider a system with more than three cores. If you start
227 one container {C0} with -c=512 running one process, and another con‐
228 tainer {C1} with -c=1024 running two processes, this can result in the
229 following division of CPU shares:
230 PID container CPU CPU share
233 100 {C0} 0 100% of CPU0
234 101 {C1} 1 100% of CPU1
235 102 {C1} 2 100% of CPU2
236 --cpuset-cpus=""
240 CPUs in which to allow execution (0-3, 0,1)
243 --cpuset-mems=""
246 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effec‐
249 tive on NUMA systems.
250 If you have four memory nodes on your system (0-3), use --cpuset-
253 mems=0,1 then processes in your container will only use memory from the
254 first two memory nodes.
255 --creds creds
258 The [username[:password]] to use to authenticate with the registry if
261 required. If one or both values are not supplied, a command line
262 prompt will appear and the value can be entered. The password is en‐
263 tered without echo.
264 --decryption-key key[:passphrase]
267 The [key[:passphrase]] to be used for decryption of images. Key can
270 point to keys and/or certificates. Decryption will be tried with all
271 keys. If the key is protected by a passphrase, it is required to be
272 passed in the argument and omitted otherwise.
273 --device=device
276 Add a host device or devices under a directory to the container. The
279 format is <device-on-host>[:<device-on-container>][:<permissions>]
280 (e.g. --device=/dev/sdc:/dev/xvdc:rwm)
281 --dns=[]
284 Set custom DNS servers
287 This option can be used to override the DNS configuration passed to the
290 container. Typically this is necessary when the host DNS configuration
291 is invalid for the container (e.g., 127.0.0.1). When this is the case
292 the --dns flag is necessary for every run.
293 The special value none can be specified to disable creation of /etc/re‐
296 solv.conf in the container by Buildah. The /etc/resolv.conf file in the
297 image will be used without changes.
298 --dns-option=[]
301 Set custom DNS options
304 --dns-search=[]
307 Set custom DNS search domains
310 --format, -f oci | docker
313 Control the format for the built image's manifest and configuration
316 data. Recognized formats include oci (OCI image-spec v1.0, the de‐
317 fault) and docker (version 2, using schema format 2 for the manifest).
318 Note: You can also override the default format by setting the BUIL‐
321 DAH_FORMAT environment variable. export BUILDAH_FORMAT=docker
322 --group-add=group | keep-groups
325 Assign additional groups to the primary user running within the con‐
328 tainer process.
329 • keep-groups is a special flag that tells Buildah to keep the
332 supplementary group access.
333 Allows container to use the user's supplementary group access. If file
337 systems or devices are only accessible by the rootless user's group,
338 this flag tells the OCI runtime to pass the group access into the con‐
339 tainer. Currently only available with the crun OCI runtime. Note: keep-
340 groups is exclusive, other groups cannot be specified with this flag.
341 --http-proxy
344 By default proxy environment variables are passed into the container if
347 set for the Buildah process. This can be disabled by setting the
348 --http-proxy option to false. The environment variables passed in in‐
349 clude http_proxy, https_proxy, ftp_proxy, no_proxy, and also the upper
350 case versions of those.
351 Defaults to true
354 --ipc how
357 Sets the configuration for IPC namespaces when the container is subse‐
360 quently used for buildah run. The configured value can be "" (the
361 empty string) or "container" to indicate that a new IPC namespace
362 should be created, or it can be "host" to indicate that the IPC name‐
363 space in which Buildah itself is being run should be reused, or it can
364 be the path to an IPC namespace which is already in use by another
365 process.
366 --isolation type
369 Controls what type of isolation is used for running processes under
372 buildah run. Recognized types include oci (OCI-compatible runtime, the
373 default), rootless (OCI-compatible runtime invoked using a modified
374 configuration, with --no-new-keyring added to its create invocation,
375 reusing the host's network and UTS namespaces, and creating private
376 IPC, PID, mount, and user namespaces; the default for unprivileged
377 users), and chroot (an internal wrapper that leans more toward ch‐
378 root(1) than container technology, reusing the host's control group,
379 network, IPC, and PID namespaces, and creating private mount and UTS
380 namespaces, and creating user namespaces only when they're required for
381 ID mapping).
382 Note: You can also override the default isolation type by setting the
385 BUILDAH_ISOLATION environment variable. export BUILDAH_ISOLATION=oci
386 --memory, -m=""
389 Memory limit (format: [], where unit = b, k, m or g)
392 Allows you to constrain the memory available to a container. If the
395 host supports swap memory, then the -m memory setting can be larger
396 than physical RAM. If a limit of 0 is specified (not using -m), the
397 container's memory is not limited. The actual limit may be rounded up
398 to a multiple of the operating system's page size (the value would be
399 very large, that's millions of trillions).
400 --memory-swap="LIMIT"
403 A limit value equal to memory plus swap. Must be used with the -m
406 (--memory) flag. The swap LIMIT should always be larger than -m (--mem‐
407 ory) value. By default, the swap LIMIT will be set to double the value
408 of --memory.
409 The format of LIMIT is <number>[<unit>]. Unit can be b (bytes), k
412 (kilobytes), m (megabytes), or g (gigabytes). If you don't specify a
413 unit, b is used. Set LIMIT to -1 to enable unlimited swap.
414 --name name
417 A name for the working container
420 --network=mode, --net=mode
423 Sets the configuration for network namespaces when the container is
426 subsequently used for buildah run.
427 Valid mode values are:
430 • none: no networking. Invalid if using --dns, --dns-opt, or
433 --dns-search;
434 • host: use the host network stack. Note: the host mode gives
436 the container full access to local system services such as D-
437 bus and is therefore considered insecure;
438 • ns:path: path to a network namespace to join;
440 • private: create a new namespace for the container (default)
442 • <network name|ID>: Join the network with the given name or ID,
444 e.g. use --network mynet to join the network with the name
445 mynet. Only supported for rootful users.
446 • slirp4netns[:OPTIONS,...]: use slirp4netns(1) to create a user
448 network stack. This is the default for rootless containers. It
449 is possible to specify these additional options, they can also
450 be set with network_cmd_options in containers.conf:
451 • allow_host_loopback=true|false: Allow slirp4netns to reach
453 the host loopback IP (default is 10.0.2.2 or the second IP
454 from slirp4netns cidr subnet when changed, see the cidr op‐
455 tion below). The default is false.
456 • mtu=MTU: Specify the MTU to use for this network. (Default
458 is 65520).
459 • cidr=CIDR: Specify ip range to use for this network. (De‐
461 fault is 10.0.2.0/24).
462 • enable_ipv6=true|false: Enable IPv6. Default is true. (Re‐
464 quired for outbound_addr6).
465 • outbound_addr=INTERFACE: Specify the outbound interface
467 slirp binds to (ipv4 traffic only).
468 • outbound_addr=IPv4: Specify the outbound ipv4 address slirp
470 binds to.
471 • outbound_addr6=INTERFACE: Specify the outbound interface
473 slirp binds to (ipv6 traffic only).
474 • outbound_addr6=IPv6: Specify the outbound ipv6 address slirp
476 binds to.
477 • pasta[:OPTIONS,...]: use pasta(1) to create a user-mode net‐
481 working stack.
482 This is only supported in rootless mode.
483 By default, IPv4 and IPv6 addresses and routes, as well as the
484 pod interface name, are copied from the host. If port forward‐
485 ing isn't configured, ports are forwarded dynamically as ser‐
486 vices are bound on either side (init namespace or container
487 namespace). Port forwarding preserves the original source IP
488 address. Options described in pasta(1) can be specified as
489 comma-separated arguments.
490 In terms of pasta(1) options, --config-net is given by de‐
491 fault, in order to configure networking when the container is
492 started, and --no-map-gw is also assumed by default, to avoid
493 direct access from container to host using the gateway ad‐
494 dress. The latter can be overridden by passing --map-gw in the
495 pasta-specific options (despite not being an actual pasta(1)
496 option).
497 Also, -t none and -u none are passed to disable automatic port
498 forwarding based on bound ports. Similarly, -T none and -U
499 none are given to disable the same functionality from con‐
500 tainer to host.
501 Some examples:
502 • pasta:--map-gw: Allow the container to directly reach the
504 host using the gateway address.
505 • pasta:--mtu,1500: Specify a 1500 bytes MTU for the tap in‐
507 terface in the container.
508 • pasta:--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-for‐
510 ward,10.0.2.3,-m,1500,--no-ndp,--no-dhcpv6,--no-dhcp, equiv‐
511 alent to default slirp4netns(1) options: disable IPv6, as‐
512 sign 10.0.2.0/24 to the tap0 interface in the container,
513 with gateway 10.0.2.3, enable DNS forwarder reachable at
514 10.0.2.3, set MTU to 1500 bytes, disable NDP, DHCPv6 and
515 DHCP support.
516 • pasta:-I,tap0,--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-
518 forward,10.0.2.3,--no-ndp,--no-dhcpv6,--no-dhcp, equivalent
519 to default slirp4netns(1) options with Podman overrides:
520 same as above, but leave the MTU to 65520 bytes
521 • pasta:-t,auto,-u,auto,-T,auto,-U,auto: enable automatic port
523 forwarding based on observed bound ports from both host and
524 container sides
525 • pasta:-T,5201: enable forwarding of TCP port 5201 from con‐
527 tainer to host, using the loopback interface instead of the
528 tap interface for improved performance
529 --os="OS"
535 Set the OS of the image to be pulled to the provided value instead of
538 using the current operating system of the host.
539 --pid how
542 Sets the configuration for PID namespaces when the container is subse‐
545 quently used for buildah run. The configured value can be "" (the
546 empty string) or "container" to indicate that a new PID namespace
547 should be created, or it can be "host" to indicate that the PID name‐
548 space in which Buildah itself is being run should be reused, or it can
549 be the path to a PID namespace which is already in use by another
550 process.
551 --platform="OS/ARCH[/VARIANT]"
554 Set the OS/ARCH of the image to be pulled to the provided value instead
557 of using the current operating system and architecture of the host (for
558 example linux/arm).
559 OS/ARCH pairs are those used by the Go Programming Language. In sev‐
562 eral cases the ARCH value for a platform differs from one produced by
563 other tools such as the arch command. Valid OS and architecture name
564 combinations are listed as values for $GOOS and $GOARCH at
565 https://golang.org/doc/install/source#environment, and can also be
566 found by running go tool dist list.
567 While buildah from is happy to pull an image for any platform that ex‐
570 ists, buildah run will not be able to run binaries provided by that im‐
571 age without the help of emulation provided by packages like qemu-user-
572 static.
573 NOTE: The --platform option may not be used in combination with the
576 --arch, --os, or --variant options.
577 --pull
580 When the flag is enabled or set explicitly to true (with --pull=true),
583 attempt to pull the latest image from the registries listed in reg‐
584 istries.conf if a local image does not exist or the image is newer than
585 the one in storage. Raise an error if the image is not in any listed
586 registry and is not present locally.
587 If the flag is disabled (with --pull=false), do not pull the image from
590 the registry, use only the local version. Raise an error if the image
591 is not present locally.
592 If the pull flag is set to always (with --pull=always), pull the image
595 from the first registry it is found in as listed in registries.conf.
596 Raise an error if not found in the registries, even if the image is
597 present locally.
598 If the pull flag is set to never (with --pull=never), Do not pull the
601 image from the registry, use only the local version. Raise an error if
602 the image is not present locally.
603 Defaults to true.
606 --quiet, -q
609 If an image needs to be pulled from the registry, suppress progress
612 output.
613 --retry attempts
616 Number of times to retry in case of failure when performing pull of im‐
619 ages from registry.
620 Defaults to 3.
623 --retry-delay duration
626 Duration of delay between retry attempts in case of failure when per‐
629 forming pull of images from registry.
630 Defaults to 2s.
633 --security-opt=[]
636 Security Options
639 "label=user:USER" : Set the label user for the container
642 "label=role:ROLE" : Set the label role for the container
643 "label=type:TYPE" : Set the label type for the container
644 "label=level:LEVEL" : Set the label level for the container
645 "label=disable" : Turn off label confinement for the container
646 "no-new-privileges" : Not supported
647 "seccomp=unconfined" : Turn off seccomp confinement for the container
650 "seccomp=profile.json : White listed syscalls seccomp Json file to
651 be used as a seccomp filter
652 "apparmor=unconfined" : Turn off apparmor confinement for the container
655 "apparmor=your-profile" : Set the apparmor confinement profile for
656 the container
657 --shm-size=""
660 Size of /dev/shm. The format is <number><unit>. number must be greater
663 than 0. Unit is optional and can be b (bytes), k (kilobytes),
664 m(megabytes), or g (gigabytes). If you omit the unit, the system uses
665 bytes. If you omit the size entirely, the system uses 64m.
666 --tls-verify bool-value
669 Require HTTPS and verification of certificates when talking to con‐
672 tainer registries (defaults to true). TLS verification cannot be used
673 when talking to an insecure registry.
674 --ulimit type=soft-limit[:hard-limit]
677 Specifies resource limits to apply to processes launched during buildah
680 run. This option can be specified multiple times. Recognized resource
681 types include:
682 "core": maximum core dump size (ulimit -c)
683 "cpu": maximum CPU time (ulimit -t)
684 "data": maximum size of a process's data segment (ulimit -d)
685 "fsize": maximum size of new files (ulimit -f)
686 "locks": maximum number of file locks (ulimit -x)
687 "memlock": maximum amount of locked memory (ulimit -l)
688 "msgqueue": maximum amount of data in message queues (ulimit -q)
689 "nice": niceness adjustment (nice -n, ulimit -e)
690 "nofile": maximum number of open files (ulimit -n)
691 "nofile": maximum number of open files (1048576); when run by root
692 "nproc": maximum number of processes (ulimit -u)
693 "nproc": maximum number of processes (1048576); when run by root
694 "rss": maximum size of a process's (ulimit -m)
695 "rtprio": maximum real-time scheduling priority (ulimit -r)
696 "rttime": maximum amount of real-time execution between blocking
697 syscalls
698 "sigpending": maximum number of pending signals (ulimit -i)
699 "stack": maximum stack size (ulimit -s)
700 --userns how
703 Sets the configuration for user namespaces when the container is subse‐
706 quently used for buildah run. The configured value can be "" (the
707 empty string) or "container" to indicate that a new user namespace
708 should be created, it can be "host" to indicate that the user namespace
709 in which Buildah itself is being run should be reused, or it can be the
710 path to an user namespace which is already in use by another process.
711 --userns-gid-map mapping
714 Directly specifies a GID mapping which should be used to set ownership,
717 at the filesystem level, on the working container's contents. Commands
718 run when handling RUN instructions will default to being run in their
719 own user namespaces, configured using the UID and GID maps.
720 Entries in this map take the form of one or more colon-separated
723 triples of a starting in-container GID, a corresponding starting host-
724 level GID, and the number of consecutive IDs which the map entry repre‐
725 sents.
726 This option overrides the remap-gids setting in the options section of
729 /etc/containers/storage.conf.
730 If this option is not specified, but a global --userns-gid-map setting
733 is supplied, settings from the global option will be used.
734 --userns-gid-map-group mapping
737 Directly specifies a GID mapping which should be used to set ownership,
740 at the filesystem level, on the container's contents. Commands run us‐
741 ing buildah run will default to being run in their own user namespaces,
742 configured using the UID and GID maps.
743 Entries in this map take the form of one or more triples of a starting
746 in-container GID, a corresponding starting host-level GID, and the num‐
747 ber of consecutive IDs which the map entry represents.
748 This option overrides the remap-gids setting in the options section of
751 /etc/containers/storage.conf.
752 If this option is not specified, but a global --userns-gid-map setting
755 is supplied, settings from the global option will be used.
756 If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-
759 gid-map are specified, but --userns-uid-map is specified, the GID map
760 will be set to use the same numeric values as the UID map.
761 NOTE: When this option is specified by a rootless user, the specified
764 mappings are relative to the rootless usernamespace in the container,
765 rather than being relative to the host as it would be when run rootful.
766 --userns-gid-map-group group
769 Specifies that a GID mapping which should be used to set ownership, at
772 the filesystem level, on the container's contents, can be found in en‐
773 tries in the /etc/subgid file which correspond to the specified group.
774 Commands run using buildah run will default to being run in their own
775 user namespaces, configured using the UID and GID maps. If --userns-
776 uid-map-user is specified, but --userns-gid-map-group is not specified,
777 Buildah will assume that the specified user name is also a suitable
778 group name to use as the default setting for this option.
779 --userns-uid-map mapping
782 Directly specifies a UID mapping which should be used to set ownership,
785 at the filesystem level, on the working container's contents. Commands
786 run when handling RUN instructions will default to being run in their
787 own user namespaces, configured using the UID and GID maps.
788 Entries in this map take the form of one or more colon-separated
791 triples of a starting in-container UID, a corresponding starting host-
792 level UID, and the number of consecutive IDs which the map entry repre‐
793 sents.
794 This option overrides the remap-uids setting in the options section of
797 /etc/containers/storage.conf.
798 If this option is not specified, but a global --userns-uid-map setting
801 is supplied, settings from the global option will be used.
802 --userns-uid-map-user mapping
805 Directly specifies a UID mapping which should be used to set ownership,
808 at the filesystem level, on the container's contents. Commands run us‐
809 ing buildah run will default to being run in their own user namespaces,
810 configured using the UID and GID maps.
811 Entries in this map take the form of one or more triples of a starting
814 in-container UID, a corresponding starting host-level UID, and the num‐
815 ber of consecutive IDs which the map entry represents.
816 This option overrides the remap-uids setting in the options section of
819 /etc/containers/storage.conf.
820 If this option is not specified, but a global --userns-uid-map setting
823 is supplied, settings from the global option will be used.
824 If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-
827 uid-map are specified, but --userns-gid-map is specified, the UID map
828 will be set to use the same numeric values as the GID map.
829 NOTE: When this option is specified by a rootless user, the specified
832 mappings are relative to the rootless usernamespace in the container,
833 rather than being relative to the host as it would be when run rootful.
834 --userns-uid-map-user user
837 Specifies that a UID mapping which should be used to set ownership, at
840 the filesystem level, on the container's contents, can be found in en‐
841 tries in the /etc/subuid file which correspond to the specified user.
842 Commands run using buildah run will default to being run in their own
843 user namespaces, configured using the UID and GID maps. If --userns-
844 gid-map-group is specified, but --userns-uid-map-user is not specified,
845 Buildah will assume that the specified group name is also a suitable
846 user name to use as the default setting for this option.
847 --uts how
850 Sets the configuration for UTS namespaces when the container is subse‐
853 quently used for buildah run. The configured value can be "" (the
854 empty string) or "container" to indicate that a new UTS namespace
855 should be created, or it can be "host" to indicate that the UTS name‐
856 space in which Buildah itself is being run should be reused, or it can
857 be the path to a UTS namespace which is already in use by another
858 process.
859 --variant=""
862 Set the architecture variant of the image to be pulled.
865 --volume, -v[=[HOST-DIR:CONTAINER-DIR[:OPTIONS]]]
868 Create a bind mount. If you specify, -v /HOST-DIR:/CONTAINER-DIR, Buil‐
871 dah
872 bind mounts /HOST-DIR in the host to /CONTAINER-DIR in the Buildah
873 container. The OPTIONS are a comma delimited list and can be: [1]
874 ⟨#Footnote1⟩
875 • [rw|ro]
878 • [U]
880 • [z|Z|O]
882 • [[r]shared|[r]slave|[r]private|[r]unbindable]
884 The CONTAINER-DIR must be an absolute path such as /src/docs. The HOST-
888 DIR must be an absolute path as well. Buildah bind-mounts the HOST-DIR
889 to the path you specify. For example, if you supply /foo as the host
890 path, Buildah copies the contents of /foo to the container filesystem
891 on the host and bind mounts that into the container.
892 You can specify multiple -v options to mount one or more mounts to a
895 container.
896 Write Protected Volume Mounts
899 You can add the :ro or :rw suffix to a volume to mount it read-only or
902 read-write mode, respectively. By default, the volumes are mounted
903 read-write. See examples.
904 Chowning Volume Mounts
907 By default, Buildah does not change the owner and group of source vol‐
910 ume directories mounted into containers. If a container is created in a
911 new user namespace, the UID and GID in the container may correspond to
912 another UID and GID on the host.
913 The :U suffix tells Buildah to use the correct host UID and GID based
916 on the UID and GID within the container, to change the owner and group
917 of the source volume.
918 Labeling Volume Mounts
921 Labeling systems like SELinux require that proper labels are placed on
924 volume content mounted into a container. Without a label, the security
925 system might prevent the processes running inside the container from
926 using the content. By default, Buildah does not change the labels set
927 by the OS.
928 To change a label in the container context, you can add either of two
931 suffixes :z or :Z to the volume mount. These suffixes tell Buildah to
932 relabel file objects on the shared volumes. The z option tells Buildah
933 that two containers share the volume content. As a result, Buildah la‐
934 bels the content with a shared content label. Shared volume labels al‐
935 low all containers to read/write content. The Z option tells Buildah
936 to label the content with a private unshared label. Only the current
937 container can use a private volume.
938 Overlay Volume Mounts
941 The :O flag tells Buildah to mount the directory from the host as a
944 temporary storage using the Overlay file system. The RUN command con‐
945 tainers are allowed to modify contents within the mountpoint and are
946 stored in the container storage in a separate directory. In Overlay FS
947 terms the source directory will be the lower, and the container storage
948 directory will be the upper. Modifications to the mount point are de‐
949 stroyed when the RUN command finishes executing, similar to a tmpfs
950 mount point.
951 Any subsequent execution of RUN commands sees the original source di‐
954 rectory content, any changes from previous RUN commands no longer ex‐
955 ist.
956 One use case of the overlay mount is sharing the package cache from the
959 host into the container to allow speeding up builds.
960 Note:
963 - 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.
966 On SELinux systems, labels in the source directory need to be readable by the container label. If not, SELinux container separation must be disabled for the container to work.
967 - 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.
968 By default bind mounted volumes are private. That means any mounts done
972 inside container will not be visible on the host and vice versa. This
973 behavior can be changed by specifying a volume mount propagation prop‐
974 erty.
975 When the mount propagation policy is set to shared, any mounts com‐
978 pleted inside the container on that volume will be visible to both the
979 host and container. When the mount propagation policy is set to slave,
980 one way mount propagation is enabled and any mounts completed on the
981 host for that volume will be visible only inside of the container. To
982 control the mount propagation property of the volume use the
983 :[r]shared, :[r]slave, [r]private or [r]unbindablepropagation flag. The
984 propagation property can be specified only for bind mounted volumes and
985 not for internal volumes or named volumes. For mount propagation to
986 work on the source mount point (the mount point where source dir is
987 mounted on) it has to have the right propagation properties. For shared
988 volumes, the source mount point has to be shared. And for slave vol‐
989 umes, the source mount has to be either shared or slave. [1] ⟨#Foot‐
990 note1⟩
991 Use df <source-dir> to determine the source mount and then use findmnt
994 -o TARGET,PROPAGATION <source-mount-dir> to determine propagation prop‐
995 erties of source mount, if findmnt utility is not available, the source
996 mount point can be determined by looking at the mount entry in
997 /proc/self/mountinfo. Look at optional fields and see if any propaga‐
998 tion properties are specified. shared:X means the mount is shared,
999 master:X means the mount is slave and if nothing is there that means
1000 the mount is private. [1] ⟨#Footnote1⟩
1001 To change propagation properties of a mount point use the mount com‐
1004 mand. For example, to bind mount the source directory /foo do mount
1005 --bind /foo /foo and mount --make-private --make-shared /foo. This will
1006 convert /foo into a shared mount point. The propagation properties of
1007 the source mount can be changed directly. For instance if / is the
1008 source mount for /foo, then use mount --make-shared / to convert / into
1009 a shared mount.
1010
1013 buildah from --pull imagename
1014 buildah from --pull docker://myregistry.example.com/imagename
1017 buildah from docker-daemon:imagename:imagetag
1020 buildah from --name mycontainer docker-archive:filename
1023 buildah from oci-archive:filename
1026 buildah from --name mycontainer dir:directoryname
1029 buildah from --pull-always --name "mycontainer" myregistry.exam‐
1032 ple.com/imagename
1033 buildah from --tls-verify=false myregistry/myrepository/imagename:im‐
1036 agetag
1037 buildah from --creds=myusername:mypassword --cert-dir ~/auth myreg‐
1040 istry/myrepository/imagename:imagetag
1041 buildah from --authfile=/tmp/auths/myauths.json myregistry/myreposi‐
1044 tory/imagename:imagetag
1045 buildah from --memory 40m --cpu-shares 2 --cpuset-cpus 0,2 --security-
1048 opt label=level:s0:c100,c200 myregistry/myrepository/imagename:imagetag
1049 buildah from --ulimit nofile=1024:1028 --cgroup-parent
1052 /path/to/cgroup/parent myregistry/myrepository/imagename:imagetag
1053 buildah from --volume /home/test:/myvol:ro,Z myregistry/myreposi‐
1056 tory/imagename:imagetag
1057 buildah from -v /home/test:/myvol:z,U myregistry/myrepository/image‐
1060 name:imagetag
1061 buildah from -v /var/lib/yum:/var/lib/yum:O myregistry/myrepository/im‐
1064 agename:imagetag
1065 buildah from --arch=arm --variant v7 myregistry/myrepository/image‐
1068 name:imagetag
1069
1072 BUILD_REGISTRY_SOURCES
1073 BUILD_REGISTRY_SOURCES, if set, is treated as a JSON object which con‐
1076 tains lists of registry names under the keys insecureRegistries,
1077 blockedRegistries, and allowedRegistries.
1078 When pulling an image from a registry, if the name of the registry
1081 matches any of the items in the blockedRegistries list, the image pull
1082 attempt is denied. If there are registries in the allowedRegistries
1083 list, and the registry's name is not in the list, the pull attempt is
1084 denied.
1085 TMPDIR The TMPDIR environment variable allows the user to specify where
1088 temporary files are stored while pulling and pushing images. Defaults
1089 to '/var/tmp'.
1090
1093 registries.conf (/etc/containers/registries.conf)
1094 registries.conf is the configuration file which specifies which con‐
1097 tainer registries should be consulted when completing image names which
1098 do not include a registry or domain portion.
1099 policy.json (/etc/containers/policy.json)
1102 Signature policy file. This defines the trust policy for container im‐
1105 ages. Controls which container registries can be used for image, and
1106 whether or not the tool should trust the images.
1107
1110 buildah(1), buildah-pull(1), buildah-login(1), docker-login(1), name‐
1111 spaces(7), pid_namespaces(7), containers-policy.json(5), containers-
1112 registries.conf(5), user_namespaces(7), containers.conf(5)
1113
1116 1: The Buildah project is committed to inclusivity, a core value of
1117 open source. The master and slave mount propagation terminology used
1118 here is problematic and divisive, and should be changed. However, these
1119 terms are currently used within the Linux kernel and must be used as-is
1120 at this time. When the kernel maintainers rectify this usage, Buildah
1121 will follow suit immediately.
1122buildah March 2017 buildah-from(1)