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

OPTIONS

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

EXAMPLES

957   Build an image using local Containerfiles
958              $ podman build .
959
960              $ podman build -f Containerfile.simple .
961
962              $ cat $HOME/Dockerfile | podman build -f - .
963
964              $ podman build -f Dockerfile.simple -f Containerfile.notsosimple .
965
966              $ podman build -f Dockerfile.in $HOME
967
968              $ podman build -t imageName .
969
970              $ podman build --tls-verify=true -t imageName -f Dockerfile.simple .
971
972              $ podman build --tls-verify=false -t imageName .
973
974              $ podman build --runtime-flag log-format=json .
975
976              $ podman build --runtime-flag debug .
977
978              $ podman build --authfile /tmp/auths/myauths.json --cert-dir $HOME/auth --tls-verify=true --creds=username:password -t imageName -f Dockerfile.simple .
979
980              $ podman build --memory 40m --cpu-period 10000 --cpu-quota 50000 --ulimit nofile=1024:1028 -t imageName .
981
982              $ podman build --security-opt label=level:s0:c100,c200 --cgroup-parent /path/to/cgroup/parent -t imageName .
983
984              $ podman build --volume /home/test:/myvol:ro,Z -t imageName .
985
986              $ podman build -v /var/lib/yum:/var/lib/yum:O -t imageName .
987
988              $ podman build --layers -t imageName .
989
990              $ podman build --no-cache -t imageName .
991
992              $ podman build --layers --force-rm -t imageName .
993
994              $ podman build --no-cache --rm=false -t imageName .
995
996
997
998   Building  an  multi-architecture  image using a --manifest option (Requires
999       emulation software)
1000              $ podman build --arch arm --manifest myimage /tmp/mysrc
1001
1002              $ podman build --arch amd64 --manifest myimage /tmp/mysrc
1003
1004              $ podman build --arch s390x --manifest myimage /tmp/mysrc
1005
1006
1007
1008   Building an image using a URL, Git repo, or archive
1009       The build context directory can be specified as a URL to  a  Container‐
1010       file,  a Git repository, or URL to an archive. If the URL is a Contain‐
1011       erfile, it is downloaded to a temporary location and used as  the  con‐
1012       text. When a Git repository is set as the URL, the repository is cloned
1013       locally to a temporary location and then used as the  context.  Lastly,
1014       if  the URL is an archive, it is downloaded to a temporary location and
1015       extracted before being used as the context.
1016
1017
1018   Building an image using a URL to a Containerfile
1019       Podman will download the Containerfile to a temporary location and then
1020       use it as the build context.
1021
1022
1023              $ podman build https://10.10.10.1/podman/Containerfile
1024
1025
1026
1027   Building an image using a Git repository
1028       Podman  will clone the specified GitHub repository to a temporary loca‐
1029       tion and use it as the context. The Containerfile at the  root  of  the
1030       repository will be used and it only works if the GitHub repository is a
1031       dedicated repository.
1032
1033
1034              $ podman build git://github.com/scollier/purpletest
1035
1036
1037
1038   Building an image using a URL to an archive
1039       Podman will fetch the archive file, decompress it, and use its contents
1040       as  the build context. The Containerfile at the root of the archive and
1041       the rest of the archive will get used as the context of the  build.  If
1042       you pass -f PATH/Containerfile option as well, the system will look for
1043       that file inside the contents of the archive.
1044
1045
1046              $ podman build -f dev/Containerfile https://10.10.10.1/podman/context.tar.gz
1047
1048
1049
1050       Note: supported compression  formats  are  'xz',  'bzip2',  'gzip'  and
1051       'identity' (no compression).
1052
1053

Files

1055   .dockerignore
1056       If the file .dockerignore exists in the context directory, buildah copy
1057       reads its contents. Use the --ignorefile flag to override .dockerignore
1058       path  location.   Podman uses the content to exclude files and directo‐
1059       ries from the context directory, when executing COPY and ADD directives
1060       in the Containerfile/Dockerfile
1061
1062
1063       Users  can  specify  a  series of Unix shell globals in a .dockerignore
1064       file to identify files/directories to exclude.
1065
1066
1067       Podman supports a special wildcard string ** which matches  any  number
1068       of  directories  (including  zero). For example, */.go will exclude all
1069       files that end with .go that are found in all directories.
1070
1071
1072       Example .dockerignore file:
1073
1074
1075              # exclude this content for image
1076              */*.c
1077              **/output*
1078              src
1079
1080
1081
1082       */*.c Excludes files and directories whose names ends with  .c  in  any
1083       top  level  subdirectory.  For  example,  the source file include/root‐
1084       less.c.
1085
1086
1087       **/output* Excludes files and directories starting with output from any
1088       directory.
1089
1090
1091       src  Excludes files named src and the directory src as well as any con‐
1092       tent in it.
1093
1094
1095       Lines starting with ! (exclamation mark) can be used to make exceptions
1096       to exclusions. The following is an example .dockerignore file that uses
1097       this mechanism:
1098
1099
1100              *.doc
1101              !Help.doc
1102
1103
1104
1105       Exclude all doc files except Help.doc from the image.
1106
1107
1108       This functionality is compatible with  the  handling  of  .dockerignore
1109       files described here:
1110
1111
1112       https://docs.docker.com/engine/reference/builder/#dockerignore-file
1113
1114
1115       registries.conf (/etc/containers/registries.conf)
1116
1117
1118       registries.conf  is  the  configuration file which specifies which con‐
1119       tainer registries should be consulted when completing image names which
1120       do not include a registry or domain portion.
1121
1122

Troubleshooting

1124   lastlog sparse file
1125       If  you are using a useradd command within a Containerfile with a large
1126       UID/GID, it will create a large sparse file /var/log/lastlog.  This can
1127       cause  the  build to hang forever.  Go language does not support sparse
1128       files correctly, which can lead to some huge  files  being  created  in
1129       your container image.
1130
1131
1132       If  you are using useradd within your build script, you should pass the
1133       --no-log-init or -l option to the useradd command.  This  option  tells
1134       useradd to stop creating the lastlog file.
1135
1136

SEE ALSO

1138       podman(1),     buildah(1),    containers-certs.d(5),    containers-reg‐
1139       istries.conf(5),  crun(8),  runc(8),  useradd(8),  podman-ps(1),   pod‐
1140       man-rm(1)
1141
1142

HISTORY

1144       Aug  2020,  Additional  options  and  .dockerignore  added by Dan Walsh
1145       <dwalsh@redhat.com>
1146
1147
1148       May 2018, Minor revisions added by Joe Doss <joe@solidadmin.com>
1149
1150
1151       December 2017, Originally compiled by Tom Sweeney <tsweeney@redhat.com>
1152
1153

FOOTNOTES

1155       1: The Podman project is committed to inclusivity, a core value of open
1156       source. The master and slave mount propagation terminology used here is
1157       problematic and divisive, and should be changed.  However, these  terms
1158       are  currently  used  within the Linux kernel and must be used as-is at
1159       this time. When the kernel maintainers rectify this usage, Podman  will
1160       follow suit immediately.
1161
1162
1163
1164                                                             podman-build(1)()
Impressum