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