1podman-build(1) General Commands Manual podman-build(1)
2
3
4
6 podman-build - Build a container image using a Containerfile
7
8
10 podman build [options] [context]
11
12
13 podman image build [options] [context]
14
15
17 podman build Builds an image using instructions from one or more Con‐
18 tainerfiles or Dockerfiles and a specified build context directory. A
19 Containerfile uses the same syntax as a Dockerfile internally. For this
20 document, a file referred to as a Containerfile can be a file named ei‐
21 ther 'Containerfile' or 'Dockerfile'.
22
23
24 The build context directory can be specified as the http(s) URL of an
25 archive, git repository or Containerfile.
26
27
28 When invoked with -f and a path to a Containerfile, with no explicit
29 CONTEXT directory, Podman uses the Containerfile's parent directory as
30 its build context.
31
32
33 Containerfiles ending with a ".in" suffix are preprocessed via CPP(1).
34 This can be useful to decompose Containerfiles into several reusable
35 parts that can be used via CPP's #include directive. Containerfiles
36 ending in .in are restricted to no comment lines unless they are CPP
37 commands. Note, a Containerfile.in file can still be used by other
38 tools when manually preprocessing them via cpp -E.
39
40
41 When the URL is an archive, the contents of the URL is downloaded to a
42 temporary location and extracted before execution.
43
44
45 When the URL is a Containerfile, the Containerfile is downloaded to a
46 temporary location.
47
48
49 When a Git repository is set as the URL, the repository is cloned lo‐
50 cally and then set as the context.
51
52
53 NOTE: podman build uses code sourced from the Buildah project to build
54 container images. This Buildah code creates Buildah containers for the
55 RUN options in container storage. In certain situations, when the pod‐
56 man build crashes or users kill the podman build process, these exter‐
57 nal containers can be left in container storage. Use the podman ps
58 --all --storage command to see these containers. External containers
59 can be removed with the podman rm --storage command.
60
61
62 podman buildx build command is an alias of podman build. Not all
63 buildx build features are available in Podman. The buildx build option
64 is provided for scripting compatibility.
65
66
68 --add-host=host:ip
69 Add a custom host-to-IP mapping (host:ip)
70
71
72 Add a line to /etc/hosts. The format is hostname:ip. The --add-host op‐
73 tion can be set multiple times. Conflicts with the --no-hosts option.
74
75
76 --all-platforms
77 Instead of building for a set of platforms specified using the --plat‐
78 form option, inspect the build's base images, and build for all of the
79 platforms for which they are all available. Stages that use scratch as
80 a starting point can not be inspected, so at least one non-scratch
81 stage must be present for detection to work usefully.
82
83
84 --annotation=annotation
85 Add an image annotation (e.g. annotation=value) to the image metadata.
86 Can be used multiple times.
87
88
89 Note: this information is not present in Docker image formats, so it is
90 discarded when writing images in Docker formats.
91
92
93 --arch=arch
94 Set the architecture of the image to be built, and that of the base im‐
95 age to be pulled, if the build uses one, to the provided value instead
96 of using the architecture of the build host. Unless overridden, subse‐
97 quent lookups of the same image in the local storage matches this ar‐
98 chitecture, regardless of the host. (Examples: arm, arm64, 386, amd64,
99 ppc64le, s390x)
100
101
102 --authfile=path
103 Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
104 ers/auth.json on Linux, and $HOME/.config/containers/auth.json on Win‐
105 dows/macOS. The file is created by podman login. If the authorization
106 state is not found there, $HOME/.docker/config.json is checked, which
107 is set using docker login.
108
109
110 Note: There is also the option to override the default path of the au‐
111 thentication file by setting the REGISTRY_AUTH_FILE environment vari‐
112 able. This can be done with export REGISTRY_AUTH_FILE=path.
113
114
115 --build-arg=arg=value
116 Specifies a build argument and its value, which is interpolated in in‐
117 structions read from the Containerfiles in the same way that environ‐
118 ment variables are, but which are not added to environment variable
119 list in the resulting image's configuration.
120
121
122 --build-arg-file=path
123 Specifies a file containing lines of build arguments of the form
124 arg=value. The suggested file name is argfile.conf.
125
126
127 Comment lines beginning with # are ignored, along with blank lines.
128 All others must be of the arg=value format passed to --build-arg.
129
130
131 If several arguments are provided via the --build-arg-file and --build-
132 arg options, the build arguments are merged across all of the provided
133 files and command line arguments.
134
135
136 Any file provided in a --build-arg-file option is read before the argu‐
137 ments supplied via the --build-arg option.
138
139
140 When a given argument name is specified several times, the last in‐
141 stance is the one that is passed to the resulting builds. This means
142 --build-arg values always override those in a --build-arg-file.
143
144
145 --build-context=name=value
146 Specify an additional build context using its short name and its loca‐
147 tion. Additional build contexts can be referenced in the same manner
148 as we access different stages in COPY instruction.
149
150
151 Valid values are:
152
153
154 • Local directory – e.g. --build-context
155 project2=../path/to/project2/src (This option is not available
156 with the remote Podman client. On Podman machine setup (i.e
157 macOS and Winows) path must exists on the machine VM)
158
159 • HTTP URL to a tarball – e.g. --build-context src=https://exam‐
160 ple.org/releases/src.tar
161
162 • Container image – specified with a container-image:// prefix,
163 e.g. --build-context alpine=container-image://alpine:3.15,
164 (also accepts docker://, docker-image://)
165
166
167
168 On the Containerfile side, reference the build context on all commands
169 that accept the “from” parameter. Here’s how that might look:
170
171
172 FROM [name]
173 COPY --from=[name] ...
174 RUN --mount=from=[name] …
175
176
177
178 The value of [name] is matched with the following priority order:
179
180
181 • Named build context defined with --build-context [name]=..
182
183 • Stage defined with AS [name] inside Containerfile
184
185 • Image [name], either local or in a remote registry
186
187
188
189 --cache-from
190 Repository to utilize as a potential cache source. When specified,
191 Buildah tries to look for cache images in the specified repository and
192 attempts to pull cache images instead of actually executing the build
193 steps locally. Buildah only attempts to pull previously cached images
194 if they are considered as valid cache hits.
195
196
197 Use the --cache-to option to populate a remote repository with cache
198 content.
199
200
201 Example
202
203
204 # populate a cache and also consult it
205 buildah build -t test --layers --cache-to registry/myrepo/cache --cache-from registry/myrepo/cache .
206
207
208
209 Note: --cache-from option is ignored unless --layers is specified.
210
211
212 --cache-to
213 Set this flag to specify a remote repository that is used to store
214 cache images. Buildah attempts to push newly built cache image to the
215 remote repository.
216
217
218 Note: Use the --cache-from option in order to use cache content in a
219 remote repository.
220
221
222 Example
223
224
225 # populate a cache and also consult it
226 buildah build -t test --layers --cache-to registry/myrepo/cache --cache-from registry/myrepo/cache .
227
228
229
230 Note: --cache-to option is ignored unless --layers is specified.
231
232
233 --cache-ttl
234 Limit the use of cached images to only consider images with created
235 timestamps less than duration ago. For example if --cache-ttl=1h is
236 specified, Buildah considers intermediate cache images which are cre‐
237 ated under the duration of one hour, and intermediate cache images out‐
238 side this duration is ignored.
239
240
241 Note: Setting --cache-ttl=0 manually is equivalent to using --no-cache
242 in the implementation since this means that the user dones not want to
243 use cache at all.
244
245
246 --cap-add=CAP_xxx
247 When executing RUN instructions, run the command specified in the in‐
248 struction with the specified capability added to its capability set.
249 Certain capabilities are granted by default; this option can be used to
250 add more.
251
252
253 --cap-drop=CAP_xxx
254 When executing RUN instructions, run the command specified in the in‐
255 struction with the specified capability removed from its capability
256 set. The CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_FOWNER, CAP_FSETID,
257 CAP_KILL, CAP_NET_BIND_SERVICE, CAP_SETFCAP, CAP_SETGID, CAP_SETPCAP,
258 and CAP_SETUID capabilities are granted by default; this option can be
259 used to remove them.
260
261
262 If a capability is specified to both the --cap-add and --cap-drop op‐
263 tions, it is dropped, regardless of the order in which the options were
264 given.
265
266
267 --cert-dir=path
268 Use certificates at path (*.crt, *.cert, *.key) to connect to the reg‐
269 istry. (Default: /etc/containers/certs.d) For details, see containers-
270 certs.d(5). (This option is not available with the remote Podman
271 client, including Mac and Windows (excluding WSL2) machines)
272
273
274 --cgroup-parent=path
275 Path to cgroups under which the cgroup for the container is created. If
276 the path is not absolute, the path is considered to be relative to the
277 cgroups path of the init process. Cgroups are created if they do not
278 already exist.
279
280
281 --cgroupns=how
282 Sets the configuration for cgroup namespaces when handling RUN instruc‐
283 tions. The configured value can be "" (the empty string) or "private"
284 to indicate that a new cgroup namespace is created, or it can be "host"
285 to indicate that the cgroup namespace in which buildah itself is being
286 run is reused.
287
288
289 --compress
290 This option is added to be aligned with other containers CLIs. Podman
291 doesn't communicate with a daemon or a remote server. Thus, compress‐
292 ing the data before sending it is irrelevant to Podman. (This option is
293 not available with the remote Podman client, including Mac and Windows
294 (excluding WSL2) machines)
295
296
297 --cpp-flag=flags
298 Set additional flags to pass to the C Preprocessor cpp(1). Container‐
299 files ending with a ".in" suffix is preprocessed via cpp(1). This op‐
300 tion can be used to pass additional flags to cpp.Note: You can also set
301 default CPPFLAGS by setting the BUILDAH_CPPFLAGS environment variable
302 (e.g., export BUILDAH_CPPFLAGS="-DDEBUG").
303
304
305 --cpu-period=limit
306 Set the CPU period for the Completely Fair Scheduler (CFS), which is a
307 duration in microseconds. Once the container's CPU quota is used up, it
308 will not be scheduled to run until the current period ends. Defaults to
309 100000 microseconds.
310
311
312 On some systems, changing the resource limits may not be allowed for
313 non-root users. For more details, see https://github.com/contain‐
314 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
315 source-limits-fails-with-a-permissions-error
316
317
318 This option is not supported on cgroups V1 rootless systems.
319
320
321 --cpu-quota=limit
322 Limit the CPU Completely Fair Scheduler (CFS) quota.
323
324
325 Limit the container's CPU usage. By default, containers run with the
326 full CPU resource. The limit is a number in microseconds. If a number
327 is provided, the container is allowed to use that much CPU time until
328 the CPU period ends (controllable via --cpu-period).
329
330
331 On some systems, changing the resource limits may not be allowed for
332 non-root users. For more details, see https://github.com/contain‐
333 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
334 source-limits-fails-with-a-permissions-error
335
336
337 This option is not supported on cgroups V1 rootless systems.
338
339
340 --cpu-shares, -c=shares
341 CPU shares (relative weight).
342
343
344 By default, all containers get the same proportion of CPU cycles. This
345 proportion can be modified by changing the container's CPU share
346 weighting relative to the combined weight of all the running contain‐
347 ers. Default weight is 1024.
348
349
350 The proportion only applies when CPU-intensive processes are running.
351 When tasks in one container are idle, other containers can use the
352 left-over CPU time. The actual amount of CPU time varies depending on
353 the number of containers running on the system.
354
355
356 For example, consider three containers, one has a cpu-share of 1024 and
357 two others have a cpu-share setting of 512. When processes in all three
358 containers attempt to use 100% of CPU, the first container receives 50%
359 of the total CPU time. If a fourth container is added with a cpu-share
360 of 1024, the first container only gets 33% of the CPU. The remaining
361 containers receive 16.5%, 16.5% and 33% of the CPU.
362
363
364 On a multi-core system, the shares of CPU time are distributed over all
365 CPU cores. Even if a container is limited to less than 100% of CPU
366 time, it can use 100% of each individual CPU core.
367
368
369 For example, consider a system with more than three cores. If the con‐
370 tainer C0 is started with --cpu-shares=512 running one process, and an‐
371 other container C1 with --cpu-shares=1024 running two processes, this
372 can result in the following division of CPU shares:
373
374
375 ┌────┬───────────┬─────┬──────────────┐
376 │PID │ container │ CPU │ CPU share │
377 ├────┼───────────┼─────┼──────────────┤
378 │100 │ C0 │ 0 │ 100% of CPU0 │
379 ├────┼───────────┼─────┼──────────────┤
380 │101 │ C1 │ 1 │ 100% of CPU1 │
381 ├────┼───────────┼─────┼──────────────┤
382 │102 │ C1 │ 2 │ 100% of CPU2 │
383 └────┴───────────┴─────┴──────────────┘
384
385 On some systems, changing the resource limits may not be allowed for
386 non-root users. For more details, see https://github.com/contain‐
387 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
388 source-limits-fails-with-a-permissions-error
389
390
391 This option is not supported on cgroups V1 rootless systems.
392
393
394 --cpuset-cpus=number
395 CPUs in which to allow execution. Can be specified as a comma-separated
396 list (e.g. 0,1), as a range (e.g. 0-3), or any combination thereof
397 (e.g. 0-3,7,11-15).
398
399
400 On some systems, changing the resource limits may not be allowed for
401 non-root users. For more details, see https://github.com/contain‐
402 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
403 source-limits-fails-with-a-permissions-error
404
405
406 This option is not supported on cgroups V1 rootless systems.
407
408
409 --cpuset-mems=nodes
410 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effec‐
411 tive on NUMA systems.
412
413
414 If there are four memory nodes on the system (0-3), use --cpuset-
415 mems=0,1 then processes in the container only uses memory from the
416 first two memory nodes.
417
418
419 On some systems, changing the resource limits may not be allowed for
420 non-root users. For more details, see https://github.com/contain‐
421 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
422 source-limits-fails-with-a-permissions-error
423
424
425 This option is not supported on cgroups V1 rootless systems.
426
427
428 --creds=[username[:password]]
429 The [username[:password]] to use to authenticate with the registry, if
430 required. If one or both values are not supplied, a command line
431 prompt appears and the value can be entered. The password is entered
432 without echo.
433
434
435 Note that the specified credentials are only used to authenticate
436 against target registries. They are not used for mirrors or when the
437 registry gets rewritten (see containers-registries.conf(5)); to authen‐
438 ticate against those consider using a containers-auth.json(5) file.
439
440
441 --cw=options
442 Produce an image suitable for use as a confidential workload running in
443 a trusted execution environment (TEE) using krun (i.e., crun built with
444 the libkrun feature enabled and invoked as krun). Instead of the con‐
445 ventional contents, the root filesystem of the image will contain an
446 encrypted disk image and configuration information for krun.
447
448
449 The value for options is a comma-separated list of key=value pairs,
450 supplying configuration information which is needed for producing the
451 additional data which will be included in the container image.
452
453
454 Recognized keys are:
455
456
457 attestation_url: The location of a key broker / attestation server. If
458 a value is specified, the new image's workload ID, along with the
459 passphrase used to encrypt the disk image, will be registered with the
460 server, and the server's location will be stored in the container im‐
461 age. At run-time, krun is expected to contact the server to retrieve
462 the passphrase using the workload ID, which is also stored in the con‐
463 tainer image. If no value is specified, a passphrase value must be
464 specified.
465
466
467 cpus: The number of virtual CPUs which the image expects to be run with
468 at run-time. If not specified, a default value will be supplied.
469
470
471 firmware_library: The location of the libkrunfw-sev shared library. If
472 not specified, buildah checks for its presence in a number of hard-
473 coded locations.
474
475
476 memory: The amount of memory which the image expects to be run with at
477 run-time, as a number of megabytes. If not specified, a default value
478 will be supplied.
479
480
481 passphrase: The passphrase to use to encrypt the disk image which will
482 be included in the container image. If no value is specified, but an
483 attestation_url value is specified, a randomly-generated passphrase
484 will be used. The authors recommend setting an attestation_url but not
485 a passphrase.
486
487
488 slop: Extra space to allocate for the disk image compared to the size
489 of the container image's contents, expressed either as a percentage
490 (..%) or a size value (bytes, or larger units if suffixes like KB or MB
491 are present), or a sum of two or more such specifications. If not
492 specified, buildah guesses that 25% more space than the contents will
493 be enough, but this option is provided in case its guess is wrong.
494
495
496 type: The type of trusted execution environment (TEE) which the image
497 should be marked for use with. Accepted values are "SEV" (AMD Secure
498 Encrypted Virtualization - Encrypted State) and "SNP" (AMD Secure En‐
499 crypted Virtualization - Secure Nested Paging). If not specified, de‐
500 faults to "SNP".
501
502
503 workload_id: A workload identifier which will be recorded in the con‐
504 tainer image, to be used at run-time for retrieving the passphrase
505 which was used to encrypt the disk image. If not specified, a semi-
506 random value will be derived from the base image's image ID.
507
508
509 This option is not supported on the remote client, including Mac and
510 Windows (excluding WSL2) machines.
511
512
513 --decryption-key=key[:passphrase]
514 The [key[:passphrase]] to be used for decryption of images. Key can
515 point to keys and/or certificates. Decryption is tried with all keys.
516 If the key is protected by a passphrase, it is required to be passed in
517 the argument and omitted otherwise.
518
519
520 --device=host-device[:container-device][:permissions]
521 Add a host device to the container. Optional permissions parameter can
522 be used to specify device permissions by combining r for read, w for
523 write, and m for mknod(2).
524
525
526 Example: --device=/dev/sdc:/dev/xvdc:rwm.
527
528
529 Note: if host-device is a symbolic link then it is resolved first. The
530 container only stores the major and minor numbers of the host device.
531
532
533 Podman may load kernel modules required for using the specified device.
534 The devices that Podman loads modules for when necessary are:
535 /dev/fuse.
536
537
538 In rootless mode, the new device is bind mounted in the container from
539 the host rather than Podman creating it within the container space. Be‐
540 cause the bind mount retains its SELinux label on SELinux systems, the
541 container can get permission denied when accessing the mounted device.
542 Modify SELinux settings to allow containers to use all device labels
543 via the following command:
544
545
546 $ sudo setsebool -P container_use_devices=true
547
548
549 Note: if the user only has access rights via a group, accessing the de‐
550 vice from inside a rootless container fails. The crun(1) runtime offers
551 a workaround for this by adding the option --annotation
552 run.oci.keep_original_groups=1.
553
554
555 --disable-compression, -D
556 Don't compress filesystem layers when building the image unless it is
557 required by the location where the image is being written. This is the
558 default setting, because image layers are compressed automatically when
559 they are pushed to registries, and images being written to local stor‐
560 age only need to be decompressed again to be stored. Compression can
561 be forced in all cases by specifying --disable-compression=false.
562
563
564 --disable-content-trust
565 This is a Docker-specific option to disable image verification to a
566 container registry and is not supported by Podman. This option is a
567 NOOP and provided solely for scripting compatibility.
568
569
570 --dns=ipaddr
571 Set custom DNS servers.
572
573
574 This option can be used to override the DNS configuration passed to the
575 container. Typically this is necessary when the host DNS configuration
576 is invalid for the container (e.g., 127.0.0.1). When this is the case
577 the --dns flag is necessary for every run.
578
579
580 The special value none can be specified to disable creation of /etc/re‐
581 solv.conf in the container by Podman. The /etc/resolv.conf file in the
582 image is used without changes.
583
584
585 This option cannot be combined with --network that is set to none.
586
587
588 Note: this option takes effect only during RUN instructions in the
589 build. It does not affect /etc/resolv.conf in the final image.
590
591
592 --dns-option=option
593 Set custom DNS options to be used during the build.
594
595
596 --dns-search=domain
597 Set custom DNS search domains to be used during the build.
598
599
600 --env=env[=value]
601 Add a value (e.g. env=value) to the built image. Can be used multiple
602 times. If neither = nor a value are specified, but env is set in the
603 current environment, the value from the current environment is added to
604 the image. To remove an environment variable from the built image, use
605 the --unsetenv option.
606
607
608 --file, -f=Containerfile
609 Specifies a Containerfile which contains instructions for building the
610 image, either a local file or an http or https URL. If more than one
611 Containerfile is specified, FROM instructions are only be accepted from
612 the last specified file.
613
614
615 If a build context is not specified, and at least one Containerfile is
616 a local file, the directory in which it resides is used as the build
617 context.
618
619
620 Specifying the option -f - causes the Containerfile contents to be read
621 from stdin.
622
623
624 --force-rm
625 Always remove intermediate containers after a build, even if the build
626 fails (default true).
627
628
629 --format
630 Control the format for the built image's manifest and configuration
631 data. Recognized formats include oci (OCI image-spec v1.0, the de‐
632 fault) and docker (version 2, using schema format 2 for the manifest).
633
634
635 Note: You can also override the default format by setting the BUIL‐
636 DAH_FORMAT environment variable. export BUILDAH_FORMAT=docker
637
638
639 --from
640 Overrides the first FROM instruction within the Containerfile. If
641 there are multiple FROM instructions in a Containerfile, only the first
642 is changed.
643
644
645 With the remote podman client, not all container transports work as ex‐
646 pected. For example, oci-archive:/x.tar references /x.tar on the remote
647 machine instead of on the client. When using podman remote clients it
648 is best to restrict use to containers-storage, and docker:// trans‐
649 ports.
650
651
652 --group-add=group | keep-groups
653 Assign additional groups to the primary user running within the con‐
654 tainer process.
655
656
657 • keep-groups is a special value that tells Buildah to keep the
658 supplementary group access.
659
660
661
662 Allows container to use the user's supplementary group access. If file
663 systems or devices are only accessible by the rootless user's group,
664 this flag tells the OCI runtime to pass the group access into the con‐
665 tainer. Currently only available with the crun OCI runtime. Note: keep-
666 groups is exclusive, other groups cannot be specified with this flag.
667
668
669 --help, -h
670 Print usage statement
671
672
673 --hooks-dir=path
674 Each *.json file in the path configures a hook for buildah build con‐
675 tainers. For more details on the syntax of the JSON files and the se‐
676 mantics of hook injection. Buildah currently support both the 1.0.0 and
677 0.1.0 hook schemas, although the 0.1.0 schema is deprecated.
678
679
680 This option may be set multiple times; paths from later options have
681 higher precedence.
682
683
684 For the annotation conditions, buildah uses any annotations set in the
685 generated OCI configuration.
686
687
688 For the bind-mount conditions, only mounts explicitly requested by the
689 caller via --volume are considered. Bind mounts that buildah inserts by
690 default (e.g. /dev/shm) are not considered.
691
692
693 If --hooks-dir is unset for root callers, Buildah currently defaults to
694 /usr/share/containers/oci/hooks.d and /etc/containers/oci/hooks.d in
695 order of increasing precedence. Using these defaults is deprecated. Mi‐
696 grate to explicitly setting --hooks-dir.
697
698
699 --http-proxy
700 By default proxy environment variables are passed into the container if
701 set for the Podman process. This can be disabled by setting the value
702 to false. The environment variables passed in include http_proxy,
703 https_proxy, ftp_proxy, no_proxy, and also the upper case versions of
704 those. This option is only needed when the host system must use a proxy
705 but the container does not use any proxy. Proxy environment variables
706 specified for the container in any other way overrides the values that
707 have been passed through from the host. (Other ways to specify the
708 proxy for the container include passing the values with the --env flag,
709 or hard coding the proxy environment at container build time.) When
710 used with the remote client it uses the proxy environment variables
711 that are set on the server process.
712
713
714 Defaults to true.
715
716
717 --identity-label
718 Adds default identity label io.buildah.version if set. (default true).
719
720
721 --ignorefile
722 Path to an alternative .containerignore file.
723
724
725 --iidfile=ImageIDfile
726 Write the built image's ID to the file. When --platform is specified
727 more than once, attempting to use this option triggers an error.
728
729
730 --ipc=how
731 Sets the configuration for IPC namespaces when handling RUN instruc‐
732 tions. The configured value can be "" (the empty string) or "con‐
733 tainer" to indicate that a new IPC namespace is created, or it can be
734 "host" to indicate that the IPC namespace in which podman itself is be‐
735 ing run is reused, or it can be the path to an IPC namespace which is
736 already in use by another process.
737
738
739 --isolation=type
740 Controls what type of isolation is used for running processes as part
741 of RUN instructions. Recognized types include oci (OCI-compatible run‐
742 time, the default), rootless (OCI-compatible runtime invoked using a
743 modified configuration and its --rootless option enabled, with --no-
744 new-keyring --no-pivot added to its create invocation, with network and
745 UTS namespaces disabled, and IPC, PID, and user namespaces enabled; the
746 default for unprivileged users), and chroot (an internal wrapper that
747 leans more toward chroot(1) than container technology).
748
749
750 Note: You can also override the default isolation type by setting the
751 BUILDAH_ISOLATION environment variable. export BUILDAH_ISOLATION=oci
752
753
754 --jobs=number
755 Run up to N concurrent stages in parallel. If the number of jobs is
756 greater than 1, stdin is read from /dev/null. If 0 is specified, then
757 there is no limit in the number of jobs that run in parallel.
758
759
760 --label=label
761 Add an image label (e.g. label=value) to the image metadata. Can be
762 used multiple times.
763
764
765 Users can set a special LABEL io.containers.capabilities=CAP1,CAP2,CAP3
766 in a Containerfile that specifies the list of Linux capabilities re‐
767 quired for the container to run properly. This label specified in a
768 container image tells Podman to run the container with just these capa‐
769 bilities. Podman launches the container with just the specified capa‐
770 bilities, as long as this list of capabilities is a subset of the de‐
771 fault list.
772
773
774 If the specified capabilities are not in the default set, Podman prints
775 an error message and runs the container with the default capabilities.
776
777
778 --layer-label=label[=value]
779 Add an intermediate image label (e.g. label=value) to the intermediate
780 image metadata. It can be used multiple times.
781
782
783 If label is named, but neither = nor a value is provided, then the la‐
784 bel is set to an empty value.
785
786
787 --layers
788 Cache intermediate images during the build process (Default is true).
789
790
791 Note: You can also override the default value of layers by setting the
792 BUILDAH_LAYERS environment variable. export BUILDAH_LAYERS=true
793
794
795 --logfile=filename
796 Log output which is sent to standard output and standard error to the
797 specified file instead of to standard output and standard error. This
798 option is not supported on the remote client, including Mac and Windows
799 (excluding WSL2) machines.
800
801
802 --logsplit=bool-value
803 If --logfile and --platform are specified, the --logsplit option allows
804 end-users to split the log file for each platform into different files
805 in the following format: ${logfile}_${platform-os}_${platform-arch}.
806 This option is not supported on the remote client, including Mac and
807 Windows (excluding WSL2) machines.
808
809
810 --manifest=manifest
811 Name of the manifest list to which the image is added. Creates the man‐
812 ifest list if it does not exist. This option is useful for building
813 multi architecture images.
814
815
816 --memory, -m=number[unit]
817 Memory limit. A unit can be b (bytes), k (kibibytes), m (mebibytes), or
818 g (gibibytes).
819
820
821 Allows the memory available to a container to be constrained. If the
822 host supports swap memory, then the -m memory setting can be larger
823 than physical RAM. If a limit of 0 is specified (not using -m), the
824 container's memory is not limited. The actual limit may be rounded up
825 to a multiple of the operating system's page size (the value is very
826 large, that's millions of trillions).
827
828
829 This option is not supported on cgroups V1 rootless systems.
830
831
832 --memory-swap=number[unit]
833 A limit value equal to memory plus swap. A unit can be b (bytes), k
834 (kibibytes), m (mebibytes), or g (gibibytes).
835
836
837 Must be used with the -m (--memory) flag. The argument value must be
838 larger than that of
839 -m (--memory) By default, it is set to double the value of --memory.
840
841
842 Set number to -1 to enable unlimited swap.
843
844
845 This option is not supported on cgroups V1 rootless systems.
846
847
848 --network=mode, --net
849 Sets the configuration for network namespaces when handling RUN in‐
850 structions.
851
852
853 Valid mode values are:
854
855
856 • none: no networking.
857
858 • host: use the Podman host network stack. Note: the host mode
859 gives the container full access to local system services such
860 as D-bus and is therefore considered insecure.
861
862 • ns:path: path to a network namespace to join.
863
864 • private: create a new namespace for the container (default)
865
866 • <network name|ID>: Join the network with the given name or ID,
867 e.g. use --network mynet to join the network with the name
868 mynet. Only supported for rootful users.
869
870 • slirp4netns[:OPTIONS,...]: use slirp4netns(1) to create a user
871 network stack. This is the default for rootless containers. It
872 is possible to specify these additional options, they can also
873 be set with network_cmd_options in containers.conf:
874
875 • allow_host_loopback=true|false: Allow slirp4netns to reach
876 the host loopback IP (default is 10.0.2.2 or the second IP
877 from slirp4netns cidr subnet when changed, see the cidr op‐
878 tion below). The default is false.
879
880 • mtu=MTU: Specify the MTU to use for this network. (Default
881 is 65520).
882
883 • cidr=CIDR: Specify ip range to use for this network. (De‐
884 fault is 10.0.2.0/24).
885
886 • enable_ipv6=true|false: Enable IPv6. Default is true. (Re‐
887 quired for outbound_addr6).
888
889 • outbound_addr=INTERFACE: Specify the outbound interface
890 slirp binds to (ipv4 traffic only).
891
892 • outbound_addr=IPv4: Specify the outbound ipv4 address slirp
893 binds to.
894
895 • outbound_addr6=INTERFACE: Specify the outbound interface
896 slirp binds to (ipv6 traffic only).
897
898 • outbound_addr6=IPv6: Specify the outbound ipv6 address slirp
899 binds to.
900
901
902
903 • pasta[:OPTIONS,...]: use pasta(1) to create a user-mode net‐
904 working stack.
905 This is only supported in rootless mode.
906 By default, IPv4 and IPv6 addresses and routes, as well as the
907 pod interface name, are copied from the host. If port forward‐
908 ing isn't configured, ports are forwarded dynamically as ser‐
909 vices are bound on either side (init namespace or container
910 namespace). Port forwarding preserves the original source IP
911 address. Options described in pasta(1) can be specified as
912 comma-separated arguments.
913 In terms of pasta(1) options, --config-net is given by de‐
914 fault, in order to configure networking when the container is
915 started, and --no-map-gw is also assumed by default, to avoid
916 direct access from container to host using the gateway ad‐
917 dress. The latter can be overridden by passing --map-gw in the
918 pasta-specific options (despite not being an actual pasta(1)
919 option).
920 Also, -t none and -u none are passed to disable automatic port
921 forwarding based on bound ports. Similarly, -T none and -U
922 none are given to disable the same functionality from con‐
923 tainer to host.
924 Some examples:
925
926 • pasta:--map-gw: Allow the container to directly reach the
927 host using the gateway address.
928
929 • pasta:--mtu,1500: Specify a 1500 bytes MTU for the tap in‐
930 terface in the container.
931
932 • pasta:--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-for‐
933 ward,10.0.2.3,-m,1500,--no-ndp,--no-dhcpv6,--no-dhcp, equiv‐
934 alent to default slirp4netns(1) options: disable IPv6, as‐
935 sign 10.0.2.0/24 to the tap0 interface in the container,
936 with gateway 10.0.2.3, enable DNS forwarder reachable at
937 10.0.2.3, set MTU to 1500 bytes, disable NDP, DHCPv6 and
938 DHCP support.
939
940 • pasta:-I,tap0,--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-
941 forward,10.0.2.3,--no-ndp,--no-dhcpv6,--no-dhcp, equivalent
942 to default slirp4netns(1) options with Podman overrides:
943 same as above, but leave the MTU to 65520 bytes
944
945 • pasta:-t,auto,-u,auto,-T,auto,-U,auto: enable automatic port
946 forwarding based on observed bound ports from both host and
947 container sides
948
949 • pasta:-T,5201: enable forwarding of TCP port 5201 from con‐
950 tainer to host, using the loopback interface instead of the
951 tap interface for improved performance
952
953
954
955
956
957 --no-cache
958 Do not use existing cached images for the container build. Build from
959 the start with a new set of cached layers.
960
961
962 --no-hosts
963 Do not create /etc/hosts for the container. By default, Podman manages
964 /etc/hosts, adding the container's own IP address and any hosts from
965 --add-host. --no-hosts disables this, and the image's /etc/hosts is
966 preserved unmodified.
967
968
969 This option conflicts with --add-host.
970
971
972 --omit-history
973 Omit build history information in the built image. (default false).
974
975
976 This option is useful for the cases where end users explicitly want to
977 set --omit-history to omit the optional History from built images or
978 when working with images built using build tools that do not include
979 History information in their images.
980
981
982 --os=string
983 Set the OS of the image to be built, and that of the base image to be
984 pulled, if the build uses one, instead of using the current operating
985 system of the build host. Unless overridden, subsequent lookups of the
986 same image in the local storage matches this OS, regardless of the
987 host.
988
989
990 --os-feature=feature
991 Set the name of a required operating system feature for the image which
992 is built. By default, if the image is not based on scratch, the base
993 image's required OS feature list is kept, if the base image specified
994 any. This option is typically only meaningful when the image's OS is
995 Windows.
996
997
998 If feature has a trailing -, then the feature is removed from the set
999 of required features which is listed in the image.
1000
1001
1002 --os-version=version
1003 Set the exact required operating system version for the image which is
1004 built. By default, if the image is not based on scratch, the base im‐
1005 age's required OS version is kept, if the base image specified one.
1006 This option is typically only meaningful when the image's OS is Win‐
1007 dows, and is typically set in Windows base images, so using this option
1008 is usually unnecessary.
1009
1010
1011 --output, -o=output-opts
1012 Output destination (format: type=local,dest=path)
1013
1014
1015 The --output (or -o) option extends the default behavior of building a
1016 container image by allowing users to export the contents of the image
1017 as files on the local filesystem, which can be useful for generating
1018 local binaries, code generation, etc. (This option is not available
1019 with the remote Podman client, including Mac and Windows (excluding
1020 WSL2) machines)
1021
1022
1023 The value for --output is a comma-separated sequence of key=value
1024 pairs, defining the output type and options.
1025
1026
1027 Supported keys are: - dest: Destination path for exported output. Valid
1028 value is absolute or relative path, - means the standard output. -
1029 type: Defines the type of output to be used. Valid values is documented
1030 below.
1031
1032
1033 Valid type values are: - local: write the resulting build files to a
1034 directory on the client-side. - tar: write the resulting files as a
1035 single tarball (.tar).
1036
1037
1038 If no type is specified, the value defaults to local. Alternatively,
1039 instead of a comma-separated sequence, the value of --output can be
1040 just a destination (in the dest format) (e.g. --output some-path,
1041 --output -) where --output some-path is treated as if type=local and
1042 --output - is treated as if type=tar.
1043
1044
1045 --pid=pid
1046 Sets the configuration for PID namespaces when handling RUN instruc‐
1047 tions. The configured value can be "" (the empty string) or "con‐
1048 tainer" to indicate that a new PID namespace is created, or it can be
1049 "host" to indicate that the PID namespace in which podman itself is be‐
1050 ing run is reused, or it can be the path to a PID namespace which is
1051 already in use by another process.
1052
1053
1054 --platform=os/arch[/variant][,...]
1055 Set the os/arch of the built image (and its base image, when using one)
1056 to the provided value instead of using the current operating system and
1057 architecture of the host (for example linux/arm). Unless overridden,
1058 subsequent lookups of the same image in the local storage matches this
1059 platform, regardless of the host.
1060
1061
1062 If --platform is set, then the values of the --arch, --os, and --vari‐
1063 ant options is overridden.
1064
1065
1066 The --platform option can be specified more than once, or given a
1067 comma-separated list of values as its argument. When more than one
1068 platform is specified, the --manifest option is used instead of the
1069 --tag option.
1070
1071
1072 Os/arch pairs are those used by the Go Programming Language. In sev‐
1073 eral cases the arch value for a platform differs from one produced by
1074 other tools such as the arch command. Valid OS and architecture name
1075 combinations are listed as values for $GOOS and $GOARCH at
1076 https://golang.org/doc/install/source#environment, and can also be
1077 found by running go tool dist list.
1078
1079
1080 While podman build is happy to use base images and build images for any
1081 platform that exists, RUN instructions are able to succeed without the
1082 help of emulation provided by packages like qemu-user-static.
1083
1084
1085 --pull=policy
1086 Pull image policy. The default is always.
1087
1088
1089 • always, true: Always pull the image and throw an error if the
1090 pull fails.
1091
1092 • missing: Only pull the image when it does not exist in the lo‐
1093 cal containers storage. Throw an error if no image is found
1094 and the pull fails.
1095
1096 • never, false: Never pull the image but use the one from the
1097 local containers storage. Throw an error when no image is
1098 found.
1099
1100 • newer: Pull if the image on the registry is newer than the one
1101 in the local containers storage. An image is considered to be
1102 newer when the digests are different. Comparing the time
1103 stamps is prone to errors. Pull errors are suppressed if a
1104 local image was found.
1105
1106
1107
1108 --quiet, -q
1109 Suppress output messages which indicate which instruction is being pro‐
1110 cessed, and of progress when pulling images from a registry, and when
1111 writing the output image.
1112
1113
1114 --retry=attempts
1115 Number of times to retry in case of failure when performing pull of im‐
1116 ages from registry. Default is 3.
1117
1118
1119 --retry-delay=duration
1120 Duration of delay between retry attempts in case of failure when per‐
1121 forming pull of images from registry. Default is 2s.
1122
1123
1124 --rm
1125 Remove intermediate containers after a successful build (default true).
1126
1127
1128 --runtime=path
1129 The path to an alternate OCI-compatible runtime, which is used to run
1130 commands specified by the RUN instruction.
1131
1132
1133 Note: You can also override the default runtime by setting the BUIL‐
1134 DAH_RUNTIME environment variable. export BUILDAH_RUNTIME=/usr/lo‐
1135 cal/bin/runc
1136
1137
1138 --runtime-flag=flag
1139 Adds global flags for the container rutime. To list the supported
1140 flags, please consult the manpages of the selected container runtime.
1141
1142
1143 Note: Do not pass the leading -- to the flag. To pass the runc flag
1144 --log-format json to buildah build, the option given is --runtime-flag
1145 log-format=json.
1146
1147
1148 --secret=id=id,src=path
1149 Pass secret information used in the Containerfile for building images
1150 in a safe way that are not stored in the final image, or be seen in
1151 other stages. The secret is mounted in the container at the default
1152 location of /run/secrets/id.
1153
1154
1155 To later use the secret, use the --mount option in a RUN instruction
1156 within a Containerfile:
1157
1158
1159 RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret
1160
1161
1162 --security-opt=option
1163 Security Options
1164
1165
1166 • apparmor=unconfined : Turn off apparmor confinement for the
1167 container
1168
1169 • apparmor=alternate-profile : Set the apparmor confinement pro‐
1170 file for the container
1171
1172 • label=user:USER : Set the label user for the container
1173 processes
1174
1175 • label=role:ROLE : Set the label role for the container
1176 processes
1177
1178 • label=type:TYPE : Set the label process type for the con‐
1179 tainer processes
1180
1181 • label=level:LEVEL : Set the label level for the container
1182 processes
1183
1184 • label=filetype:TYPE : Set the label file type for the con‐
1185 tainer files
1186
1187 • label=disable : Turn off label separation for the con‐
1188 tainer
1189
1190 • no-new-privileges : Not supported
1191
1192 • seccomp=unconfined : Turn off seccomp confinement for the con‐
1193 tainer
1194
1195 • seccomp=profile.json : White listed syscalls seccomp Json
1196 file to be used as a seccomp filter
1197
1198
1199
1200 --shm-size=number[unit]
1201 Size of /dev/shm. A unit can be b (bytes), k (kibibytes), m
1202 (mebibytes), or g (gibibytes). If the unit is omitted, the system uses
1203 bytes. If the size is omitted, the default is 64m. When size is 0,
1204 there is no limit on the amount of memory used for IPC by the con‐
1205 tainer. This option conflicts with --ipc=host.
1206
1207
1208 --sign-by=fingerprint
1209 Sign the image using a GPG key with the specified FINGERPRINT. (This
1210 option is not available with the remote Podman client, including Mac
1211 and Windows (excluding WSL2) machines,)
1212
1213
1214 --skip-unused-stages
1215 Skip stages in multi-stage builds which don't affect the target stage.
1216 (Default: true).
1217
1218
1219 --squash
1220 Squash all of the image's new layers into a single new layer; any pre‐
1221 existing layers are not squashed.
1222
1223
1224 --squash-all
1225 Squash all of the new image's layers (including those inherited from a
1226 base image) into a single new layer.
1227
1228
1229 --ssh=default | id[=socket>
1230 SSH agent socket or keys to expose to the build. The socket path can
1231 be left empty to use the value of default=$SSH_AUTH_SOCK
1232
1233
1234 To later use the ssh agent, use the --mount option in a RUN instruction
1235 within a Containerfile:
1236
1237
1238 RUN --mount=type=ssh,id=id mycmd
1239
1240
1241 --stdin
1242 Pass stdin into the RUN containers. Sometime commands being RUN within
1243 a Containerfile want to request information from the user. For example
1244 apt asking for a confirmation for install. Use --stdin to be able to
1245 interact from the terminal during the build.
1246
1247
1248 --tag, -t=imageName
1249 Specifies the name which is assigned to the resulting image if the
1250 build process completes successfully. If imageName does not include a
1251 registry name, the registry name localhost is prepended to the image
1252 name.
1253
1254
1255 --target=stageName
1256 Set the target build stage to build. When building a Containerfile
1257 with multiple build stages, --target can be used to specify an interme‐
1258 diate build stage by name as the final stage for the resulting image.
1259 Commands after the target stage is skipped.
1260
1261
1262 --timestamp=seconds
1263 Set the create timestamp to seconds since epoch to allow for determin‐
1264 istic builds (defaults to current time). By default, the created time‐
1265 stamp is changed and written into the image manifest with every commit,
1266 causing the image's sha256 hash to be different even if the sources are
1267 exactly the same otherwise. When --timestamp is set, the created time‐
1268 stamp is always set to the time specified and therefore not changed,
1269 allowing the image's sha256 hash to remain the same. All files commit‐
1270 ted to the layers of the image is created with the timestamp.
1271
1272
1273 If the only instruction in a Containerfile is FROM, this flag has no
1274 effect.
1275
1276
1277 --tls-verify
1278 Require HTTPS and verify certificates when contacting registries (de‐
1279 fault: true). If explicitly set to true, TLS verification is used. If
1280 set to false, TLS verification is not used. If not specified, TLS ver‐
1281 ification is used unless the target registry is listed as an insecure
1282 registry in containers-registries.conf(5)
1283
1284
1285 --ulimit=type=soft-limit[:hard-limit]
1286 Specifies resource limits to apply to processes launched when process‐
1287 ing RUN instructions. This option can be specified multiple times.
1288 Recognized resource types include:
1289 "core": maximum core dump size (ulimit -c)
1290 "cpu": maximum CPU time (ulimit -t)
1291 "data": maximum size of a process's data segment (ulimit -d)
1292 "fsize": maximum size of new files (ulimit -f)
1293 "locks": maximum number of file locks (ulimit -x)
1294 "memlock": maximum amount of locked memory (ulimit -l)
1295 "msgqueue": maximum amount of data in message queues (ulimit -q)
1296 "nice": niceness adjustment (nice -n, ulimit -e)
1297 "nofile": maximum number of open files (ulimit -n)
1298 "nproc": maximum number of processes (ulimit -u)
1299 "rss": maximum size of a process's (ulimit -m)
1300 "rtprio": maximum real-time scheduling priority (ulimit -r)
1301 "rttime": maximum amount of real-time execution between blocking
1302 syscalls
1303 "sigpending": maximum number of pending signals (ulimit -i)
1304 "stack": maximum stack size (ulimit -s)
1305
1306
1307 --unsetenv=env
1308 Unset environment variables from the final image.
1309
1310
1311 --userns=how
1312 Sets the configuration for user namespaces when handling RUN instruc‐
1313 tions. The configured value can be "" (the empty string) or "con‐
1314 tainer" to indicate that a new user namespace is created, it can be
1315 "host" to indicate that the user namespace in which podman itself is
1316 being run is reused, or it can be the path to a user namespace which is
1317 already in use by another process.
1318
1319
1320 --userns-gid-map=mapping
1321 Directly specifies a GID mapping to be used to set ownership, at the
1322 filesystem level, on the working container's contents. Commands run
1323 when handling RUN instructions defaults to being run in their own user
1324 namespaces, configured using the UID and GID maps.
1325
1326
1327 Entries in this map take the form of one or more triples of a starting
1328 in-container GID, a corresponding starting host-level GID, and the num‐
1329 ber of consecutive IDs which the map entry represents.
1330
1331
1332 This option overrides the remap-gids setting in the options section of
1333 /etc/containers/storage.conf.
1334
1335
1336 If this option is not specified, but a global --userns-gid-map setting
1337 is supplied, settings from the global option is used.
1338
1339
1340 If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-
1341 gid-map are specified, but --userns-uid-map is specified, the GID map
1342 is set to use the same numeric values as the UID map.
1343
1344
1345 --userns-gid-map-group=group
1346 Specifies that a GID mapping to be used to set ownership, at the
1347 filesystem level, on the working container's contents, can be found in
1348 entries in the /etc/subgid file which correspond to the specified
1349 group. Commands run when handling RUN instructions defaults to being
1350 run in their own user namespaces, configured using the UID and GID
1351 maps. If --userns-uid-map-user is specified, but --userns-gid-map-
1352 group is not specified, podman assumes that the specified user name is
1353 also a suitable group name to use as the default setting for this op‐
1354 tion.
1355
1356
1357 NOTE: When this option is specified by a rootless user, the specified
1358 mappings are relative to the rootless user namespace in the container,
1359 rather than being relative to the host as it is when run rootful.
1360
1361
1362 --userns-uid-map=mapping
1363 Directly specifies a UID mapping to be used to set ownership, at the
1364 filesystem level, on the working container's contents. Commands run
1365 when handling RUN instructions default to being run in their own user
1366 namespaces, configured using the UID and GID maps.
1367
1368
1369 Entries in this map take the form of one or more triples of a starting
1370 in-container UID, a corresponding starting host-level UID, and the num‐
1371 ber of consecutive IDs which the map entry represents.
1372
1373
1374 This option overrides the remap-uids setting in the options section of
1375 /etc/containers/storage.conf.
1376
1377
1378 If this option is not specified, but a global --userns-uid-map setting
1379 is supplied, settings from the global option is used.
1380
1381
1382 If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-
1383 uid-map are specified, but --userns-gid-map is specified, the UID map
1384 is set to use the same numeric values as the GID map.
1385
1386
1387 --userns-uid-map-user=user
1388 Specifies that a UID mapping to be used to set ownership, at the
1389 filesystem level, on the working container's contents, can be found in
1390 entries in the /etc/subuid file which correspond to the specified user.
1391 Commands run when handling RUN instructions defaults to being run in
1392 their own user namespaces, configured using the UID and GID maps. If
1393 --userns-gid-map-group is specified, but --userns-uid-map-user is not
1394 specified, podman assumes that the specified group name is also a suit‐
1395 able user name to use as the default setting for this option.
1396
1397
1398 NOTE: When this option is specified by a rootless user, the specified
1399 mappings are relative to the rootless user namespace in the container,
1400 rather than being relative to the host as it is when run rootful.
1401
1402
1403 --uts=how
1404 Sets the configuration for UTS namespaces when handling RUN instruc‐
1405 tions. The configured value can be "" (the empty string) or "con‐
1406 tainer" to indicate that a new UTS namespace to be created, or it can
1407 be "host" to indicate that the UTS namespace in which podman itself is
1408 being run is reused, or it can be the path to a UTS namespace which is
1409 already in use by another process.
1410
1411
1412 --variant=variant
1413 Set the architecture variant of the image to be built, and that of the
1414 base image to be pulled, if the build uses one, to the provided value
1415 instead of using the architecture variant of the build host.
1416
1417
1418 --volume, -v=[HOST-DIR:CONTAINER-DIR[:OPTIONS]]
1419 Create a bind mount. Specifying the -v /HOST-DIR:/CONTAINER-DIR option,
1420 Podman bind mounts /HOST-DIR from the host to /CONTAINER-DIR in the
1421 Podman container.
1422
1423
1424 The OPTIONS are a comma-separated list and can be: [1] ⟨#Footnote1⟩
1425
1426
1427 • [rw|ro]
1428
1429 • [z|Z|O]
1430
1431 • [U]
1432
1433 • [[r]shared|[r]slave|[r]private]
1434
1435
1436
1437 The CONTAINER-DIR must be an absolute path such as /src/docs. The HOST-
1438 DIR must be an absolute path as well. Podman bind-mounts the HOST-DIR
1439 to the specified path. For example, when specifying the host path /foo,
1440 Podman copies the contents of /foo to the container filesystem on the
1441 host and bind mounts that into the container.
1442
1443
1444 You can specify multiple -v options to mount one or more mounts to a
1445 container.
1446
1447
1448 You can add the :ro or :rw suffix to a volume to mount it read-only or
1449 read-write mode, respectively. By default, the volumes are mounted
1450 read-write. See examples.
1451
1452
1453 Chowning Volume Mounts
1454
1455
1456 By default, Podman does not change the owner and group of source volume
1457 directories mounted. When running using user namespaces, the UID and
1458 GID inside the namespace may correspond to another UID and GID on the
1459 host.
1460
1461
1462 The :U suffix tells Podman to use the correct host UID and GID based on
1463 the UID and GID within the namespace, to change recursively the owner
1464 and group of the source volume.
1465
1466
1467 Warning use with caution since this modifies the host filesystem.
1468
1469
1470 Labeling Volume Mounts
1471
1472
1473 Labeling systems like SELinux require that proper labels are placed on
1474 volume content mounted into a container. Without a label, the security
1475 system might prevent the processes running inside the container from
1476 using the content. By default, Podman does not change the labels set by
1477 the OS.
1478
1479
1480 To change a label in the container context, add one of these two suf‐
1481 fixes :z or :Z to the volume mount. These suffixes tell Podman to rela‐
1482 bel file objects on the shared volumes. The z option tells Podman that
1483 two containers share the volume content. As a result, Podman labels the
1484 content with a shared content label. Shared volume labels allow all
1485 containers to read/write content. The Z option tells Podman to label
1486 the content with a private unshared label. Only the current container
1487 can use a private volume.
1488
1489
1490 Note: Do not relabel system files and directories. Relabeling system
1491 content might cause other confined services on the host machine to
1492 fail. For these types of containers, disabling SELinux separation is
1493 recommended. The option --security-opt label=disable disables SELinux
1494 separation for the container. For example, if a user wanted to volume
1495 mount their entire home directory into the build containers, they need
1496 to disable SELinux separation.
1497
1498
1499 $ podman build --security-opt label=disable -v $HOME:/home/user .
1500
1501
1502
1503 Overlay Volume Mounts
1504
1505
1506 The :O flag tells Podman to mount the directory from the host as a tem‐
1507 porary storage using the Overlay file system. The RUN command contain‐
1508 ers are allowed to modify contents within the mountpoint and are stored
1509 in the container storage in a separate directory. In Overlay FS terms
1510 the source directory is the lower, and the container storage directory
1511 is the upper. Modifications to the mount point are destroyed when the
1512 RUN command finishes executing, similar to a tmpfs mount point.
1513
1514
1515 Any subsequent execution of RUN commands sees the original source di‐
1516 rectory content, any changes from previous RUN commands no longer ex‐
1517 ists.
1518
1519
1520 One use case of the overlay mount is sharing the package cache from the
1521 host into the container to allow speeding up builds.
1522
1523
1524 Note:
1525
1526
1527 - Overlay mounts are not currently supported in rootless mode.
1528 - The `O` flag is not allowed to be specified with the `Z` or `z` flags.
1529
1530
1531
1532 Content mounted into the container is labeled with the private label.
1533 On SELinux systems, labels in the source directory needs to be
1534 readable by the container label. If not, SELinux container separation
1535 must be disabled for the container to work.
1536 - Modification of the directory volume mounted into the container
1537 with an overlay mount can cause unexpected failures. Do not modify the
1538 directory until the container finishes running.
1539
1540
1541 By default bind mounted volumes are private. That means any mounts done
1542 inside containers are not be visible on the host and vice versa. This
1543 behavior can be changed by specifying a volume mount propagation prop‐
1544 erty.
1545
1546
1547 When the mount propagation policy is set to shared, any mounts com‐
1548 pleted inside the container on that volume is visible to both the host
1549 and container. When the mount propagation policy is set to slave, one
1550 way mount propagation is enabled and any mounts completed on the host
1551 for that volume is visible only inside of the container. To control the
1552 mount propagation property of volume use the :[r]shared, :[r]slave or
1553 :[r]private propagation flag. For mount propagation to work on the
1554 source mount point (mount point where source dir is mounted on) has to
1555 have the right propagation properties. For shared volumes, the source
1556 mount point has to be shared. And for slave volumes, the source mount
1557 has to be either shared or slave. [1] ⟨#Footnote1⟩
1558
1559
1560 Use df <source-dir> to determine the source mount and then use findmnt
1561 -o TARGET,PROPAGATION <source-mount-dir> to determine propagation prop‐
1562 erties of source mount, if findmnt utility is not available, the source
1563 mount point can be determined by looking at the mount entry in
1564 /proc/self/mountinfo. Look at optional fields and see if any propaga‐
1565 tion properties are specified. shared:X means the mount is shared,
1566 master:X means the mount is slave and if nothing is there that means
1567 the mount is private. [1] ⟨#Footnote1⟩
1568
1569
1570 To change propagation properties of a mount point use the mount com‐
1571 mand. For example, to bind mount the source directory /foo do mount
1572 --bind /foo /foo and mount --make-private --make-shared /foo. This con‐
1573 verts /foo into a shared mount point. The propagation properties of
1574 the source mount can be changed directly. For instance if / is the
1575 source mount for /foo, then use mount --make-shared / to convert / into
1576 a shared mount.
1577
1578
1580 Build an image using local Containerfiles
1581 $ podman build .
1582
1583 $ podman build -f Containerfile.simple .
1584
1585 $ cat $HOME/Containerfile | podman build -f - .
1586
1587 $ podman build -f Containerfile.simple -f Containerfile.notsosimple .
1588
1589 $ podman build -f Containerfile.in $HOME
1590
1591 $ podman build -t imageName .
1592
1593 $ podman build --tls-verify=true -t imageName -f Containerfile.simple .
1594
1595 $ podman build --tls-verify=false -t imageName .
1596
1597 $ podman build --runtime-flag log-format=json .
1598
1599 $ podman build --runtime-flag debug .
1600
1601 $ podman build --authfile /tmp/auths/myauths.json --cert-dir $HOME/auth --tls-verify=true --creds=username:password -t imageName -f Containerfile.simple .
1602
1603 $ podman build --memory 40m --cpu-period 10000 --cpu-quota 50000 --ulimit nofile=1024:1028 -t imageName .
1604
1605 $ podman build --security-opt label=level:s0:c100,c200 --cgroup-parent /path/to/cgroup/parent -t imageName .
1606
1607 $ podman build --volume /home/test:/myvol:ro,Z -t imageName .
1608
1609 $ podman build -v /var/lib/yum:/var/lib/yum:O -t imageName .
1610
1611 $ podman build --layers -t imageName .
1612
1613 $ podman build --no-cache -t imageName .
1614
1615 $ podman build --layers --force-rm -t imageName .
1616
1617 $ podman build --no-cache --rm=false -t imageName .
1618
1619 $ podman build --network mynet .
1620
1621
1622
1623 Building a multi-architecture image using the --manifest option (requires
1624 emulation software)
1625 $ podman build --arch arm --manifest myimage /tmp/mysrc
1626
1627 $ podman build --arch amd64 --manifest myimage /tmp/mysrc
1628
1629 $ podman build --arch s390x --manifest myimage /tmp/mysrc
1630
1631 $ podman build --platform linux/s390x,linux/ppc64le,linux/amd64 --manifest myimage /tmp/mysrc
1632
1633 $ podman build --platform linux/arm64 --platform linux/amd64 --manifest myimage /tmp/mysrc
1634
1635
1636
1637 Building an image using a URL, Git repo, or archive
1638 The build context directory can be specified as a URL to a Container‐
1639 file, a Git repository, or URL to an archive. If the URL is a Contain‐
1640 erfile, it is downloaded to a temporary location and used as the con‐
1641 text. When a Git repository is set as the URL, the repository is cloned
1642 locally to a temporary location and then used as the context. Lastly,
1643 if the URL is an archive, it is downloaded to a temporary location and
1644 extracted before being used as the context.
1645
1646
1647 Building an image using a URL to a Containerfile
1648 Podman downloads the Containerfile to a temporary location and then use
1649 it as the build context.
1650
1651
1652 $ podman build https://10.10.10.1/podman/Containerfile
1653
1654
1655
1656 Building an image using a Git repository
1657 Podman clones the specified GitHub repository to a temporary location
1658 and use it as the context. The Containerfile at the root of the reposi‐
1659 tory is used and it only works if the GitHub repository is a dedicated
1660 repository.
1661
1662
1663 $ podman build -t hello https://github.com/containers/PodmanHello.git
1664 $ podman run hello
1665
1666
1667
1668 Note: Github does not support using git:// for performing clone opera‐
1669 tion due to recent changes in their security guidance
1670 (https://github.blog/2021-09-01-improving-git-protocol-security-
1671 github/). Use an https:// URL if the source repository is hosted on
1672 Github.
1673
1674
1675 Building an image using a URL to an archive
1676 Podman fetches the archive file, decompress it, and use its contents as
1677 the build context. The Containerfile at the root of the archive and the
1678 rest of the archive are used as the context of the build. Passing the
1679 -f PATH/Containerfile option as well tells the system to look for that
1680 file inside the contents of the archive.
1681
1682
1683 $ podman build -f dev/Containerfile https://10.10.10.1/podman/context.tar.gz
1684
1685
1686
1687 Note: supported compression formats are 'xz', 'bzip2', 'gzip' and
1688 'identity' (no compression).
1689
1690
1692 .containerignore/.dockerignore
1693 If the file .containerignore or .dockerignore exists in the context di‐
1694 rectory, podman build reads its contents. Use the --ignorefile option
1695 to override the Podman uses the content to exclude files and directo‐
1696 ries from the context directory, when executing COPY and ADD directives
1697 in the Containerfile/Dockerfile
1698
1699
1700 The .containerignore and .dockerignore files use the same syntax; if
1701 both are in the context directory, podman build only uses .containerig‐
1702 nore.
1703
1704
1705 Users can specify a series of Unix shell globs in a .containerignore
1706 file to identify files/directories to exclude.
1707
1708
1709 Podman supports a special wildcard string ** which matches any number
1710 of directories (including zero). For example, */.go excludes all files
1711 that end with .go that are found in all directories.
1712
1713
1714 Example .containerignore file:
1715
1716
1717 # exclude this content for image
1718 */*.c
1719 **/output*
1720 src
1721
1722
1723
1724 */*.c Excludes files and directories whose names ends with .c in any
1725 top level subdirectory. For example, the source file include/root‐
1726 less.c.
1727
1728
1729 **/output* Excludes files and directories starting with output from any
1730 directory.
1731
1732
1733 src Excludes files named src and the directory src as well as any con‐
1734 tent in it.
1735
1736
1737 Lines starting with ! (exclamation mark) can be used to make exceptions
1738 to exclusions. The following is an example .containerignore file that
1739 uses this mechanism:
1740
1741
1742 *.doc
1743 !Help.doc
1744
1745
1746
1747 Exclude all doc files except Help.doc from the image.
1748
1749
1750 This functionality is compatible with the handling of .containerignore
1751 files described here:
1752
1753
1754 https://github.com/containers/common/blob/main/docs/containerig‐
1755 nore.5.md
1756
1757
1758 registries.conf (/etc/containers/registries.conf)
1759
1760
1761 registries.conf is the configuration file which specifies which con‐
1762 tainer registries is consulted when completing image names which do not
1763 include a registry or domain portion.
1764
1765
1767 lastlog sparse file
1768 Using a useradd command within a Containerfile with a large UID/GID
1769 creates a large sparse file /var/log/lastlog. This can cause the build
1770 to hang forever. Go language does not support sparse files correctly,
1771 which can lead to some huge files being created in the container image.
1772
1773
1774 When using the useradd command within the build script, pass the --no-
1775 log-init or -l option to the useradd command. This option tells user‐
1776 add to stop creating the lastlog file.
1777
1778
1780 podman(1), buildah(1), containers-certs.d(5), containers-reg‐
1781 istries.conf(5), crun(1), runc(8), useradd(8), podman-ps(1), podman-
1782 rm(1), Containerfile(5), containerignore(5)
1783
1784
1786 Aug 2020, Additional options and .containerignore added by Dan Walsh
1787 <dwalsh@redhat.com>
1788
1789
1790 May 2018, Minor revisions added by Joe Doss <joe@solidadmin.com>
1791
1792
1793 December 2017, Originally compiled by Tom Sweeney <tsweeney@redhat.com>
1794
1795
1797 1: The Podman project is committed to inclusivity, a core value of open
1798 source. The master and slave mount propagation terminology used here is
1799 problematic and divisive, and needs to be changed. However, these
1800 terms are currently used within the Linux kernel and must be used as-is
1801 at this time. When the kernel maintainers rectify this usage, Podman
1802 will follow suit immediately.
1803
1804
1805
1806 podman-build(1)