1podman-build(1)()                                            podman-build(1)()
2
3
4

NAME

6       podman-build - Build a container image using a Containerfile
7
8

SYNOPSIS

10       podman build [options] [context]
11
12
13       podman image build [options] [context]
14
15

DESCRIPTION

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 an 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

OPTIONS

67   --add-host=host
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.
73
74
75   --annotation=annotation
76       Add an image annotation (e.g. annotation=value) to the image  metadata.
77       Can be used multiple times.
78
79
80       Note: this information is not present in Docker image formats, so it is
81       discarded when writing images in Docker formats.
82
83
84   --arch=arch
85       Set the architecture of the image to be built, and that of the base im‐
86       age  to be pulled, if the build uses one, to the provided value instead
87       of using the architecture of the build  host.  (Examples:  arm,  arm64,
88       386, amd64, ppc64le, s390x)
89
90
91   --authfile=path
92       Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
93       ers/auth.json, which is set using podman login.  If  the  authorization
94       state  is  not found there, $HOME/.docker/config.json is checked, which
95       is set using docker login.
96
97
98       Note: You can also override the default path of the authentication file
99       by  setting  the  REGISTRY_AUTH_FILE environment variable.  export REG‐
100       ISTRY_AUTH_FILE=path
101
102
103   --build-arg=arg=value
104       Specifies a build argument and its value, which will be interpolated in
105       instructions read from the Containerfiles in the same way that environ‐
106       ment variables are, but which will not be added to environment variable
107       list in the resulting image's configuration.
108
109
110   --cache-from
111       Images to utilize as potential cache sources. Podman does not currently
112       support caching so this is a NOOP. (This option is not  available  with
113       the remote Podman client)
114
115
116   --cap-add=CAP_xxx
117       When  executing  RUN instructions, run the command specified in the in‐
118       struction with the specified capability added to  its  capability  set.
119       Certain capabilities are granted by default; this option can be used to
120       add more.
121
122
123   --cap-drop=CAP_xxx
124       When executing RUN instructions, run the command specified in  the  in‐
125       struction  with  the  specified  capability removed from its capability
126       set.  The  CAP_AUDIT_WRITE,  CAP_CHOWN,  CAP_DAC_OVERRIDE,  CAP_FOWNER,
127       CAP_FSETID,  CAP_KILL,  CAP_MKNOD,  CAP_NET_BIND_SERVICE,  CAP_SETFCAP,
128       CAP_SETGID, CAP_SETPCAP, CAP_SETUID,  and  CAP_SYS_CHROOT  capabilities
129       are granted by default; this option can be used to remove them.
130
131
132       If  a  capability is specified to both the --cap-add and --cap-drop op‐
133       tions, it will be dropped, regardless of the order in which the options
134       were given.
135
136
137   --cert-dir=path
138       Use  certificates at path (*.crt, *.cert, *.key) to connect to the reg‐
139       istry.  Please refer to containers-certs.d(5) for details. (This option
140       is not available with the remote Podman client)
141
142
143   --cgroup-parent=path
144       Path  to  cgroups under which the cgroup for the container will be cre‐
145       ated. If the path is not absolute, the path is considered to  be  rela‐
146       tive  to  the cgroups path of the init process. Cgroups will be created
147       if they do not already exist.
148
149
150   --compress
151       This option is added to be aligned with other containers CLIs.   Podman
152       doesn't  communicate with a daemon or a remote server.  Thus, compress‐
153       ing the data before sending it is irrelevant to Podman. (This option is
154       not available with the remote Podman client)
155
156
157   --cni-config-dir=directory
158       Location  of  CNI  configuration files which will dictate which plugins
159       will be used to configure network interfaces and routing for containers
160       created  for handling RUN instructions, if those containers will be run
161       in their own network namespaces, and networking is not disabled.
162
163
164   --cni-plugin-path=directory[:directory[:directory[...]]]
165       List of directories in which the CNI plugins which  will  be  used  for
166       configuring network namespaces can be found.
167
168
169   --cpu-period=limit
170       Set  the CPU period for the Completely Fair Scheduler (CFS), which is a
171       duration in microseconds. Once the container's CPU quota is used up, it
172       will not be scheduled to run until the current period ends. Defaults to
173       100000 microseconds.
174
175
176       On some systems, changing the CPU limits may not be  allowed  for  non-
177       root  users.  For  more details, see https://github.com/containers/pod
178       man/blob/master/troubleshooting.md#26-running-containers-with-cpu-lim‐
179       its-fails-with-a-permissions-error
180
181
182   --cpu-quota=limit
183       Limit the CPU Completely Fair Scheduler (CFS) quota.
184
185
186       Limit  the  container's  CPU usage. By default, containers run with the
187       full CPU resource. The limit is a number in microseconds. If  you  pro‐
188       vide  a number, the container will be allowed to use that much CPU time
189       until the CPU period ends (controllable via --cpu-period).
190
191
192       On some systems, changing the CPU limits may not be  allowed  for  non-
193       root  users.  For  more details, see https://github.com/containers/pod
194       man/blob/master/troubleshooting.md#26-running-containers-with-cpu-lim‐
195       its-fails-with-a-permissions-error
196
197
198   --cpu-shares, -c=shares
199       CPU shares (relative weight)
200
201
202       By  default, all containers get the same proportion of CPU cycles. This
203       proportion can be  modified  by  changing  the  container's  CPU  share
204       weighting relative to the weighting of all other running containers.
205
206
207       To modify the proportion from the default of 1024, use the --cpu-shares
208       flag to set the weighting to 2 or higher.
209
210
211       The proportion will only apply when CPU-intensive  processes  are  run‐
212       ning.   When  tasks in one container are idle, other containers can use
213       the left-over CPU time. The actual amount of CPU time will vary depend‐
214       ing on the number of containers running on the system.
215
216
217       For example, consider three containers, one has a cpu-share of 1024 and
218       two others have a cpu-share setting of 512. When processes in all three
219       containers  attempt  to  use 100% of CPU, the first container would re‐
220       ceive 50% of the total CPU time. If you add a fourth container  with  a
221       cpu-share  of  1024,  the first container only gets 33% of the CPU. The
222       remaining containers receive 16.5%, 16.5% and 33% of the CPU.
223
224
225       On a multi-core system, the shares of CPU time are distributed over all
226       CPU  cores.  Even  if  a  container is limited to less than 100% of CPU
227       time, it can use 100% of each individual CPU core.
228
229
230       For example, consider a system with more than three cores. If you start
231       one  container  {C0}  with -c=512 running one process, and another con‐
232       tainer {C1} with -c=1024 running two processes, this can result in  the
233       following division of CPU shares:
234
235
236              PID    container    CPU  CPU share
237              100    {C0}         0    100% of CPU0
238              101    {C1}         1    100% of CPU1
239              102    {C1}         2    100% of CPU2
240
241
242
243   --cpuset-cpus=num
244       CPUs in which to allow execution (0-3, 0,1)
245
246
247   --cpuset-mems=nodes
248       Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effec‐
249       tive on NUMA systems.
250
251
252       If you have four memory nodes  on  your  system  (0-3),  use  --cpuset-
253       mems=0,1 then processes in your container will only use memory from the
254       first two memory nodes.
255
256
257   --creds=creds
258       The [username[:password]] to use to authenticate with the  registry  if
259       required.   If  one  or  both  values  are not supplied, a command line
260       prompt will appear and the value can be entered.  The password  is  en‐
261       tered without echo.
262
263
264   --decryption-key=key[:passphrase]
265       The  [key[:passphrase]]  to  be  used for decryption of images. Key can
266       point to keys and/or certificates. Decryption will be  tried  with  all
267       keys.  If  the  key  is protected by a passphrase, it is required to be
268       passed in the argument and omitted otherwise.
269
270
271   --device=host-device[:container-device][:permissions]
272       Add a host device to the container. Optional permissions parameter  can
273       be used to specify device permissions, it is combination of r for read,
274       w for write, and m for mknod(2).
275
276
277       Example: --device=/dev/sdc:/dev/xvdc:rwm.
278
279
280       Note: if _hostdevice is a symbolic link then it will be resolved first.
281       The  container  will only store the major and minor numbers of the host
282       device.
283
284
285       Note: if the user only has access rights via a group, accessing the de‐
286       vice  from  inside  a rootless container will fail. The crun(1) runtime
287       offers a workaround for this by adding the option
288
289
290   --annotation run.oci.keep_original_groups=1.
291   --disable-compression, -D
292       Don't compress filesystem layers when building the image unless  it  is
293       required by the location where the image is being written.  This is the
294       default setting, because image layers are compressed automatically when
295       they  are pushed to registries, and images being written to local stor‐
296       age would only need to be decompressed again to be stored.  Compression
297       can be forced in all cases by specifying --disable-compression=false.
298
299
300   --disable-content-trust
301       This  is  a  Docker  specific option to disable image verification to a
302       Docker registry and is not supported by Podman.  This flag  is  a  NOOP
303       and  provided  solely  for scripting compatibility. (This option is not
304       available with the remote Podman client)
305
306
307   --dns=dns
308       Set custom DNS servers to be used during the build.
309
310
311       This option can be used to override the DNS configuration passed to the
312       container.  Typically this is necessary when the host DNS configuration
313       is invalid for the container (e.g., 127.0.0.1). When this is  the  case
314       the --dns flag is necessary for every run.
315
316
317       The special value none can be specified to disable creation of /etc/re‐
318       solv.conf in the container by Podman. The /etc/resolv.conf file in  the
319       image will be used without changes.
320
321
322   --dns-option=option
323       Set custom DNS options to be used during the build.
324
325
326   --dns-search=domain
327       Set custom DNS search domains to be used during the build.
328
329
330   --file, -f=Containerfile
331       Specifies  a Containerfile which contains instructions for building the
332       image, either a local file or an http or https URL.  If more  than  one
333       Containerfile  is  specified,  FROM  instructions will only be accepted
334       from the first specified file.
335
336
337       If a build context is not specified, and at least one Containerfile  is
338       a  local  file,  the  directory in which it resides will be used as the
339       build context.
340
341
342       If you specify -f -, the  Containerfile  contents  will  be  read  from
343       stdin.
344
345
346   --force-rm=true|false
347       Always  remove intermediate containers after a build, even if the build
348       fails (default true).
349
350
351   --format
352       Control the format for the built  image's  manifest  and  configuration
353       data.   Recognized  formats  include  oci (OCI image-spec v1.0, the de‐
354       fault) and docker (version 2, using schema format 2 for the manifest).
355
356
357       Note: You can also override the default format  by  setting  the  BUIL‐
358       DAH_FORMAT environment variable.  export BUILDAH_FORMAT=docker
359
360
361   --from
362       Overrides  the  first  FROM  instruction  within the Containerfile.  If
363       there are multiple FROM instructions in a Containerfile, only the first
364       is changed.
365
366
367       -h, --help
368
369
370       Print usage statement
371
372
373   --http-proxy
374       Pass through HTTP Proxy environment variables.
375
376
377   --iidfile=ImageIDfile
378       Write  the  built image's ID to the file.  When --platform is specified
379       more than once, attempting to use this option will trigger an error.
380
381
382   --ignorefile
383       Path to an alternative .dockerignore file.
384
385
386   --ipc=how
387       Sets the configuration for IPC namespaces when  handling  RUN  instruc‐
388       tions.   The  configured  value  can  be "" (the empty string) or "con‐
389       tainer" to indicate that a new IPC namespace should be created,  or  it
390       can be "host" to indicate that the IPC namespace in which podman itself
391       is being run should be reused, or it can be the path to  an  IPC  name‐
392       space which is already in use by another process.
393
394
395   --isolation=type
396       Controls  what  type of isolation is used for running processes as part
397       of RUN instructions.  Recognized types include oci (OCI-compatible run‐
398       time,  the  default),  rootless (OCI-compatible runtime invoked using a
399       modified configuration and its --rootless flag enabled, with  --no-new-
400       keyring --no-pivot added to its create invocation, with network and UTS
401       namespaces disabled, and IPC, PID, and user namespaces enabled; the de‐
402       fault  for  unprivileged  users),  and chroot (an internal wrapper that
403       leans more toward chroot(1) than container technology).
404
405
406       Note: You can also override the default isolation type by  setting  the
407       BUILDAH_ISOLATION environment variable.  export BUILDAH_ISOLATION=oci
408
409
410   --jobs=number
411       Run  up  to  N concurrent stages in parallel.  If the number of jobs is
412       greater than 1, stdin will be read from /dev/null.  If 0 is  specified,
413       then there is no limit in the number of jobs that run in parallel.
414
415
416   --label=label
417       Add  an  image  label  (e.g. label=value) to the image metadata. Can be
418       used multiple times.
419
420
421       Users can set a special LABEL io.containers.capabilities=CAP1,CAP2,CAP3
422       in  a  Containerfile  that specified the list of Linux capabilities re‐
423       quired for the container to run properly. This  label  specified  in  a
424       container image tells Podman to run the container with just these capa‐
425       bilities. Podman launches the container with just the  specified  capa‐
426       bilities,  as  long as this list of capabilities is a subset of the de‐
427       fault list.
428
429
430       If the specified capabilities are not in the default set,  Podman  will
431       print  an error message and will run the container with the default ca‐
432       pabilities.
433
434
435   --layers
436       Cache intermediate images during the build process (Default is true).
437
438
439       Note: You can also override the default value of layers by setting  the
440       BUILDAH_LAYERS environment variable. export BUILDAH_LAYERS=true
441
442
443   --logfile=filename
444       Log output which would be sent to standard output and standard error to
445       the specified file instead of to standard output and standard error.
446
447
448   --manifest manifest
449       Name of the manifest list to which the image will be added. Creates the
450       manifest  list if it does not exist. This option is useful for building
451       multi architecture images.
452
453
454   --memory, -m=LIMIT
455       Memory limit (format: <number>[<unit>],  where  unit  =  b  (bytes),  k
456       (kilobytes), m (megabytes), or g (gigabytes))
457
458
459       Allows  you  to  constrain  the memory available to a container. If the
460       host supports swap memory, then the -m memory  setting  can  be  larger
461       than  physical  RAM.  If  a limit of 0 is specified (not using -m), the
462       container's memory is not limited. The actual limit may be  rounded  up
463       to  a  multiple of the operating system's page size (the value would be
464       very large, that's millions of trillions).
465
466
467   --memory-swap=LIMIT
468       A limit value equal to memory plus swap. Must  be  used  with  the   -m
469       (--memory) flag. The swap LIMIT should always be larger than -m (--mem‐
470       ory) value.  By default, the swap LIMIT will be set to double the value
471       of --memory.
472
473
474       The  format  of  LIMIT  is  <number>[<unit>].  Unit can be b (bytes), k
475       (kilobytes), m (megabytes), or g (gigabytes). If you  don't  specify  a
476       unit, b is used. Set LIMIT to -1 to enable unlimited swap.
477
478
479   --network=mode, --net
480       Sets  the  configuration  for  network namespaces when handling RUN in‐
481       structions.
482
483
484       Valid mode values are:
485
486
487none: no networking.
488
489host: use the Podman host network stack. Note: the  host  mode
490                gives  the container full access to local system services such
491                as D-bus and is therefore considered insecure.
492
493ns:path: path to a network namespace to join.
494
495private: create a new namespace for the container (default).
496
497
498
499   --no-cache
500       Do not use existing cached images for the container build.  Build  from
501       the start with a new set of cached layers.
502
503
504   --os=string
505       Set  the  OS of the image to be built, and that of the base image to be
506       pulled, if the build uses one, instead of using the  current  operating
507       system of the build host.
508
509
510   --pid=pid
511       Sets  the  configuration  for PID namespaces when handling RUN instruc‐
512       tions.  The configured value can be ""  (the  empty  string)  or  "con‐
513       tainer"  to  indicate that a new PID namespace should be created, or it
514       can be "host" to indicate that the PID namespace in which podman itself
515       is being run should be reused, or it can be the path to a PID namespace
516       which is already in use by another process.
517
518
519   --platform="OS/ARCH[/VARIANT][,...]"
520       Set the OS/ARCH of the built image (and its base image, if  your  build
521       uses  one) to the provided value instead of using the current operating
522       system and architecture of the host (for example linux/arm). If --plat‐
523       form is set, then the values of the --arch, --os, and --variant options
524       will be overridden.
525
526
527       The --platform flag can be specified more than once, or given a  comma-
528       separated  list of values as its argument.  When more than one platform
529       is specified, the --manifest option should be used instead of the --tag
530       option.
531
532
533       OS/ARCH  pairs  are those used by the Go Programming Language.  In sev‐
534       eral cases the ARCH value for a platform differs from one  produced  by
535       other  tools  such as the arch command.  Valid OS and architecture name
536       combinations  are  listed  as  values  for   $GOOS   and   $GOARCH   at
537       https://golang.org/doc/install/source#environment,   and  can  also  be
538       found by running go tool dist list.
539
540
541       While podman build is happy to use base images and build images for any
542       platform  that  exists,  RUN  instructions  will not be able to succeed
543       without the help of emulation  provided  by  packages  like  qemu-user-
544       static.
545
546
547   --pull
548       When  the  option is specified or set to "true", pull the image.  Raise
549       an error if the image could not be pulled, even if the image is present
550       locally.
551
552
553       If  the  option  is disabled (with --pull=false) or not specified, pull
554       the image from the registry only if the image is not  present  locally.
555       Raise  an  error if the image is not found in the registries and is not
556       present locally.
557
558
559   --pull-always
560       Pull the image from the first registry it is found in as listed in reg‐
561       istries.conf.  Raise  an  error if not found in the registries, even if
562       the image is present locally.
563
564
565   --pull-never
566       Do not pull the image from the registry, use only  the  local  version.
567       Raise an error if the image is not present locally.
568
569
570   --quiet, -q
571       Suppress output messages which indicate which instruction is being pro‐
572       cessed, and of progress when pulling images from a registry,  and  when
573       writing the output image.
574
575
576   --rm=true|false
577       Remove intermediate containers after a successful build (default true).
578
579
580   --runtime=path
581       The  path to an alternate OCI-compatible runtime, which will be used to
582       run commands specified by the RUN instruction.
583
584
585       Note: You can also override the default runtime by  setting  the  BUIL‐
586       DAH_RUNTIME   environment  variable.   export  BUILDAH_RUNTIME=/usr/lo‐
587       cal/bin/runc
588
589
590   --secret=id=id,src=path
591       Pass secret information to be used in the  Containerfile  for  building
592       images in a safe way that will not end up stored in the final image, or
593       be seen in other stages.  The secret will be mounted in  the  container
594       at the default location of /run/secrets/id.
595
596
597       To  later  use  the  secret,  use the --mount flag in a RUN instruction
598       within a Containerfile:
599
600
601       RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret
602
603
604   --security-opt=option
605       Security Options
606
607
608apparmor=unconfined : Turn off apparmor  confinement  for  the
609                container
610
611apparmor=your-profile  :  Set the apparmor confinement profile
612                for the container
613
614label=user:USER     : Set the label  user  for  the  container
615                processes
616
617label=role:ROLE      :  Set  the  label role for the container
618                processes
619
620label=type:TYPE     : Set the label process type for the  con‐
621                tainer processes
622
623label=level:LEVEL    :  Set  the label level for the container
624                processes
625
626label=filetype:TYPE : Set the label file  type  for  the  con‐
627                tainer files
628
629label=disable        :  Turn off label separation for the con‐
630                tainer
631
632no-new-privileges   : Not supported
633
634seccomp=unconfined : Turn off seccomp confinement for the con‐
635                tainer
636
637seccomp=profile.json  :   White  listed  syscalls seccomp Json
638                file to be used as a seccomp filter
639
640
641
642   --shm-size=size
643       Size of /dev/shm. The format is <number><unit>. number must be  greater
644       than  0.   Unit  is  optional  and  can  be  b  (bytes), k (kilobytes),
645       m(megabytes), or g (gigabytes). If you omit the unit, the  system  uses
646       bytes. If you omit the size entirely, the system uses 64m.
647
648
649   --sign-by=fingerprint
650       Sign  the  image  using a GPG key with the specified FINGERPRINT. (This
651       option is not available with the remote Podman client)
652
653
654   --squash
655       Squash all of the image's new layers into a single new layer; any  pre‐
656       existing layers are not squashed.
657
658
659   --squash-all
660       Squash  all of the new image's layers (including those inherited from a
661       base image) into a single new layer.
662
663
664   --ssh=default|id[=socket>|[,]
665       SSH agent socket or keys to expose to the build.  The socket  path  can
666       be left empty to use the value of default=$SSH_AUTH_SOCK
667
668
669       To  later  use the ssh agent, use the --mount flag in a RUN instruction
670       within a Containerfile:
671
672
673       RUN --mount=type=ssh,id=id mycmd
674
675
676   --stdin
677       Pass stdin into the RUN containers. Sometime commands being RUN  within
678       a  Containerfile want to request information from the user. For example
679       apt asking for a confirmation for install.  Use --stdin to be  able  to
680       interact from the terminal during the build.
681
682
683   --tag, -t=imageName
684       Specifies the name which will be assigned to the resulting image if the
685       build process completes successfully.  If imageName does not include  a
686       registry name, the registry name localhost will be prepended to the im‐
687       age name.
688
689
690   --target=stageName
691       Set the target build stage to build.   When  building  a  Containerfile
692       with multiple build stages, --target can be used to specify an interme‐
693       diate build stage by name as the final stage for the  resulting  image.
694       Commands after the target stage will be skipped.
695
696
697   --timestamp seconds
698       Set  the create timestamp to seconds since epoch to allow for determin‐
699       istic builds (defaults to current time). By default, the created  time‐
700       stamp is changed and written into the image manifest with every commit,
701       causing the image's sha256 hash to be different even if the sources are
702       exactly the same otherwise.  When --timestamp is set, the created time‐
703       stamp is always set to the time specified and  therefore  not  changed,
704       allowing  the image's sha256 hash to remain the same. All files commit‐
705       ted to the layers of the image will be created with the timestamp.
706
707
708   --tls-verify=true|false
709       Require HTTPS and verify certificates when talking  to  container  reg‐
710       istries  (defaults to true). (This option is not available with the re‐
711       mote Podman client)
712
713
714   --ulimit=type=soft-limit[:hard-limit]
715       Specifies resource limits to apply to processes launched when  process‐
716       ing  RUN  instructions.  This  option  can be specified multiple times.
717       Recognized resource types include:
718         "core": maximum core dump size (ulimit -c)
719         "cpu": maximum CPU time (ulimit -t)
720         "data": maximum size of a process's data segment (ulimit -d)
721         "fsize": maximum size of new files (ulimit -f)
722         "locks": maximum number of file locks (ulimit -x)
723         "memlock": maximum amount of locked memory (ulimit -l)
724         "msgqueue": maximum amount of data in message queues (ulimit -q)
725         "nice": niceness adjustment (nice -n, ulimit -e)
726         "nofile": maximum number of open files (ulimit -n)
727         "nproc": maximum number of processes (ulimit -u)
728         "rss": maximum size of a process's (ulimit -m)
729         "rtprio": maximum real-time scheduling priority (ulimit -r)
730         "rttime": maximum amount  of  real-time  execution  between  blocking
731       syscalls
732         "sigpending": maximum number of pending signals (ulimit -i)
733         "stack": maximum stack size (ulimit -s)
734
735
736   --userns=how
737       Sets  the  configuration for user namespaces when handling RUN instruc‐
738       tions.  The configured value can be ""  (the  empty  string)  or  "con‐
739       tainer" to indicate that a new user namespace should be created, it can
740       be "host" to indicate that the user namespace in which podman itself is
741       being  run  should be reused, or it can be the path to a user namespace
742       which is already in use by another process.
743
744
745   --userns-uid-map=mapping
746       Directly specifies a UID mapping which should be used to set ownership,
747       at the filesystem level, on the working container's contents.  Commands
748       run when handling RUN instructions will default to being run  in  their
749       own user namespaces, configured using the UID and GID maps.
750
751
752       Entries  in this map take the form of one or more triples of a starting
753       in-container UID, a corresponding starting host-level UID, and the num‐
754       ber of consecutive IDs which the map entry represents.
755
756
757       This  option overrides the remap-uids setting in the options section of
758       /etc/containers/storage.conf.
759
760
761       If this option is not specified, but a global --userns-uid-map  setting
762       is supplied, settings from the global option will be used.
763
764
765       If  none of --userns-uid-map-user, --userns-gid-map-group, or --userns-
766       uid-map are specified, but --userns-gid-map is specified, the  UID  map
767       will be set to use the same numeric values as the GID map.
768
769
770   --userns-gid-map=mapping
771       Directly specifies a GID mapping which should be used to set ownership,
772       at the filesystem level, on the working container's contents.  Commands
773       run  when  handling RUN instructions will default to being run in their
774       own user namespaces, configured using the UID and GID maps.
775
776
777       Entries in this map take the form of one or more triples of a  starting
778       in-container GID, a corresponding starting host-level GID, and the num‐
779       ber of consecutive IDs which the map entry represents.
780
781
782       This option overrides the remap-gids setting in the options section  of
783       /etc/containers/storage.conf.
784
785
786       If  this option is not specified, but a global --userns-gid-map setting
787       is supplied, settings from the global option will be used.
788
789
790       If none of --userns-uid-map-user, --userns-gid-map-group, or  --userns-
791       gid-map  are  specified, but --userns-uid-map is specified, the GID map
792       will be set to use the same numeric values as the UID map.
793
794
795   --userns-uid-map-user=user
796       Specifies that a UID mapping which should be used to set ownership,  at
797       the filesystem level, on the working container's contents, can be found
798       in entries in the /etc/subuid file which correspond  to  the  specified
799       user.   Commands run when handling RUN instructions will default to be‐
800       ing run in their own user namespaces, configured using the UID and  GID
801       maps.   If  --userns-gid-map-group  is specified, but --userns-uid-map-
802       user is not specified, podman will assume that the specified group name
803       is also a suitable user name to use as the default setting for this op‐
804       tion.
805
806
807       NOTE: When this option is specified by a rootless user,  the  specified
808       mappings  are relative to the rootless user namespace in the container,
809       rather than being relative to the host as it would be  when  run  root‐
810       full.
811
812
813   --userns-gid-map-group=group
814       Specifies  that a GID mapping which should be used to set ownership, at
815       the filesystem level, on the working container's contents, can be found
816       in  entries  in  the /etc/subgid file which correspond to the specified
817       group.  Commands run when handling RUN instructions will default to be‐
818       ing  run in their own user namespaces, configured using the UID and GID
819       maps.  If --userns-uid-map-user  is  specified,  but  --userns-gid-map-
820       group is not specified, podman will assume that the specified user name
821       is also a suitable group name to use as the default  setting  for  this
822       option.
823
824
825       NOTE:  When  this option is specified by a rootless user, the specified
826       mappings are relative to the rootless user namespace in the  container,
827       rather  than  being  relative to the host as it would be when run root‐
828       full.
829
830
831   --uts=how
832       Sets the configuration for UTS namespaces when  the  handling  RUN  in‐
833       structions.  The configured value can be "" (the empty string) or "con‐
834       tainer" to indicate that a new UTS namespace should be created,  or  it
835       can be "host" to indicate that the UTS namespace in which podman itself
836       is being run should be reused, or it can be the path to a UTS namespace
837       which is already in use by another process.
838
839
840   --variant=""
841       Set  the architecture variant of the image to be built, and that of the
842       base image to be pulled, if the build uses one, to the  provided  value
843       instead of using the architecture variant of the build host.
844
845
846   --volume, -v[=[HOST-DIR:CONTAINER-DIR[:OPTIONS]]]
847       Create  a bind mount. If you specify, -v /HOST-DIR:/CONTAINER-DIR, Pod‐
848       man
849          bind mounts /HOST-DIR in the host to /CONTAINER-DIR in the Podman
850          container. (This option is not  available  with  the  remote  Podman
851       client)
852
853
854       The OPTIONS are a comma-separated list and can be: [1] ⟨#Footnote1⟩
855
856
857              • [rw|ro]
858
859              • [z|Z|O]
860
861              • [U]
862
863              • [[r]shared|[r]slave|[r]private]
864
865
866
867       The CONTAINER-DIR must be an absolute path such as /src/docs. The HOST-
868       DIR must be an absolute path as well. Podman bind-mounts  the  HOST-DIR
869       to  the  path  you specify. For example, if you supply /foo as the host
870       path, Podman copies the contents of /foo to the container filesystem on
871       the host and bind mounts that into the container.
872
873
874       You  can  specify multiple  -v options to mount one or more mounts to a
875       container.
876
877
878       You can add the :ro or :rw suffix to a volume to mount it read-only  or
879       read-write  mode,  respectively.  By  default,  the volumes are mounted
880       read-write.  See examples.
881
882
883       Chowning Volume Mounts
884
885
886       By default, Podman does not change the owner and group of source volume
887       directories  mounted.  When  running using user namespaces, the UID and
888       GID inside the namespace may correspond to another UID and GID  on  the
889       host.
890
891
892       The :U suffix tells Podman to use the correct host UID and GID based on
893       the UID and GID within the namespace, to change recursively  the  owner
894       and group of the source volume.
895
896
897       Warning use with caution since this will modify the host filesystem.
898
899
900       Labeling Volume Mounts
901
902
903       Labeling  systems like SELinux require that proper labels are placed on
904       volume content mounted into a container. Without a label, the  security
905       system  might  prevent  the processes running inside the container from
906       using the content. By default, Podman does not change the labels set by
907       the OS.
908
909
910       To  change  a label in the container context, you can add either of two
911       suffixes :z or :Z to the volume mount. These suffixes  tell  Podman  to
912       relabel  file  objects on the shared volumes. The z option tells Podman
913       that two containers share the volume content. As a result,  Podman  la‐
914       bels  the content with a shared content label. Shared volume labels al‐
915       low all containers to read/write content.  The Z option tells Podman to
916       label the content with a private unshared label.  Only the current con‐
917       tainer can use a private volume.
918
919
920       Note: Do not relabel system files and  directories.  Relabeling  system
921       content  might  cause  other confined services on your machine to fail.
922       For these types of containers, disabling SELinux separation  is  recom‐
923       mended.  The option --security-opt label=disable disables SELinux sepa‐
924       ration for the container.  For example, if  a  user  wanted  to  volume
925       mount  their entire home directory into the build containers, they need
926       to disable SELinux separation.
927
928
929                 $ podman build --security-opt label=disable -v $HOME:/home/user .
930
931
932
933       Overlay Volume Mounts
934
935
936       The :O flag tells Podman to mount the directory from the host as a tem‐
937       porary  storage using the Overlay file system. The RUN command contain‐
938       ers are allowed to modify contents within the mountpoint and are stored
939       in  the container storage in a separate directory.  In Overlay FS terms
940       the source directory will be the lower, and the container  storage  di‐
941       rectory  will  be  the  upper. Modifications to the mount point are de‐
942       stroyed when the RUN command finishes executing,  similar  to  a  tmpfs
943       mount point.
944
945
946       Any  subsequent  execution of RUN commands sees the original source di‐
947       rectory content, any changes from previous RUN commands no  longer  ex‐
948       ists.
949
950
951       One use case of the overlay mount is sharing the package cache from the
952       host into the container to allow speeding up builds.
953
954
955       Note:
956
957
958               - Overlay mounts are not currently supported in rootless mode.
959               - The `O` flag is not allowed to be specified with the `Z` or `z` flags.
960
961
962
963       Content mounted into the container is labeled with the private label.
964              On SELinux systems, labels in the source directory needs  to  be
965       readable  by  the container label. If not, SELinux container separation
966       must be disabled for the container to work.
967            - Modification of the directory volume mounted into the  container
968       with an overlay mount can cause unexpected failures.  It is recommended
969       that you do not modify the directory until the container finishes  run‐
970       ning.
971
972
973       By default bind mounted volumes are private. That means any mounts done
974       inside containers will not be visible on the host and vice versa.  This
975       behavior  can be changed by specifying a volume mount propagation prop‐
976       erty.
977
978
979       When the mount propagation policy is set to  shared,  any  mounts  com‐
980       pleted  inside the container on that volume will be visible to both the
981       host and container. When the mount propagation policy is set to  slave,
982       one  way  mount  propagation is enabled and any mounts completed on the
983       host for that volume will be visible only inside of the  container.  To
984       control  the  mount  propagation property of volume use the :[r]shared,
985       :[r]slave or :[r]private propagation flag. The propagation property can
986       be specified only for bind mounted volumes and not for internal volumes
987       or named volumes. For mount propagation to work  on  the  source  mount
988       point  (mount  point  where  source  dir is mounted on) has to have the
989       right propagation properties. For  shared  volumes,  the  source  mount
990       point  has to be shared. And for slave volumes, the source mount has to
991       be either shared or slave. [1] ⟨#Footnote1⟩
992
993
994       Use df <source-dir> to determine the source mount and then use  findmnt
995       -o TARGET,PROPAGATION <source-mount-dir> to determine propagation prop‐
996       erties of source mount, if findmnt utility is not available, the source
997       mount  point  can  be  determined  by  looking  at  the  mount entry in
998       /proc/self/mountinfo. Look at optional fields and see if  any  propaga‐
999       tion  properties  are  specified.   shared:X means the mount is shared,
1000       master:X means the mount is slave and if nothing is  there  that  means
1001       the mount is private. [1] ⟨#Footnote1⟩
1002
1003
1004       To  change  propagation  properties of a mount point use the mount com‐
1005       mand. For example, to bind mount the source  directory  /foo  do  mount
1006       --bind /foo /foo and mount --make-private --make-shared /foo. This will
1007       convert /foo into a shared mount point.  The propagation properties  of
1008       the  source  mount  can  be  changed directly. For instance if / is the
1009       source mount for /foo, then use mount --make-shared / to convert / into
1010       a shared mount.
1011
1012

EXAMPLES

1014   Build an image using local Containerfiles
1015              $ podman build .
1016
1017              $ podman build -f Containerfile.simple .
1018
1019              $ cat $HOME/Dockerfile | podman build -f - .
1020
1021              $ podman build -f Dockerfile.simple -f Containerfile.notsosimple .
1022
1023              $ podman build -f Dockerfile.in $HOME
1024
1025              $ podman build -t imageName .
1026
1027              $ podman build --tls-verify=true -t imageName -f Dockerfile.simple .
1028
1029              $ podman build --tls-verify=false -t imageName .
1030
1031              $ podman build --runtime-flag log-format=json .
1032
1033              $ podman build --runtime-flag debug .
1034
1035              $ podman build --authfile /tmp/auths/myauths.json --cert-dir $HOME/auth --tls-verify=true --creds=username:password -t imageName -f Dockerfile.simple .
1036
1037              $ podman build --memory 40m --cpu-period 10000 --cpu-quota 50000 --ulimit nofile=1024:1028 -t imageName .
1038
1039              $ podman build --security-opt label=level:s0:c100,c200 --cgroup-parent /path/to/cgroup/parent -t imageName .
1040
1041              $ podman build --volume /home/test:/myvol:ro,Z -t imageName .
1042
1043              $ podman build -v /var/lib/yum:/var/lib/yum:O -t imageName .
1044
1045              $ podman build --layers -t imageName .
1046
1047              $ podman build --no-cache -t imageName .
1048
1049              $ podman build --layers --force-rm -t imageName .
1050
1051              $ podman build --no-cache --rm=false -t imageName .
1052
1053
1054
1055   Building  a  multi-architecture image using the --manifest option (requires
1056       emulation software)
1057              $ podman build --arch arm --manifest myimage /tmp/mysrc
1058
1059              $ podman build --arch amd64 --manifest myimage /tmp/mysrc
1060
1061              $ podman build --arch s390x --manifest myimage /tmp/mysrc
1062
1063              $ podman build --platform linux/s390x,linux/ppc64le,linux/amd64 --manifest myimage /tmp/mysrc
1064
1065              $ podman build --platform linux/arm64 --platform linux/amd64 --manifest myimage /tmp/mysrc
1066
1067
1068
1069   Building an image using a URL, Git repo, or archive
1070       The build context directory can be specified as a URL to  a  Container‐
1071       file,  a Git repository, or URL to an archive. If the URL is a Contain‐
1072       erfile, it is downloaded to a temporary location and used as  the  con‐
1073       text. When a Git repository is set as the URL, the repository is cloned
1074       locally to a temporary location and then used as the  context.  Lastly,
1075       if  the URL is an archive, it is downloaded to a temporary location and
1076       extracted before being used as the context.
1077
1078
1079   Building an image using a URL to a Containerfile
1080       Podman will download the Containerfile to a temporary location and then
1081       use it as the build context.
1082
1083
1084              $ podman build https://10.10.10.1/podman/Containerfile
1085
1086
1087
1088   Building an image using a Git repository
1089       Podman  will clone the specified GitHub repository to a temporary loca‐
1090       tion and use it as the context. The Containerfile at the  root  of  the
1091       repository will be used and it only works if the GitHub repository is a
1092       dedicated repository.
1093
1094
1095              $ podman build git://github.com/scollier/purpletest
1096
1097
1098
1099   Building an image using a URL to an archive
1100       Podman will fetch the archive file, decompress it, and use its contents
1101       as  the build context. The Containerfile at the root of the archive and
1102       the rest of the archive will get used as the context of the  build.  If
1103       you pass -f PATH/Containerfile option as well, the system will look for
1104       that file inside the contents of the archive.
1105
1106
1107              $ podman build -f dev/Containerfile https://10.10.10.1/podman/context.tar.gz
1108
1109
1110
1111       Note: supported compression  formats  are  'xz',  'bzip2',  'gzip'  and
1112       'identity' (no compression).
1113
1114

Files

1116   .dockerignore
1117       If the file .dockerignore exists in the context directory, buildah copy
1118       reads its contents. Use the --ignorefile flag to override .dockerignore
1119       path  location.   Podman uses the content to exclude files and directo‐
1120       ries from the context directory, when executing COPY and ADD directives
1121       in the Containerfile/Dockerfile
1122
1123
1124       Users  can  specify  a  series of Unix shell globals in a .dockerignore
1125       file to identify files/directories to exclude.
1126
1127
1128       Podman supports a special wildcard string ** which matches  any  number
1129       of  directories  (including  zero). For example, */.go will exclude all
1130       files that end with .go that are found in all directories.
1131
1132
1133       Example .dockerignore file:
1134
1135
1136              # exclude this content for image
1137              */*.c
1138              **/output*
1139              src
1140
1141
1142
1143       */*.c Excludes files and directories whose names ends with  .c  in  any
1144       top  level  subdirectory.  For  example,  the source file include/root‐
1145       less.c.
1146
1147
1148       **/output* Excludes files and directories starting with output from any
1149       directory.
1150
1151
1152       src  Excludes files named src and the directory src as well as any con‐
1153       tent in it.
1154
1155
1156       Lines starting with ! (exclamation mark) can be used to make exceptions
1157       to exclusions. The following is an example .dockerignore file that uses
1158       this mechanism:
1159
1160
1161              *.doc
1162              !Help.doc
1163
1164
1165
1166       Exclude all doc files except Help.doc from the image.
1167
1168
1169       This functionality is compatible with  the  handling  of  .dockerignore
1170       files described here:
1171
1172
1173       https://docs.docker.com/engine/reference/builder/#dockerignore-file
1174
1175
1176       registries.conf (/etc/containers/registries.conf)
1177
1178
1179       registries.conf  is  the  configuration file which specifies which con‐
1180       tainer registries should be consulted when completing image names which
1181       do not include a registry or domain portion.
1182
1183

Troubleshooting

1185   lastlog sparse file
1186       If  you are using a useradd command within a Containerfile with a large
1187       UID/GID, it will create a large sparse file /var/log/lastlog.  This can
1188       cause  the  build to hang forever.  Go language does not support sparse
1189       files correctly, which can lead to some huge  files  being  created  in
1190       your container image.
1191
1192
1193       If  you are using useradd within your build script, you should pass the
1194       --no-log-init or -l option to the useradd command.  This  option  tells
1195       useradd to stop creating the lastlog file.
1196
1197

SEE ALSO

1199       podman(1),     buildah(1),    containers-certs.d(5),    containers-reg‐
1200       istries.conf(5), crun(8), runc(8),  useradd(8),  podman-ps(1),  podman-
1201       rm(1)
1202
1203

HISTORY

1205       Aug  2020,  Additional  options  and  .dockerignore  added by Dan Walsh
1206       <dwalsh@redhat.com>
1207
1208
1209       May 2018, Minor revisions added by Joe Doss <joe@solidadmin.com>
1210
1211
1212       December 2017, Originally compiled by Tom Sweeney <tsweeney@redhat.com>
1213
1214

FOOTNOTES

1216       1: The Podman project is committed to inclusivity, a core value of open
1217       source. The master and slave mount propagation terminology used here is
1218       problematic and divisive, and should be changed.  However, these  terms
1219       are  currently  used  within the Linux kernel and must be used as-is at
1220       this time. When the kernel maintainers rectify this usage, Podman  will
1221       follow suit immediately.
1222
1223
1224
1225                                                             podman-build(1)()
Impressum