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

EXAMPLES

912   Build an image using local Containerfiles
913              $ podman build .
914
915              $ podman build -f Containerfile.simple .
916
917              $ cat $HOME/Dockerfile | podman build -f - .
918
919              $ podman build -f Dockerfile.simple -f Containerfile.notsosimple .
920
921              $ podman build -f Dockerfile.in $HOME
922
923              $ podman build -t imageName .
924
925              $ podman build --tls-verify=true -t imageName -f Dockerfile.simple .
926
927              $ podman build --tls-verify=false -t imageName .
928
929              $ podman build --runtime-flag log-format=json .
930
931              $ podman build --runtime-flag debug .
932
933              $ podman build --authfile /tmp/auths/myauths.json --cert-dir $HOME/auth --tls-verify=true --creds=username:password -t imageName -f Dockerfile.simple .
934
935              $ podman build --memory 40m --cpu-period 10000 --cpu-quota 50000 --ulimit nofile=1024:1028 -t imageName .
936
937              $ podman build --security-opt label=level:s0:c100,c200 --cgroup-parent /path/to/cgroup/parent -t imageName .
938
939              $ podman build --volume /home/test:/myvol:ro,Z -t imageName .
940
941              $ podman build -v /var/lib/yum:/var/lib/yum:O -t imageName .
942
943              $ podman build --layers -t imageName .
944
945              $ podman build --no-cache -t imageName .
946
947              $ podman build --layers --force-rm -t imageName .
948
949              $ podman build --no-cache --rm=false -t imageName .
950
951
952
953   Building  an  multi-architecture  image using a --manifest option (Requires
954       emulation software)
955       podman build --arch arm  --manifest  myimage  /tmp/mysrc  podman  build
956       --arch  amd64  --manifest  myimage /tmp/mysrc podman build --arch s390x
957       --manifest myimage /tmp/mysrc
958
959
960   Building an image using a URL, Git repo, or archive
961       The build context directory can be specified as a URL to  a  Container‐
962       file,  a Git repository, or URL to an archive. If the URL is a Contain‐
963       erfile, it is downloaded to a temporary location and used as  the  con‐
964       text. When a Git repository is set as the URL, the repository is cloned
965       locally to a temporary location and then used as the  context.  Lastly,
966       if  the URL is an archive, it is downloaded to a temporary location and
967       extracted before being used as the context.
968
969
970   Building an image using a URL to a Containerfile
971       Podman will download the Containerfile to a temporary location and then
972       use it as the build context.
973
974
975              $ podman build https://10.10.10.1/podman/Containerfile
976
977
978
979   Building an image using a Git repository
980       Podman  will clone the specified GitHub repository to a temporary loca‐
981       tion and use it as the context. The Containerfile at the  root  of  the
982       repository will be used and it only works if the GitHub repository is a
983       dedicated repository.
984
985
986              $ podman build git://github.com/scollier/purpletest
987
988
989
990   Building an image using a URL to an archive
991       Podman will fetch the archive file, decompress it, and use its contents
992       as  the build context. The Containerfile at the root of the archive and
993       the rest of the archive will get used as the context of the  build.  If
994       you pass -f PATH/Containerfile option as well, the system will look for
995       that file inside the contents of the archive.
996
997
998              $ podman build -f dev/Containerfile https://10.10.10.1/podman/context.tar.gz
999
1000
1001
1002       Note: supported compression  formats  are  'xz',  'bzip2',  'gzip'  and
1003       'identity' (no compression).
1004
1005

Files

1007   .dockerignore
1008       If the file .dockerignore exists in the context directory, buildah copy
1009       reads its contents. Use the --ignorefile flag to override .dockerignore
1010       path  location.   Podman uses the content to exclude files and directo‐
1011       ries from the context directory, when executing COPY and ADD directives
1012       in the Containerfile/Dockerfile
1013
1014
1015       Users  can  specify  a  series of Unix shell globals in a .dockerignore
1016       file to identify files/directories to exclude.
1017
1018
1019       Podman supports a special wildcard string ** which matches  any  number
1020       of  directories  (including  zero). For example, */.go will exclude all
1021       files that end with .go that are found in all directories.
1022
1023
1024       Example .dockerignore file:
1025
1026
1027              # exclude this content for image
1028              */*.c
1029              **/output*
1030              src
1031
1032
1033
1034       */*.c Excludes files and directories whose names ends with  .c  in  any
1035       top  level  subdirectory.  For  example,  the source file include/root‐
1036       less.c.
1037
1038
1039       **/output* Excludes files and directories starting with output from any
1040       directory.
1041
1042
1043       src  Excludes files named src and the directory src as well as any con‐
1044       tent in it.
1045
1046
1047       Lines starting with ! (exclamation mark) can be used to make exceptions
1048       to exclusions. The following is an example .dockerignore file that uses
1049       this mechanism:
1050
1051
1052              *.doc
1053              !Help.doc
1054
1055
1056
1057       Exclude all doc files except Help.doc from the image.
1058
1059
1060       This functionality is compatible with  the  handling  of  .dockerignore
1061       files described here:
1062
1063
1064       https://docs.docker.com/engine/reference/builder/#dockerignore-file
1065
1066
1067       registries.conf (/etc/containers/registries.conf)
1068
1069
1070       registries.conf  is  the  configuration file which specifies which con‐
1071       tainer registries should be consulted when completing image names which
1072       do not include a registry or domain portion.
1073
1074

Troubleshooting

1076   lastlog sparse file
1077       If  you are using a useradd command within a Containerfile with a large
1078       UID/GID, it will create a large sparse file /var/log/lastlog.  This can
1079       cause  the  build to hang forever.  Go language does not support sparse
1080       files correctly, which can lead to some huge  files  being  created  in
1081       your container image.
1082
1083
1084       If  you are using useradd within your build script, you should pass the
1085       --no-log-init or -l option to the useradd command.  This  option  tells
1086       useradd to stop creating the lastlog file.
1087
1088

SEE ALSO

1090       podman(1), buildah(1), containers-registries.conf(5), crun(8), runc(8),
1091       useradd(8), podman-ps(1), podman-rm(1)
1092
1093

HISTORY

1095       Aug 2020, Additional options  and  .dockerignore  added  by  Dan  Walsh
1096       dwalsh@redhat.com ⟨mailto:dwalsh@redhat.com⟩
1097
1098
1099       May   2018,  Minor  revisions  added  by  Joe  Doss  joe@solidadmin.com
1100       ⟨mailto:joe@solidadmin.com⟩
1101
1102
1103       December 2017, Originally compiled by Tom  Sweeney  tsweeney@redhat.com
1104       ⟨mailto:tsweeney@redhat.com⟩
1105
1106

FOOTNOTES

1108       1: The Podman project is committed to inclusivity, a core value of open
1109       source. The master and slave mount propagation terminology used here is
1110       problematic  and divisive, and should be changed.  However, these terms
1111       are currently used within the Linux kernel and must be  used  as-is  at
1112       this  time. When the kernel maintainers rectify this usage, Podman will
1113       follow suit immediately.
1114
1115
1116
1117                                                             podman-build(1)()
Impressum