1podman-create(1)            General Commands Manual           podman-create(1)
2
3
4

NAME

6       podman-create - Create a new container
7
8

SYNOPSIS

10       podman create [options] image [command [arg ...]]
11
12
13       podman container create [options] image [command [arg ...]]
14
15

DESCRIPTION

17       Creates  a  writable  container layer over the specified image and pre‐
18       pares it for running the specified command. The container  ID  is  then
19       printed  to  STDOUT.  This  is similar to podman run -d except the con‐
20       tainer is never started. You can then use the  podman  start  container
21       command to start the container at any point.
22
23
24       The initial status of the container created with podman create is 'cre‐
25       ated'.
26
27
28       Default settings for flags are defined in  containers.conf.  Most  set‐
29       tings  for  remote connections use the server's containers.conf, except
30       when documented in man pages.
31
32

IMAGE

34       The image is specified using transport:path format. If no transport  is
35       specified,  the  docker  (container registry) transport will be used by
36       default. For remote Podman, including Mac and Windows (excluding  WSL2)
37       machines, docker is the only allowed transport.
38
39
40       dir:path
41         An existing local directory path storing the manifest, layer tarballs
42       and signatures as individual files. This is a non-standardized  format,
43       primarily useful for debugging or noninvasive container inspection.
44
45
46              $ podman save --format docker-dir fedora -o /tmp/fedora
47              $ podman create dir:/tmp/fedora echo hello
48
49
50
51       docker://docker-reference (Default)
52         An  image reference stored in  a remote container image registry. Ex‐
53       ample: "quay.io/podman/stable:latest".  The  reference  can  include  a
54       path  to  a specific registry; if it does not, the registries listed in
55       registries.conf will be queried to find a matching image.  By  default,
56       credentials  from  podman  login  (stored  at $XDG_RUNTIME_DIR/contain‐
57       ers/auth.json by default) will be used to  authenticate;  otherwise  it
58       falls back to using credentials in $HOME/.docker/config.json.
59
60
61              $ podman create registry.fedoraproject.org/fedora:latest echo hello
62
63
64
65       docker-archive:path[:docker-reference]  An  image  stored in the docker
66       save formatted file. docker-reference is only used when creating such a
67       file, and it must not contain a digest.
68
69
70              $ podman save --format docker-archive fedora -o /tmp/fedora
71              $ podman create docker-archive:/tmp/fedora echo hello
72
73
74
75       docker-daemon:docker-reference
76         An  image  in docker-reference format stored in the docker daemon in‐
77       ternal storage. The docker-reference can also be an image  ID  (docker-
78       daemon:algo:digest).
79
80
81              $ sudo docker pull fedora
82              $ sudo podman create docker-daemon:docker.io/library/fedora echo hello
83
84
85
86       oci-archive:path:tag
87         An image in a directory compliant with the "Open Container Image Lay‐
88       out Specification" at the specified path and specified with a tag.
89
90
91              $ podman save --format oci-archive fedora -o /tmp/fedora
92              $ podman create oci-archive:/tmp/fedora echo hello
93
94
95

OPTIONS

97   --add-host=host:ip
98       Add a custom host-to-IP mapping (host:ip)
99
100
101       Add a line to /etc/hosts. The format is hostname:ip. The --add-host op‐
102       tion can be set multiple times. Conflicts with the --no-hosts option.
103
104
105   --annotation=key=value
106       Add  an  annotation  to  the container. This option can be set multiple
107       times.
108
109
110   --arch=ARCH
111       Override the architecture, defaults  to  hosts,  of  the  image  to  be
112       pulled. For example, arm.  Unless overridden, subsequent lookups of the
113       same image in the local storage will match this  architecture,  regard‐
114       less of the host.
115
116
117   --attach, -a=stdin | stdout | stderr
118       Attach to STDIN, STDOUT or STDERR.
119
120
121       In  foreground  mode (the default when -d is not specified), podman run
122       can start the process in the container and attach the  console  to  the
123       process's  standard input, output, and error. It can even pretend to be
124       a TTY (this is what most  command-line  executables  expect)  and  pass
125       along  signals. The -a option can be set for each of stdin, stdout, and
126       stderr.
127
128
129   --authfile=path
130       Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
131       ers/auth.json,  which  is set using podman login.  If the authorization
132       state is not found there, $HOME/.docker/config.json is  checked,  which
133       is set using docker login.
134
135
136       Note:  There is also the option to override the default path of the au‐
137       thentication file by setting the REGISTRY_AUTH_FILE  environment  vari‐
138       able. This can be done with export REGISTRY_AUTH_FILE=path.
139
140
141   --blkio-weight=weight
142       Block IO relative weight. The weight is a value between 10 and 1000.
143
144
145       This option is not supported on cgroups V1 rootless systems.
146
147
148   --blkio-weight-device=device:weight
149       Block IO relative device weight.
150
151
152   --cap-add=capability
153       Add Linux capabilities.
154
155
156   --cap-drop=capability
157       Drop Linux capabilities.
158
159
160   --cgroup-conf=KEY=VALUE
161       When  running on cgroup v2, specify the cgroup file to write to and its
162       value. For example --cgroup-conf=memory.high=1073741824 sets  the  mem‐
163       ory.high limit to 1GB.
164
165
166   --cgroup-parent=path
167       Path  to  cgroups under which the cgroup for the container will be cre‐
168       ated. If the path is not absolute, the path is considered to  be  rela‐
169       tive  to  the cgroups path of the init process. Cgroups will be created
170       if they do not already exist.
171
172
173   --cgroupns=mode
174       Set the cgroup namespace mode for the container.
175
176
177host: use the host's cgroup namespace inside the container.
178
179container:id: join the namespace of the specified container.
180
181private: create a new cgroup namespace.
182
183ns:path: join the namespace at the specified path.
184
185
186
187       If the host uses cgroups v1, the default is set to host. On cgroups v2,
188       the default is private.
189
190
191   --cgroups=how
192       Determines whether the container will create CGroups.
193
194
195       Default is enabled.
196
197
198       The  enabled  option  will create a new cgroup under the cgroup-parent.
199       The disabled option will force the container to not create CGroups, and
200       thus  conflicts  with  CGroup options (--cgroupns and --cgroup-parent).
201       The no-conmon option disables a new CGroup only for the conmon process.
202       The  split option splits the current CGroup in two sub-cgroups: one for
203       conmon and one for the container payload. It is  not  possible  to  set
204       --cgroup-parent with split.
205
206
207   --chrootdirs=path
208       Path  to  a  directory inside the container that should be treated as a
209       chroot directory.  Any Podman  managed  file  (e.g.,  /etc/resolv.conf,
210       /etc/hosts,  etc/hostname) that is mounted into the root directory will
211       be mounted into that location as well.  Multiple directories should  be
212       separated with a comma.
213
214
215   --cidfile=file
216       Write the container ID to file.
217
218
219   --conmon-pidfile=file
220       Write the pid of the conmon process to a file. As conmon runs in a sep‐
221       arate process than Podman, this is  necessary  when  using  systemd  to
222       restart  Podman containers.  (This option is not available with the re‐
223       mote Podman client, including Mac  and  Windows  (excluding  WSL2)  ma‐
224       chines)
225
226
227   --cpu-period=limit
228       Set  the CPU period for the Completely Fair Scheduler (CFS), which is a
229       duration in microseconds. Once the container's CPU quota is used up, it
230       will not be scheduled to run until the current period ends. Defaults to
231       100000 microseconds.
232
233
234       On some systems, changing the resource limits may not  be  allowed  for
235       non-root  users.  For  more  details,  see  https://github.com/contain
236       ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
237       source-limits-fails-with-a-permissions-error
238
239
240       This option is not supported on cgroups V1 rootless systems.
241
242
243   --cpu-quota=limit
244       Limit the CPU Completely Fair Scheduler (CFS) quota.
245
246
247       Limit  the  container's  CPU usage. By default, containers run with the
248       full CPU resource. The limit is a number in microseconds. If  a  number
249       is  provided,  the  container will be allowed to use that much CPU time
250       until the CPU period ends (controllable via --cpu-period).
251
252
253       On some systems, changing the resource limits may not  be  allowed  for
254       non-root  users.  For  more  details,  see  https://github.com/contain
255       ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
256       source-limits-fails-with-a-permissions-error
257
258
259       This option is not supported on cgroups V1 rootless systems.
260
261
262   --cpu-rt-period=microseconds
263       Limit the CPU real-time period in microseconds.
264
265
266       Limit the container's Real Time CPU usage. This option tells the kernel
267       to restrict the container's Real Time CPU usage to  the  period  speci‐
268       fied.
269
270
271       This option is only supported on cgroups V1 rootful systems.
272
273
274   --cpu-rt-runtime=microseconds
275       Limit the CPU real-time runtime in microseconds.
276
277
278       Limit  the containers Real Time CPU usage. This option tells the kernel
279       to limit the amount of time in a given CPU period Real Time  tasks  may
280       consume.  Ex: Period of 1,000,000us and Runtime of 950,000us means that
281       this container could consume 95% of available CPU and leave the remain‐
282       ing 5% to normal priority tasks.
283
284
285       The  sum of all runtimes across containers cannot exceed the amount al‐
286       lotted to the parent cgroup.
287
288
289       This option is only supported on cgroups V1 rootful systems.
290
291
292   --cpu-shares, -c=shares
293       CPU shares (relative weight).
294
295
296       By default, all containers get the same proportion of CPU cycles.  This
297       proportion  can  be  modified  by  changing  the  container's CPU share
298       weighting relative to the combined weight of all the  running  contain‐
299       ers.  Default weight is 1024.
300
301
302       The  proportion  will  only apply when CPU-intensive processes are run‐
303       ning.  When tasks in one container are idle, other containers  can  use
304       the left-over CPU time. The actual amount of CPU time will vary depend‐
305       ing on the number of containers running on the system.
306
307
308       For example, consider three containers, one has a cpu-share of 1024 and
309       two others have a cpu-share setting of 512. When processes in all three
310       containers attempt to use 100% of CPU, the first  container  would  re‐
311       ceive  50% of the total CPU time. If a fourth container is added with a
312       cpu-share of 1024, the first container only gets 33% of  the  CPU.  The
313       remaining containers receive 16.5%, 16.5% and 33% of the CPU.
314
315
316       On a multi-core system, the shares of CPU time are distributed over all
317       CPU cores. Even if a container is limited to  less  than  100%  of  CPU
318       time, it can use 100% of each individual CPU core.
319
320
321       For example, consider a system with more than three cores.  If the con‐
322       tainer C0 is started with --cpu-shares=512 running one process, and an‐
323       other  container  C1 with --cpu-shares=1024 running two processes, this
324       can result in the following division of CPU shares:
325
326
327       ┌────┬───────────┬─────┬──────────────┐
328PID container CPU CPU share    
329       ├────┼───────────┼─────┼──────────────┤
330       │100 │ C0        │ 0   │ 100% of CPU0 │
331       ├────┼───────────┼─────┼──────────────┤
332       │101 │ C1        │ 1   │ 100% of CPU1 │
333       ├────┼───────────┼─────┼──────────────┤
334       │102 │ C1        │ 2   │ 100% of CPU2 │
335       └────┴───────────┴─────┴──────────────┘
336
337       On some systems, changing the resource limits may not  be  allowed  for
338       non-root  users.  For  more  details,  see  https://github.com/contain
339       ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
340       source-limits-fails-with-a-permissions-error
341
342
343       This option is not supported on cgroups V1 rootless systems.
344
345
346   --cpus=number
347       Number of CPUs. The default is 0.0 which means no limit. This is short‐
348       hand for --cpu-period and --cpu-quota,  so  you  may  only  set  either
349       --cpus or --cpu-period and --cpu-quota.
350
351
352       On  some  systems,  changing the CPU limits may not be allowed for non-
353       root users. For more  details,  see  https://github.com/containers/pod
354       man/blob/main/troubleshooting.md#26-running-containers-with-resource-
355       limits-fails-with-a-permissions-error
356
357
358       This option is not supported on cgroups V1 rootless systems.
359
360
361   --cpuset-cpus=number
362       CPUs in which to allow execution. Can be specified as a comma-separated
363       list  (e.g.  0,1),  as  a  range (e.g. 0-3), or any combination thereof
364       (e.g. 0-3,7,11-15).
365
366
367       On some systems, changing the resource limits may not  be  allowed  for
368       non-root  users.  For  more  details,  see  https://github.com/contain
369       ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
370       source-limits-fails-with-a-permissions-error
371
372
373       This option is not supported on cgroups V1 rootless systems.
374
375
376   --cpuset-mems=nodes
377       Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effec‐
378       tive on NUMA systems.
379
380
381       If there are four memory nodes  on  the  system  (0-3),  use  --cpuset-
382       mems=0,1  then processes in the container will only use memory from the
383       first two memory nodes.
384
385
386       On some systems, changing the resource limits may not  be  allowed  for
387       non-root  users.  For  more  details,  see  https://github.com/contain
388       ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
389       source-limits-fails-with-a-permissions-error
390
391
392       This option is not supported on cgroups V1 rootless systems.
393
394
395   --device=host-device[:container-device][:permissions]
396       Add  a host device to the container. Optional permissions parameter can
397       be used to specify device permissions by combining r for  read,  w  for
398       write, and m for mknod(2).
399
400
401       Example: --device=/dev/sdc:/dev/xvdc:rwm.
402
403
404       Note: if host-device is a symbolic link then it will be resolved first.
405       The container will only store the major and minor numbers of  the  host
406       device.
407
408
409       Podman may load kernel modules required for using the specified device.
410       The devices that Podman will  load  modules  for  when  necessary  are:
411       /dev/fuse.
412
413
414       In  rootless mode, the new device is bind mounted in the container from
415       the host rather than Podman creating it within the container space. Be‐
416       cause  the bind mount retains its SELinux label on SELinux systems, the
417       container can get permission denied when accessing the mounted  device.
418       Modify  SELinux  settings  to allow containers to use all device labels
419       via the following command:
420
421
422       $ sudo setsebool -P  container_use_devices=true
423
424
425       Note: if the user only has access rights via a group, accessing the de‐
426       vice  from  inside  a rootless container will fail. Use the --group-add
427       keep-groups flag to pass the user's supplementary group access into the
428       container.
429
430
431   --device-cgroup-rule="type major:minor mode"
432       Add  a rule to the cgroup allowed devices list. The rule is expected to
433       be in the format specified in the Linux kernel documentation  (Documen‐
434       tation/cgroup-v1/devices.txt):
435              - type: a (all), c (char), or b (block);
436              - major and minor: either a number, or * for all;
437              - mode: a composition of r (read), w (write), and m (mknod(2)).
438
439
440   --device-read-bps=path:rate
441       Limit  read  rate  (in  bytes per second) from a device (e.g. --device-
442       read-bps=/dev/sda:1mb).
443
444
445       On some systems, changing the resource limits may not  be  allowed  for
446       non-root  users.  For  more  details,  see  https://github.com/contain
447       ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
448       source-limits-fails-with-a-permissions-error
449
450
451       This option is not supported on cgroups V1 rootless systems.
452
453
454   --device-read-iops=path:rate
455       Limit read rate (in IO operations per second) from a device (e.g. --de‐
456       vice-read-iops=/dev/sda:1000).
457
458
459       On some systems, changing the resource limits may not  be  allowed  for
460       non-root  users.  For  more  details,  see  https://github.com/contain
461       ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
462       source-limits-fails-with-a-permissions-error
463
464
465       This option is not supported on cgroups V1 rootless systems.
466
467
468   --device-write-bps=path:rate
469       Limit  write  rate  (in  bytes  per second) to a device (e.g. --device-
470       write-bps=/dev/sda:1mb).
471
472
473       On some systems, changing the resource limits may not  be  allowed  for
474       non-root  users.  For  more  details,  see  https://github.com/contain
475       ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
476       source-limits-fails-with-a-permissions-error
477
478
479       This option is not supported on cgroups V1 rootless systems.
480
481
482   --device-write-iops=path:rate
483       Limit  write rate (in IO operations per second) to a device (e.g. --de‐
484       vice-write-iops=/dev/sda:1000).
485
486
487       On some systems, changing the resource limits may not  be  allowed  for
488       non-root  users.  For  more  details,  see  https://github.com/contain
489       ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
490       source-limits-fails-with-a-permissions-error
491
492
493       This option is not supported on cgroups V1 rootless systems.
494
495
496   --disable-content-trust
497       This  is  a  Docker-specific  option to disable image verification to a
498       container registry and is not supported by Podman.  This  option  is  a
499       NOOP and provided solely for scripting compatibility.
500
501
502   --dns=ipaddr
503       Set custom DNS servers.
504
505
506       This option can be used to override the DNS configuration passed to the
507       container. Typically this is necessary when the host DNS  configuration
508       is  invalid  for the container (e.g., 127.0.0.1). When this is the case
509       the --dns flag is necessary for every run.
510
511
512       The special value none can be specified to disable creation of /etc/re‐
513       solv.conf in the container by Podman.  The /etc/resolv.conf file in the
514       image will be used without changes.
515
516
517       This option cannot be combined with --network that is set  to  none  or
518       container:id.
519
520
521   --dns-option=option
522       Set  custom  DNS  options. Invalid if using --dns-option with --network
523       that is set to none or container:id.
524
525
526   --dns-search=domain
527       Set custom DNS search  domains.  Invalid  if  using  --dns-search  with
528       --network  that  is set to none or container:id.  Use --dns-search=. if
529       you don't wish to set the search domain.
530
531
532   --entrypoint="command" | '["command", arg1 , ...]'
533       Overwrite the default ENTRYPOINT of the image.
534
535
536       This option allows you to overwrite the default entrypoint of  the  im‐
537       age.
538
539
540       The ENTRYPOINT of an image is similar to a COMMAND because it specifies
541       what executable to run when the container starts, but it is (purposely)
542       more  difficult  to  override. The ENTRYPOINT gives a container its de‐
543       fault nature or behavior, so that when you set an  ENTRYPOINT  you  can
544       run  the container as if it were that binary, complete with default op‐
545       tions, and you can pass in more options via the COMMAND. But, sometimes
546       an operator may want to run something else inside the container, so you
547       can override the default ENTRYPOINT at runtime by using a  --entrypoint
548       and a string to specify the new ENTRYPOINT.
549
550
551       You need to specify multi option commands in the form of a json string.
552
553
554   --env, -e=env
555       Set environment variables.
556
557
558       This  option  allows arbitrary environment variables that are available
559       for the process to be launched inside of the container. If an  environ‐
560       ment  variable is specified without a value, Podman will check the host
561       environment for a value and set the variable only if it is set  on  the
562       host.  As  a  special  case,  if an environment variable ending in * is
563       specified without a value, Podman will search the host environment  for
564       variables  starting with the prefix and will add those variables to the
565       container.
566
567
568       See Environment ⟨#environment⟩ note below for precedence and examples.
569
570
571   --env-file=file
572       Read in a line-delimited file of environment variables.
573
574
575       See Environment ⟨#environment⟩ note below for precedence and examples.
576
577
578   --env-host
579       Use host environment inside of the container. See Environment note  be‐
580       low  for precedence. (This option is not available with the remote Pod‐
581       man client, including Mac and Windows (excluding WSL2) machines)
582
583
584   --env-merge=env
585       Preprocess default environment variables for the containers. For  exam‐
586       ple if image contains environment variable hello=world user can prepro‐
587       cess it using --env-merge hello=${hello}-some  so  new  value  will  be
588       hello=world-some.
589
590
591   --expose=port
592       Expose  a port, or a range of ports (e.g. --expose=3300-3310) to set up
593       port redirection on the host system.
594
595
596   --gidmap=container_gid:host_gid:amount
597       Run the container in a new user namespace using the supplied  GID  map‐
598       ping. This option conflicts with the --userns and --subgidname options.
599       This option provides a way to map host GIDs to container  GIDs  in  the
600       same  way as --uidmap maps host UIDs to container UIDs. For details see
601       --uidmap.
602
603
604       Note: the --gidmap flag cannot be called in conjunction with the  --pod
605       flag as a gidmap cannot be set on the container level when in a pod.
606
607
608   --group-add=group | keep-groups
609       Assign  additional  groups  to the primary user running within the con‐
610       tainer process.
611
612
613keep-groups is a special flag that tells Podman  to  keep  the
614                supplementary group access.
615
616
617
618       Allows  container to use the user's supplementary group access. If file
619       systems or devices are only accessible by the  rootless  user's  group,
620       this  flag tells the OCI runtime to pass the group access into the con‐
621       tainer. Currently only available with the crun OCI runtime. Note: keep-
622       groups  is  exclusive,  you cannot add any other groups with this flag.
623       (Not available for remote commands, including Mac and Windows  (exclud‐
624       ing WSL2) machines)
625
626
627   --health-cmd="command" | '["command", arg1 , ...]'
628       Set  or  alter  a healthcheck command for a container. The command is a
629       command to be executed inside your container that determines your  con‐
630       tainer health. The command is required for other healthcheck options to
631       be applied. A value of none disables existing healthchecks.
632
633
634       Multiple options can be passed in the form of a JSON array;  otherwise,
635       the command will be interpreted as an argument to /bin/sh -c.
636
637
638   --health-interval=interval
639       Set an interval for the healthchecks. An interval of disable results in
640       no automatic timer setup. The default is 30s.
641
642
643   --health-on-failure=action
644       Action to take once the container transitions to  an  unhealthy  state.
645       The default is none.
646
647
648none: Take no action.
649
650kill: Kill the container.
651
652restart:  Restart  the  container.  Do not combine the restart
653                action with the --restart flag.  When running inside of a sys‐
654                temd  unit,  consider using the kill or stop action instead to
655                make use of systemd's restart policy.
656
657stop: Stop the container.
658
659
660
661   --health-retries=retries
662       The number of retries allowed before a healthcheck is considered to  be
663       unhealthy. The default value is 3.
664
665
666   --health-start-period=period
667       The  initialization time needed for a container to bootstrap. The value
668       can be expressed in time format like 2m3s. The default value is 0s.
669
670
671   --health-timeout=timeout
672       The maximum time allowed to complete the healthcheck before an interval
673       is  considered failed. Like start-period, the value can be expressed in
674       a time format such as 1m22s. The default value is 30s.
675
676
677   --help
678       Print usage statement
679
680
681   --hostname, -h=name
682       Container host name
683
684
685       Sets the container host name that is available  inside  the  container.
686       Can  only be used with a private UTS namespace --uts=private (default).
687       If --pod is specified and the pod shares the  UTS  namespace  (default)
688       the pod's hostname will be used.
689
690
691   --hostuser=name
692       Add  a  user account to /etc/passwd from the host to the container. The
693       Username or UID must exist on the host system.
694
695
696   --http-proxy
697       By default proxy environment variables are passed into the container if
698       set  for  the Podman process. This can be disabled by setting the value
699       to false.  The environment  variables  passed  in  include  http_proxy,
700       https_proxy,  ftp_proxy,  no_proxy, and also the upper case versions of
701       those. This option is only needed when the host system must use a proxy
702       but the container should not use any proxy. Proxy environment variables
703       specified for the container in any other way will override  the  values
704       that would have been passed through from the host. (Other ways to spec‐
705       ify the proxy for the container include passing  the  values  with  the
706       --env  flag,  or  hard  coding the proxy environment at container build
707       time.)  (This option is not available with the  remote  Podman  client,
708       including Mac and Windows (excluding WSL2) machines)
709
710
711       Defaults to true.
712
713
714   --image-volume=bind | tmpfs | ignore
715       Tells Podman how to handle the builtin image volumes. Default is bind.
716
717
718bind:  An  anonymous  named volume will be created and mounted
719                into the container.
720
721tmpfs: The volume is mounted onto the container  as  a  tmpfs,
722                which  allows the users to create content that disappears when
723                the container is stopped.
724
725ignore: All volumes are just ignored and no action is taken.
726
727
728
729   --init
730       Run an init inside the container that forwards signals and  reaps  pro‐
731       cesses.   The  container-init  binary  is  mounted at /run/podman-init.
732       Mounting over /run will hence break container execution.
733
734
735   --init-ctr=type
736       (Pods only).  When using pods, create an init style container, which is
737       run  after  the  infra container is started but before regular pod con‐
738       tainers are started.  Init containers are useful for running setup  op‐
739       erations for the pod's applications.
740
741
742       Valid  values  for  init-ctr type are always or once.  The always value
743       means the container will run with each and every pod start, whereas the
744       once  value  means  the  container  will  only run once when the pod is
745       started and then the container is removed.
746
747
748       Init containers are only run on pod start.  Restarting a pod  will  not
749       execute  any init containers should they be present.  Furthermore, init
750       containers can only be created in a pod when that pod is not running.
751
752
753   --init-path=path
754       Path to the container-init binary.
755
756
757   --interactive, -i
758       When set to true, keep stdin open even if not attached. The default  is
759       false.
760
761
762   --ip=ipv4
763       Specify   a   static  IPv4  address  for  the  container,  for  example
764       10.88.64.128.  This option can only be used if the container is  joined
765       to only a single network - i.e., --network=network-name is used at most
766       once - and if the container is not joining another container's  network
767       namespace  via  --network=container:id.  The address must be within the
768       network's IP address pool (default 10.88.0.0/16).
769
770
771       To specify multiple static IP addresses  per  container,  set  multiple
772       networks  using the --network option with a static IP address specified
773       for each using the ip mode for that option.
774
775
776   --ip6=ipv6
777       Specify  a  static  IPv6  address  for  the  container,   for   example
778       fd46:db93:aa76:ac37::10.  This option can only be used if the container
779       is joined to only a single network -  i.e.,  --network=network-name  is
780       used  at  most  once - and if the container is not joining another con‐
781       tainer's network namespace  via  --network=container:id.   The  address
782       must be within the network's IPv6 address pool.
783
784
785       To  specify  multiple static IPv6 addresses per container, set multiple
786       networks using the --network option with a static IPv6  address  speci‐
787       fied for each using the ip6 mode for that option.
788
789
790   --ipc=ipc
791       Set  the IPC namespace mode for a container. The default is to create a
792       private IPC namespace.
793
794
795              • "": Use Podman's default, defined in containers.conf.
796
797container:id: reuses another container's shared memory,  sema‐
798                phores, and message queues
799
800host:  use  the  host's shared memory, semaphores, and message
801                queues inside the container. Note: the  host  mode  gives  the
802                container  full access to local shared memory and is therefore
803                considered insecure.
804
805none:  private IPC namespace, with /dev/shm not mounted.
806
807ns:path: path to an IPC namespace to join.
808
809private: private IPC  namespace.   =  shareable:  private  IPC
810                namespace  with  a possibility to share it with other contain‐
811                ers.
812
813
814
815   --label, -l=key=value
816       Add metadata to a container.
817
818
819   --label-file=file
820       Read in a line-delimited file of labels.
821
822
823   --link-local-ip=ip
824       Not implemented.
825
826
827   --log-driver=driver
828       Logging driver for the container. Currently available options are  k8s-
829       file,  journald,  none  and passthrough, with json-file aliased to k8s-
830       file for scripting compatibility. (Default journald).
831
832
833       The podman info command below will display the default  log-driver  for
834       the system.
835
836
837              $ podman info --format '{{ .Host.LogDriver }}'
838              journald
839
840
841
842       The passthrough driver passes down the standard streams (stdin, stdout,
843       stderr) to the container.  It is not allowed  with  the  remote  Podman
844       client,  including  Mac and Windows (excluding WSL2) machines, and on a
845       tty, since it is vulnerable to attacks via TIOCSTI.
846
847
848   --log-opt=name=value
849       Logging driver specific options.
850
851
852       Set custom logging configuration. The following *name*s are supported:
853
854
855       path: specify a path to the log file
856           (e.g. --log-opt path=/var/log/container/mycontainer.json);
857
858
859       max-size: specify a max size of the log file
860           (e.g. --log-opt max-size=10mb);
861
862
863       tag: specify a custom log tag for the container
864           (e.g. --log-opt tag="{{.ImageName}}".  It supports the same keys as
865       podman  inspect  --format.   This option is currently supported only by
866       the journald log driver.
867
868
869   --mac-address=address
870       Container network interface MAC address (e.g.  92:d0:c6:0a:29:33)  This
871       option  can  only  be  used if the container is joined to only a single
872       network - i.e., --network=network-name is used at most once  -  and  if
873       the  container is not joining another container's network namespace via
874       --network=container:id.
875
876
877       Remember that the MAC address in an Ethernet network  must  be  unique.
878       The  IPv6  link-local address will be based on the device's MAC address
879       according to RFC4862.
880
881
882       To specify multiple static MAC addresses per  container,  set  multiple
883       networks using the --network option with a static MAC address specified
884       for each using the mac mode for that option.
885
886
887   --memory, -m=number[unit]
888       Memory limit. A unit can be b (bytes), k (kibibytes), m (mebibytes), or
889       g (gibibytes).
890
891
892       Allows  the  memory  available to a container to be constrained. If the
893       host supports swap memory, then the -m memory  setting  can  be  larger
894       than  physical  RAM.  If  a limit of 0 is specified (not using -m), the
895       container's memory is not limited. The actual limit may be  rounded  up
896       to  a  multiple of the operating system's page size (the value would be
897       very large, that's millions of trillions).
898
899
900       This option is not supported on cgroups V1 rootless systems.
901
902
903   --memory-reservation=number[unit]
904       Memory  soft  limit.  A  unit  can  be  b  (bytes),  k  (kibibytes),  m
905       (mebibytes), or g (gibibytes).
906
907
908       After  setting  memory reservation, when the system detects memory con‐
909       tention or low memory, containers are forced to restrict their consump‐
910       tion  to  their  reservation.  So you should always set the value below
911       --memory, otherwise the hard limit will take  precedence.  By  default,
912       memory reservation will be the same as memory limit.
913
914
915       This option is not supported on cgroups V1 rootless systems.
916
917
918   --memory-swap=number[unit]
919       A  limit  value  equal to memory plus swap.  A unit can be b (bytes), k
920       (kibibytes), m (mebibytes), or g (gibibytes).
921
922
923       Must be used with the -m (--memory) flag.  The  argument  value  should
924       always be larger than that of
925        -m (--memory) By default, it is set to double the value of --memory.
926
927
928       Set number to -1 to enable unlimited swap.
929
930
931       This option is not supported on cgroups V1 rootless systems.
932
933
934   --memory-swappiness=number
935       Tune  a  container's memory swappiness behavior. Accepts an integer be‐
936       tween 0 and 100.
937
938
939       This flag is only supported on cgroups V1 rootful systems.
940
941
942   --mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]
943       Attach a filesystem mount to the container
944
945
946       Current supported mount TYPEs are bind, volume, image,  tmpfs  and  de‐
947       vpts. [1] ⟨#Footnote1⟩
948
949
950                 e.g.
951
952                 type=bind,source=/path/on/host,destination=/path/in/container
953
954                 type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared
955
956                 type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared,U=true
957
958                 type=volume,source=vol1,destination=/path/in/container,ro=true
959
960                 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
961
962                 type=image,source=fedora,destination=/fedora-image,rw=true
963
964                 type=devpts,destination=/dev/pts
965
966                 Common Options:
967
968                    · src, source: mount source spec for bind and volume. Mandatory for bind.
969
970                    · dst, destination, target: mount destination spec.
971
972                 Options specific to volume:
973
974                    · ro, readonly: true or false (default).
975
976                    . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
977
978                    · idmap: true or false (default).  If specified, create an idmapped mount to the target user namespace in the container.
979
980                 Options specific to image:
981
982                    · rw, readwrite: true or false (default).
983
984                 Options specific to bind:
985
986                    · ro, readonly: true or false (default).
987
988                    · bind-propagation: shared, slave, private, unbindable, rshared, rslave, runbindable, or rprivate(default). See also mount(2).
989
990                    . bind-nonrecursive: do not set up a recursive bind mount. By default it is recursive.
991
992                    . relabel: shared, private.
993
994                    · idmap: true or false (default).  If specified, create an idmapped mount to the target user namespace in the container.
995
996                    . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
997
998                 Options specific to tmpfs:
999
1000                    · ro, readonly: true or false (default).
1001
1002                    · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
1003
1004                    · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
1005
1006                    · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs. Used by default.
1007
1008                    · notmpcopyup: Disable copying files from the image to the tmpfs.
1009
1010                    . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
1011
1012                 Options specific to devpts:
1013
1014                    · uid: UID of the file owner (default 0).
1015
1016                    · gid: GID of the file owner (default 0).
1017
1018                    · mode: permission mask for the file (default 600).
1019
1020                    · max: maximum number of PTYs (default 1048576).
1021
1022
1023
1024   --name=name
1025       Assign a name to the container.
1026
1027
1028       The operator can identify a container in three ways:
1029
1030
1031              • UUID                      long                      identifier
1032                (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”);
1033
1034              • UUID short identifier (“f78375b1c487”);
1035
1036              • Name (“jonah”).
1037
1038
1039
1040       Podman  generates  a  UUID for each container, and if a name is not as‐
1041       signed to the container with --name then  it  will  generate  a  random
1042       string  name.  The name is useful any place you need to identify a con‐
1043       tainer.  This works for both background and foreground containers.
1044
1045
1046   --network=mode, --net
1047       Set the network mode for the container.
1048
1049
1050       Valid mode values are:
1051
1052
1053bridge[:OPTIONS,...]: Create a network stack  on  the  default
1054                bridge. This is the default for rootful containers. It is pos‐
1055                sible to specify these additional options:
1056
1057alias=name: Add network-scoped alias for the container.
1058
1059ip=IPv4: Specify a static ipv4 address for this container.
1060
1061ip=IPv6: Specify a static ipv6 address for this container.
1062
1063mac=MAC: Specify a static mac address for this container.
1064
1065interface_name: Specify a name for the created  network  in‐
1066                  terface inside the container.
1067
1068
1069
1070
1071
1072       For  example to set a static ipv4 address and a static mac address, use
1073       --network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99.  - <network  name
1074       or  ID>[:OPTIONS,...]:  Connect  to a user-defined network; this is the
1075       network name or ID from a network created by podman network create. Us‐
1076       ing the network name implies the bridge network mode. It is possible to
1077       specify the same options described under the bridge mode above. You can
1078       use the --network option multiple times to specify additional networks.
1079       - none: Create a network namespace for the container but do not config‐
1080       ure  network  interfaces for it, thus the container has no network con‐
1081       nectivity.  - container:id: Reuse another container's network stack.  -
1082       host:  Do  not  create  a network namespace, the container will use the
1083       host's network. Note: The host mode gives the container full access  to
1084       local  system  services such as D-bus and is therefore considered inse‐
1085       cure.  - ns:path: Path to a network namespace to join.  - private: Cre‐
1086       ate  a  new  namespace for the container. This will use the bridge mode
1087       for  rootful  containers  and  slirp4netns  for   rootless   ones.    -
1088       slirp4netns[:OPTIONS,...]:  use slirp4netns(1) to create a user network
1089       stack. This is the default for rootless containers. It is  possible  to
1090       specify  these  additional  options,  they  can  also  be set with net‐
1091       work_cmd_options in containers.conf:
1092         - allow_host_loopback=true|false: Allow slirp4netns to reach the host
1093       loopback IP (default is 10.0.2.2 or the second IP from slirp4netns cidr
1094       subnet when changed, see the cidr option below). The default is false.
1095         - mtu=MTU: Specify the MTU to  use  for  this  network.  (Default  is
1096       65520).
1097         -  cidr=CIDR:  Specify  ip range to use for this network. (Default is
1098       10.0.2.0/24).
1099         - enable_ipv6=true|false: Enable IPv6. Default is true. (Required for
1100       outbound_addr6).
1101         -  outbound_addr=INTERFACE:  Specify  the  outbound  interface  slirp
1102       should bind to (ipv4 traffic only).
1103         - outbound_addr=IPv4: Specify the outbound ipv4 address slirp  should
1104       bind to.
1105         -  outbound_addr6=INTERFACE:  Specify  the  outbound  interface slirp
1106       should bind to (ipv6 traffic only).
1107         - outbound_addr6=IPv6: Specify the outbound ipv6 address slirp should
1108       bind to.
1109         -  port_handler=rootlesskit: Use rootlesskit for port forwarding. De‐
1110       fault.
1111         Note: Rootlesskit changes the source IP address of  incoming  packets
1112       to   an   IP  address  in  the  container  network  namespace,  usually
1113       10.0.2.100. If your application requires the real  source  IP  address,
1114       e.g. web server logs, use the slirp4netns port handler. The rootlesskit
1115       port handler is also used for rootless  containers  when  connected  to
1116       user-defined networks.
1117         -  port_handler=slirp4netns:  Use the slirp4netns port forwarding, it
1118       is slower than rootlesskit but preserves the correct source IP address.
1119       This port handler cannot be used for user-defined networks.
1120
1121
1122       Invalid  if  using  --dns, --dns-option, or --dns-search with --network
1123       set to none or container:id.
1124
1125
1126       If used together with --pod, the container will not join the pod's net‐
1127       work namespace.
1128
1129
1130   --network-alias=alias
1131       Add a network-scoped alias for the container, setting the alias for all
1132       networks that the container joins. To set a name only  for  a  specific
1133       network,  use the alias option as described under the --network option.
1134       If the network has DNS enabled (podman  network  inspect  -f  {{.DNSEn‐
1135       abled}}  <name>),  these aliases can be used for name resolution on the
1136       given network. This option can be specified multiple times.  NOTE: When
1137       using  CNI  a  container  will only have access to aliases on the first
1138       network that  it  joins.  This  limitation  does  not  exist  with  ne‐
1139       tavark/aardvark-dns.
1140
1141
1142   --no-healthcheck
1143       Disable any defined healthchecks for container.
1144
1145
1146   --no-hosts
1147       Do  not  create  /etc/hosts for the container.  By default, Podman will
1148       manage /etc/hosts, adding the container's own IP address and any  hosts
1149       from  --add-host.  --no-hosts disables this, and the image's /etc/hosts
1150       will be preserved unmodified.
1151
1152
1153       This option conflicts with --add-host.
1154
1155
1156   --oom-kill-disable
1157       Whether to disable OOM Killer for the container or not.
1158
1159
1160       This flag is not supported on cgroups V2 systems.
1161
1162
1163   --oom-score-adj=num
1164       Tune the host's OOM preferences for  containers  (accepts  values  from
1165       -1000 to 1000).
1166
1167
1168   --os=OS
1169       Override  the OS, defaults to hosts, of the image to be pulled. For ex‐
1170       ample, windows.  Unless overridden, subsequent lookups of the same  im‐
1171       age in the local storage will match this OS, regardless of the host.
1172
1173
1174   --passwd-entry=ENTRY
1175       Customize  the entry that is written to the /etc/passwd file within the
1176       container when --passwd is used.
1177
1178
1179       The variables $USERNAME, $UID, $GID, $NAME, $HOME are automatically re‐
1180       placed with their value at runtime.
1181
1182
1183   --personality=persona
1184       Personality sets the execution domain via Linux personality(2).
1185
1186
1187   --pid=mode
1188       Set the PID namespace mode for the container.  The default is to create
1189       a private PID namespace for the container.
1190
1191
1192container:id: join another container's PID namespace;
1193
1194host: use the host's PID namespace for the container. Note the
1195                host  mode gives the container full access to local PID and is
1196                therefore considered insecure;
1197
1198ns:path: join the specified PID namespace;
1199
1200private: create a new namespace for the container (default).
1201
1202
1203
1204   --pidfile=path
1205       When the pidfile location is specified, the container process' PID will
1206       be  written  to the pidfile. (This option is not available with the re‐
1207       mote Podman client, including Mac  and  Windows  (excluding  WSL2)  ma‐
1208       chines)  If the pidfile option is not specified, the container process'
1209       PID will be written  to  /run/containers/storage/${storage-driver}-con‐
1210       tainers/$CID/userdata/pidfile.
1211
1212
1213       After  the  container  is  started, the location for the pidfile can be
1214       discovered with the following podman inspect command:
1215
1216
1217              $ podman inspect --format '{{ .PidFile }}' $CID
1218              /run/containers/storage/${storage-driver}-containers/$CID/userdata/pidfile
1219
1220
1221
1222   --pids-limit=limit
1223       Tune the container's pids limit. Set to -1 to have unlimited  pids  for
1224       the  container.  The  default  is  4096  on systems that support "pids"
1225       cgroup controller.
1226
1227
1228   --platform=OS/ARCH
1229       Specify the platform for selecting the image.  (Conflicts  with  --arch
1230       and --os) The --platform option can be used to override the current ar‐
1231       chitecture and operating system.  Unless overridden, subsequent lookups
1232       of  the  same  image in the local storage will match this platform, re‐
1233       gardless of the host.
1234
1235
1236   --pod=name
1237       Run container in an existing pod. If you want Podman to  make  the  pod
1238       for you, prefix the pod name with new:.  To make a pod with more granu‐
1239       lar options, use the podman pod create command before creating  a  con‐
1240       tainer.   If  a  container is run with a pod, and the pod has an infra-
1241       container, the infra-container will be started before the container is.
1242
1243
1244   --pod-id-file=file
1245       Run container in an existing pod and read the pod's ID from the  speci‐
1246       fied  file.  If a container is run within a pod, and the pod has an in‐
1247       fra-container, the infra-container will be started before the container
1248       is.
1249
1250
1251   --privileged
1252       Give extended privileges to this container. The default is false.
1253
1254
1255       By default, Podman containers are unprivileged (=false) and cannot, for
1256       example, modify parts of the operating system. This is because  by  de‐
1257       fault  a container is only allowed limited access to devices. A "privi‐
1258       leged" container is given the  same  access  to  devices  as  the  user
1259       launching the container.
1260
1261
1262       A privileged container turns off the security features that isolate the
1263       container from the host. Dropped Capabilities, limited  devices,  read-
1264       only mount points, Apparmor/SELinux separation, and Seccomp filters are
1265       all disabled.
1266
1267
1268       Rootless containers cannot have more privileges than the  account  that
1269       launched them.
1270
1271
1272   --publish, -p=[[ip:][hostPort]:]containerPort[/protocol]
1273       Publish a container's port, or range of ports, to the host.
1274
1275
1276       Both  hostPort  and containerPort can be specified as a range of ports.
1277       When specifying ranges for both, the number of container ports  in  the
1278       range must match the number of host ports in the range.
1279
1280
1281       If  host IP is set to 0.0.0.0 or not set at all, the port will be bound
1282       on all IPs on the host.
1283
1284
1285       By default, Podman will publish TCP ports. To publish a  UDP  port  in‐
1286       stead,  give  udp  as  protocol. To publish both TCP and UDP ports, set
1287       --publish twice, with tcp, and udp as protocols  respectively.  Rootful
1288       containers can also publish ports using the sctp protocol.
1289
1290
1291       Host   port  does  not  have  to  be  specified  (e.g.  podman  run  -p
1292       127.0.0.1::80).  If it is not, the container port will be randomly  as‐
1293       signed a port on the host.
1294
1295
1296       Use podman port to see the actual mapping: podman port $CONTAINER $CON‐
1297       TAINERPORT.
1298
1299
1300       Note: If a container will be run within a pod, it is not  necessary  to
1301       publish  the  port for the containers in the pod. The port must only be
1302       published by the pod itself. Pod network stacks act  like  the  network
1303       stack  on  the  host - you have a variety of containers in the pod, and
1304       programs in the container, all sharing a single interface  and  IP  ad‐
1305       dress, and associated ports. If one container binds to a port, no other
1306       container can use that port within the pod while it is in use. Contain‐
1307       ers  in  the pod can also communicate over localhost by having one con‐
1308       tainer bind to localhost in the pod, and another connect to that port.
1309
1310
1311   --publish-all, -P
1312       Publish all exposed ports to random ports on the host  interfaces.  The
1313       default is false.
1314
1315
1316       When set to true, publish all exposed ports to the host interfaces.  If
1317       the operator uses -P (or -p) then Podman will make the exposed port ac‐
1318       cessible on the host and the ports will be available to any client that
1319       can reach the host.
1320
1321
1322       When using this option, Podman will bind any exposed port to  a  random
1323       port   on   the   host  within  an  ephemeral  port  range  defined  by
1324       /proc/sys/net/ipv4/ip_local_port_range.  To find  the  mapping  between
1325       the host ports and the exposed ports, use podman port.
1326
1327
1328   --pull=policy
1329       Pull image policy. The default is missing.
1330
1331
1332always:  Always  pull the image and throw an error if the pull
1333                fails.
1334
1335missing: Pull the image only if it could not be found  in  the
1336                local containers storage.  Throw an error if no image could be
1337                found and the pull fails.
1338
1339never: Never pull the image but use the  one  from  the  local
1340                containers  storage.   Throw  an  error  if  no image could be
1341                found.
1342
1343newer: Pull if the image on the registry is newer than the one
1344                in the local containers storage.  An image is considered to be
1345                newer when the digests  are  different.   Comparing  the  time
1346                stamps  is  prone  to errors.  Pull errors are suppressed if a
1347                local image was found.
1348
1349
1350
1351   --quiet, -q
1352       Suppress output information when pulling images
1353
1354
1355   --read-only
1356       Mount the container's root filesystem as read-only.
1357
1358
1359       By default a container will have its root filesystem writable  allowing
1360       processes  to write files anywhere. By specifying the --read-only flag,
1361       the container will have its root filesystem mounted as  read-only  pro‐
1362       hibiting any writes.
1363
1364
1365   --read-only-tmpfs
1366       If  container  is  running in --read-only mode, then mount a read-write
1367       tmpfs on /run, /tmp, and /var/tmp. The default is true.
1368
1369
1370   --replace
1371       If another container with the same name already exists, replace and re‐
1372       move it. The default is false.
1373
1374
1375   --requires=container
1376       Specify  one  or more requirements.  A requirement is a dependency con‐
1377       tainer that will be started before this container.  Containers  can  be
1378       specified  by  name  or ID, with multiple containers being separated by
1379       commas.
1380
1381
1382   --restart=policy
1383       Restart policy to follow when containers exit.  Restart policy will not
1384       take  effect  if  a  container is stopped via the podman kill or podman
1385       stop commands.
1386
1387
1388       Valid policy values are:
1389
1390
1391no                       : Do not restart containers on exit
1392
1393on-failure[:max_retries] : Restart containers when  they  exit
1394                with  a non-zero exit code, retrying indefinitely or until the
1395                optional max_retries count is hit
1396
1397always                   : Restart containers when they  exit,
1398                regardless of status, retrying indefinitely
1399
1400unless-stopped           : Identical to always
1401
1402
1403
1404       Please note that restart will not restart containers after a system re‐
1405       boot.  If this functionality is required in your environment,  you  can
1406       invoke Podman from a systemd.unit(5) file, or create an init script for
1407       whichever init system is in  use.   To  generate  systemd  unit  files,
1408       please see podman generate systemd.
1409
1410
1411   --rm
1412       Automatically remove the container when it exits. The default is false.
1413
1414
1415   --rootfs
1416       If specified, the first argument refers to an exploded container on the
1417       file system.
1418
1419
1420       This is useful to run a container without requiring any  image  manage‐
1421       ment, the rootfs of the container is assumed to be managed externally.
1422
1423
1424       Overlay Rootfs Mounts
1425
1426
1427       The :O flag tells Podman to mount the directory from the rootfs path as
1428       storage using the overlay file system. The container processes can mod‐
1429       ify  content  within  the  mount point which is stored in the container
1430       storage in a separate directory. In overlay terms, the source directory
1431       will  be the lower, and the container storage directory will be the up‐
1432       per. Modifications to the mount point are destroyed when the  container
1433       finishes executing, similar to a tmpfs mount point being unmounted.
1434
1435
1436       Note:  On SELinux systems, the rootfs needs the correct label, which is
1437       by default unconfined_u:object_r:container_file_t:s0.
1438
1439
1440   --sdnotify=container | conmon | ignore
1441       Determines how to use the NOTIFY_SOCKET, as  passed  with  systemd  and
1442       Type=notify.
1443
1444
1445       Default  is  container,  which means allow the OCI runtime to proxy the
1446       socket into the container to receive ready  notification.  Podman  will
1447       set  the  MAINPID  to  conmon's pid.  The conmon option sets MAINPID to
1448       conmon's pid, and sends READY  when  the  container  has  started.  The
1449       socket is never passed to the runtime or the container.  The ignore op‐
1450       tion removes NOTIFY_SOCKET from the environment for  itself  and  child
1451       processes,  for the case where some other process above Podman uses NO‐
1452       TIFY_SOCKET and Podman should not use it.
1453
1454
1455   --seccomp-policy=policy
1456       Specify the policy to select the seccomp profile. If set to image, Pod‐
1457       man  will  look for a "io.containers.seccomp.profile" label in the con‐
1458       tainer-image config and use its value as a seccomp profile.  Otherwise,
1459       Podman  will  follow the default policy by applying the default profile
1460       unless specified otherwise via --security-opt seccomp as described  be‐
1461       low.
1462
1463
1464       Note that this feature is experimental and may change in the future.
1465
1466
1467   --secret=secret[,opt=opt ...]
1468       Give the container access to a secret. Can be specified multiple times.
1469
1470
1471       A secret is a blob of sensitive data which a container needs at runtime
1472       but should not be stored in the image or in  source  control,  such  as
1473       usernames  and  passwords, TLS certificates and keys, SSH keys or other
1474       important generic strings or binary content (up to 500 kb in size).
1475
1476
1477       When secrets are specified as type mount, the secrets  are  copied  and
1478       mounted  into  the container when a container is created.  When secrets
1479       are specified as type env, the secret will be  set  as  an  environment
1480       variable within the container.  Secrets are written in the container at
1481       the time of container creation, and modifying the secret  using  podman
1482       secret  commands after the container is created will not affect the se‐
1483       cret inside the container.
1484
1485
1486       Secrets and its storage are managed using the podman secret command.
1487
1488
1489       Secret Options
1490
1491
1492type=mount|env    : How the secret will be exposed to the con‐
1493                tainer. Default mount.
1494
1495target=target     : Target of secret. Defaults to secret name.
1496
1497uid=0             : UID of secret. Defaults to 0. Mount secret
1498                type only.
1499
1500gid=0             : GID of secret. Defaults to 0. Mount secret
1501                type only.
1502
1503mode=0             :  Mode  of secret. Defaults to 0444. Mount
1504                secret type only.
1505
1506
1507
1508   --security-opt=option
1509       Security Options
1510
1511
1512apparmor=unconfined : Turn off apparmor  confinement  for  the
1513                container
1514
1515apparmor=your-profile  :  Set the apparmor confinement profile
1516                for the container
1517
1518label=user:USER     : Set the label  user  for  the  container
1519                processes
1520
1521label=role:ROLE      :  Set  the  label role for the container
1522                processes
1523
1524label=type:TYPE     : Set the label process type for the  con‐
1525                tainer processes
1526
1527label=level:LEVEL    :  Set  the label level for the container
1528                processes
1529
1530label=filetype:TYPE : Set the label file  type  for  the  con‐
1531                tainer files
1532
1533label=disable        :  Turn off label separation for the con‐
1534                tainer
1535
1536
1537
1538       Note: Labeling can be  disabled  for  all  containers  by  setting  la‐
1539       bel=false  in  the  containers.conf (/etc/containers/containers.conf or
1540       $HOME/.config/containers/containers.conf) file.
1541
1542
1543mask=/path/1:/path/2 : The paths to mask separated by a colon.
1544                A masked path cannot be accessed inside the container.
1545
1546no-new-privileges  :  Disable container processes from gaining
1547                additional privileges
1548
1549seccomp=unconfined : Turn off seccomp confinement for the con‐
1550                tainer.
1551
1552seccomp=profile.json  : JSON file to be used as a seccomp fil‐
1553                ter. Note that the io.podman.annotations.seccomp annotation is
1554                set with the specified value as shown in podman inspect.
1555
1556proc-opts=OPTIONS : Comma-separated list of options to use for
1557                the /proc mount. More details for the possible  mount  options
1558                are specified in the proc(5) man page.
1559
1560unmask=ALL   or   /path/1:/path/2,  or  shell  expanded  paths
1561                (/proc/*): Paths to unmask separated by a  colon.  If  set  to
1562                ALL,  it  will  unmask  all  the paths that are masked or made
1563                read-only  by  default.   The   default   masked   paths   are
1564                /proc/acpi,   /proc/kcore,   /proc/keys,  /proc/latency_stats,
1565                /proc/sched_debug,        /proc/scsi,        /proc/timer_list,
1566                /proc/timer_stats,  /sys/firmware,  and  /sys/fs/selinux.  The
1567                default paths that are read-only are /proc/asound,  /proc/bus,
1568                /proc/fs,     /proc/irq,    /proc/sys,    /proc/sysrq-trigger,
1569                /sys/fs/cgroup.
1570
1571
1572
1573       Note: Labeling can be  disabled  for  all  containers  by  setting  la‐
1574       bel=false  in  the  containers.conf (/etc/containers/containers.conf or
1575       $HOME/.config/containers/containers.conf) file.
1576
1577
1578   --shm-size=number[unit]
1579       Size  of  /dev/shm.  A  unit  can  be  b  (bytes),  k  (kibibytes),   m
1580       (mebibytes), or g (gibibytes).  If the unit is omitted, the system uses
1581       bytes. If the size is omitted, the default is 64m.   When  size  is  0,
1582       there  is  no  limit  on  the amount of memory used for IPC by the con‐
1583       tainer.  This option conflicts with --ipc=host.
1584
1585
1586   --stop-signal=signal
1587       Signal to stop a container. Default is SIGTERM.
1588
1589
1590   --stop-timeout=seconds
1591       Timeout to stop a container. Default is 10.  Remote connections use lo‐
1592       cal containers.conf for defaults
1593
1594
1595   --subgidname=name
1596       Run  the  container  in a new user namespace using the map with name in
1597       the /etc/subgid file.  If running rootless, the user needs to have  the
1598       right  to  use  the  mapping.  See subgid(5).  This flag conflicts with
1599       --userns and --gidmap.
1600
1601
1602   --subuidname=name
1603       Run the container in a new user namespace using the map  with  name  in
1604       the  /etc/subuid file.  If running rootless, the user needs to have the
1605       right to use the mapping. See  subuid(5).   This  flag  conflicts  with
1606       --userns and --uidmap.
1607
1608
1609   --sysctl=name=value
1610       Configure namespaced kernel parameters at runtime.
1611
1612
1613       For the IPC namespace, the following sysctls are allowed:
1614
1615
1616              • kernel.msgmax
1617
1618              • kernel.msgmnb
1619
1620              • kernel.msgmni
1621
1622              • kernel.sem
1623
1624              • kernel.shmall
1625
1626              • kernel.shmmax
1627
1628              • kernel.shmmni
1629
1630              • kernel.shm_rmid_forced
1631
1632              • Sysctls beginning with fs.mqueue.*
1633
1634
1635
1636       Note:  if  you use the --ipc=host option, the above sysctls are not al‐
1637       lowed.
1638
1639
1640       For the network namespace, only sysctls beginning with  net.*  are  al‐
1641       lowed.
1642
1643
1644       Note:  if  you use the --network=host option, the above sysctls are not
1645       allowed.
1646
1647
1648   --systemd=true | false | always
1649       Run container in systemd mode. The default is true.
1650
1651
1652       The value always enforces the systemd mode is enforced without  looking
1653       at  the  executable name. Otherwise, if set to true and the command you
1654       are running inside the container is systemd, /usr/sbin/init, /sbin/init
1655       or /usr/local/sbin/init.
1656
1657
1658       Running the container in systemd mode causes the following changes:
1659
1660
1661              • Podman mounts tmpfs file systems on the following directories
1662
1663/run
1664
1665/run/lock
1666
1667/tmp
1668
1669/sys/fs/cgroup/systemd
1670
1671/var/lib/journal
1672
1673
1674
1675              • Podman sets the default stop signal to SIGRTMIN+3.
1676
1677              • Podman  sets  container_uuid  environment variable in the con‐
1678                tainer to the first 32 characters of the container id.
1679
1680
1681
1682       This allows systemd to run in a confined container without any  modifi‐
1683       cations.
1684
1685
1686       Note  that  on SELinux systems, systemd attempts to write to the cgroup
1687       file system. Containers writing to the cgroup file system are denied by
1688       default.   The container_manage_cgroup boolean must be enabled for this
1689       to be allowed on an SELinux separated system.
1690
1691
1692              setsebool -P container_manage_cgroup true
1693
1694
1695
1696   --timeout=seconds
1697       Maximum time a container is allowed to run before conmon sends  it  the
1698       kill  signal.   By  default  containers will run until they exit or are
1699       stopped by podman stop.
1700
1701
1702   --tls-verify
1703       Require HTTPS and verify certificates when contacting  registries  (de‐
1704       fault:  true).   If  explicitly  set  to true, TLS verification will be
1705       used.  If set to false, TLS verification will  not  be  used.   If  not
1706       specified,  TLS verification will be used unless the target registry is
1707       listed as an insecure registry in containers-registries.conf(5)
1708
1709
1710   --tmpfs=fs
1711       Create a tmpfs mount.
1712
1713
1714       Mount a temporary filesystem (tmpfs) mount into a container, for  exam‐
1715       ple:
1716
1717
1718              $ podman create -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image
1719
1720
1721
1722       This command mounts a tmpfs at /tmp within the container. The supported
1723       mount options are the same as the Linux default mount flags. If you  do
1724       not  specify  any  options,  the  system  uses  the  following options:
1725       rw,noexec,nosuid,nodev.
1726
1727
1728   --tty, -t
1729       Allocate a pseudo-TTY. The default is false.
1730
1731
1732       When set to true, Podman will allocate a pseudo-tty and attach  to  the
1733       standard  input of the container. This can be used, for example, to run
1734       a throwaway interactive shell.
1735
1736
1737       NOTE: The --tty flag prevents redirection of standard output.  It  com‐
1738       bines  STDOUT  and STDERR, it can insert control characters, and it can
1739       hang pipes. This option should only be used when run interactively in a
1740       terminal. When feeding input to Podman, use -i only, not -it.
1741
1742
1743   --tz=timezone
1744       Set  timezone  in  container. This flag takes area-based timezones, GMT
1745       time, as well as local, which sets the timezone  in  the  container  to
1746       match  the  host machine. See /usr/share/zoneinfo/ for valid timezones.
1747       Remote connections use local containers.conf for defaults
1748
1749
1750   --uidmap=container_uid:from_uid:amount
1751       Run the container in a new user namespace using the supplied  UID  map‐
1752       ping. This option conflicts with the --userns and --subuidname options.
1753       This option provides a way to map host UIDs to container UIDs.  It  can
1754       be passed several times to map different ranges.
1755
1756
1757       The  _fromuid  value is based upon the user running the command, either
1758       rootful    or    rootless    users.     *    rootful    user:      con‐
1759       tainer_uid:host_uid:amount  *  rootless  user: container_uid:intermedi‐
1760       ate_uid:amount
1761
1762
1763       When podman create is called by a privileged user, the option  --uidmap
1764       works as a direct mapping between host UIDs and container UIDs.
1765
1766
1767       host UID -> container UID
1768
1769
1770       The  amount  specifies  the  number  of  consecutive  UIDs that will be
1771       mapped.  If for example amount is 4 the mapping would look like:
1772
1773
1774       |    host  UID      |     container  UID     |  |  -               |  -
1775       | | _fromuid     | _containeruid     | | _fromuid + 1 | _containeruid +
1776       1 | | _fromuid + 2 | _containeruid + 2 | | _fromuid + 3 | _containeruid
1777       + 3 |
1778
1779
1780       When  podman  create  is  called  by an unprivileged user (i.e. running
1781       rootless), the value _fromuid is interpreted as an "intermediate  UID".
1782       In  the  rootless  case, host UIDs are not mapped directly to container
1783       UIDs. Instead the mapping happens over two mapping steps:
1784
1785
1786       host UID -> intermediate UID -> container UID
1787
1788
1789       The --uidmap option only influences the second mapping step.
1790
1791
1792       The first mapping step is derived by Podman from the  contents  of  the
1793       file /etc/subuid and the UID of the user calling Podman.
1794
1795
1796       First mapping step:
1797
1798
1799       | host UID                                         | intermediate UID |
1800       | -                                                |                - |
1801       | UID for the user starting Podman                 |                0 |
1802       | 1st subordinate UID for the user starting Podman |                1 |
1803       | 2nd subordinate UID for the user starting Podman |                2 |
1804       | 3rd subordinate UID for the user starting Podman |                3 |
1805       | nth subordinate UID for the user starting Podman |                n |
1806
1807
1808       To  be  able to use intermediate UIDs greater than zero, the user needs
1809       to have subordinate UIDs configured in /etc/subuid. See subuid(5).
1810
1811
1812       The second mapping step is configured with --uidmap.
1813
1814
1815       If for example amount is 5 the second mapping step would look like:
1816
1817
1818       |   intermediate UID   |    container UID    | | -                    |
1819       -                    |  |  _fromuid            |  _containeruid     | |
1820       _fromuid + 1       | _containeruid + 1 | | _fromuid + 2        |  _con‐
1821       taineruid + 2 | | _fromuid + 3       | _containeruid + 3 | | _fromuid +
1822       4       | _containeruid + 4 |
1823
1824
1825       When running as rootless, Podman will use all the ranges configured  in
1826       the /etc/subuid file.
1827
1828
1829       The  current user ID is mapped to UID=0 in the rootless user namespace.
1830       Every additional range is added sequentially afterward:
1831
1832
1833       |     host                  |rootless   user   namespace    |    length
1834       |    |    -                        |    -                         |   -
1835       |   |    $UID                     |    0                         |    1
1836       |     |     1                         |     $FIRST_RANGE_ID           |
1837       $FIRST_RANGE_LENGTH  |  |  1+$FIRST_RANGE_LENGTH   |   $SECOND_RANGE_ID
1838       | $SECOND_RANGE_LENGTH|
1839
1840
1841       Even  if  a  user  does  not have any subordinate UIDs in  /etc/subuid,
1842       --uidmap could still be used to map the normal UID of  the  user  to  a
1843       container  UID  by  running  podman  create --uidmap $container_uid:0:1
1844       --user $container_uid ....
1845
1846
1847       Note: the --uidmap flag cannot be called in conjunction with the  --pod
1848       flag as a uidmap cannot be set on the container level when in a pod.
1849
1850
1851   --ulimit=option
1852       Ulimit options. You can use host to copy the current configuration from
1853       the host.
1854
1855
1856   --umask=umask
1857       Set the umask inside the container. Defaults to 0022.   Remote  connec‐
1858       tions use local containers.conf for defaults
1859
1860
1861   --unsetenv=env
1862       Unset default environment variables for the container. Default environ‐
1863       ment variables include variables provided natively by Podman,  environ‐
1864       ment  variables configured by the image, and environment variables from
1865       containers.conf.
1866
1867
1868   --unsetenv-all
1869       Unset all default environment variables for the container. Default  en‐
1870       vironment  variables include variables provided natively by Podman, en‐
1871       vironment variables configured by the image, and environment  variables
1872       from containers.conf.
1873
1874
1875   --user, -u=user[:group]
1876       Sets the username or UID used and, optionally, the groupname or GID for
1877       the specified command. Both user and group may be symbolic or numeric.
1878
1879
1880       Without this argument, the command will run as the  user  specified  in
1881       the  container  image.  Unless overridden by a USER command in the Con‐
1882       tainerfile or by a value passed to this option, this user generally de‐
1883       faults to root.
1884
1885
1886       When  a  user  namespace is not in use, the UID and GID used within the
1887       container and on the host will match. When user namespaces are in  use,
1888       however, the UID and GID in the container may correspond to another UID
1889       and GID on the host. In rootless containers, for example, a user  name‐
1890       space  is always used, and root in the container will by default corre‐
1891       spond to the UID and GID of the user invoking Podman.
1892
1893
1894   --userns=mode
1895       Set the user namespace mode for the container. It defaults to the  POD‐
1896       MAN_USERNS  environment  variable. An empty value ("") means user name‐
1897       spaces are disabled unless an explicit mapping is set with the --uidmap
1898       and --gidmap options.
1899
1900
1901       This  option  is incompatible with --gidmap, --uidmap, --subuidname and
1902       --subgidname.
1903
1904
1905       Rootless user --userns=Key mappings:
1906
1907
1908       ┌────────┬───────────┬─────────────────────┐
1909Key     Host User Container User      
1910       ├────────┼───────────┼─────────────────────┤
1911       │""      │ $UID      │ 0 (Default User ac‐ │
1912       │        │           │ count   mapped   to │
1913       │        │           │ root user  in  con‐ │
1914       │        │           │ tainer.)            │
1915       ├────────┼───────────┼─────────────────────┤
1916       │keep-id │ $UID      │ $UID  (Map user ac‐ │
1917       │        │           │ count to  same  UID │
1918       │        │           │ within container.)  │
1919       ├────────┼───────────┼─────────────────────┤
1920       │auto    │ $UID      │ nil  (Host User UID │
1921       │        │           │ is not mapped  into │
1922       │        │           │ container.)         │
1923       ├────────┼───────────┼─────────────────────┤
1924       │nomap   │ $UID      │ nil  (Host User UID │
1925       │        │           │ is not mapped  into │
1926       │        │           │ container.)         │
1927       └────────┴───────────┴─────────────────────┘
1928
1929       Valid mode values are:
1930
1931
1932       auto[:OPTIONS,...]: automatically create a unique user namespace.
1933
1934
1935       The  --userns=auto  flag,  requires that the user name containers and a
1936       range of subordinate user ids that the Podman container is  allowed  to
1937       use be specified in the /etc/subuid and /etc/subgid files.
1938
1939
1940       Example: containers:2147483647:2147483648.
1941
1942
1943       Podman  allocates  unique  ranges  of UIDs and GIDs from the containers
1944       subordinate user ids. The size of the ranges is based on the number  of
1945       UIDs required in the image. The number of UIDs and GIDs can be overrid‐
1946       den with the size option.
1947
1948
1949       The rootless option --userns=keep-id uses all the subuids  and  subgids
1950       of  the user. Using --userns=auto when starting new containers will not
1951       work  as  long  as  any  containers  exist  that  were   started   with
1952       --userns=keep-id.
1953
1954
1955       Valid auto options:
1956
1957
1958gidmapping=_CONTAINER_GID:HOSTGID:SIZE: to force a GID mapping
1959                to be present in the user namespace.
1960
1961size=SIZE: to specify an explicit size for the automatic  user
1962                namespace. e.g. --userns=auto:size=8192. If size is not speci‐
1963                fied, auto will estimate a size for the user namespace.
1964
1965uidmapping=_CONTAINER_UID:HOSTUID:SIZE: to force a UID mapping
1966                to be present in the user namespace.
1967
1968
1969
1970       container:id: join the user namespace of the specified container.
1971
1972
1973       host: run in the user namespace of the caller. The processes running in
1974       the container will have the same privileges on the host  as  any  other
1975       process launched by the calling user (default).
1976
1977
1978       keep-id:  creates  a  user  namespace where the current rootless user's
1979       UID:GID are mapped to the same values in the container. This option  is
1980       not allowed for containers created by the root user.
1981
1982
1983       Valid keep-id options:
1984
1985
1986uid=UID:  override  the  UID inside the container that will be
1987                used to map the current rootless user to.
1988
1989gid=GID: override the GID inside the container  that  will  be
1990                used to map the current rootless user to.
1991
1992
1993
1994       nomap:  creates  a  user  namespace  where  the current rootless user's
1995       UID:GID are not mapped into the container. This option is  not  allowed
1996       for containers created by the root user.
1997
1998
1999       ns:namespace: run the container in the given existing user namespace.
2000
2001
2002   --uts=mode
2003       Set  the UTS namespace mode for the container. The following values are
2004       supported:
2005
2006
2007host: use the host's UTS namespace inside the container.
2008
2009private: create a new namespace for the container (default).
2010
2011ns:[path]: run the container in the given existing  UTS  name‐
2012                space.
2013
2014container:[container]: join the UTS namespace of the specified
2015                container.
2016
2017
2018
2019   --variant=VARIANT
2020       Use VARIANT instead of the default architecture  variant  of  the  con‐
2021       tainer  image.  Some images can use multiple variants of the arm archi‐
2022       tectures, such as arm/v5 and arm/v7.
2023
2024
2025   --volume, -v=[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]
2026       Create a bind mount. If -v /HOST-DIR:/CONTAINER-DIR is specified,  Pod‐
2027       man bind mounts /HOST-DIR from the host into /CONTAINER-DIR in the Pod‐
2028       man container. Similarly, -v  SOURCE-VOLUME:/CONTAINER-DIR  will  mount
2029       the  named  volume  from  the host into the container. If no such named
2030       volume exists, Podman will create one. If no source is given, the  vol‐
2031       ume will be created as an anonymously named volume with a randomly gen‐
2032       erated name, and will be removed when the container is removed via  the
2033       --rm flag or the podman rm --volumes command.
2034
2035
2036       (Note  when using the remote client, including Mac and Windows (exclud‐
2037       ing WSL2) machines, the volumes will be mounted from the remote server,
2038       not necessarily the client machine.)
2039
2040
2041       The OPTIONS is a comma-separated list and can be: [1] ⟨#Footnote1⟩
2042
2043
2044rw|ro
2045
2046z|Z
2047
2048              • [O]
2049
2050              • [U]
2051
2052              • [no]copy
2053
2054              • [no]dev
2055
2056              • [no]exec
2057
2058              • [no]suid
2059
2060              • [r]bind
2061
2062              • [r]shared|[r]slave|[r]private[r]unbindable
2063
2064
2065
2066       The  CONTAINER-DIR must be an absolute path such as /src/docs. The vol‐
2067       ume will be mounted into the container at this directory.
2068
2069
2070       If a volume source is specified, it must be a path on the host  or  the
2071       name  of a named volume. Host paths are allowed to be absolute or rela‐
2072       tive; relative paths are resolved relative to the directory  Podman  is
2073       run  in.  If  the  source  does not exist, Podman will return an error.
2074       Users must pre-create the source files or directories.
2075
2076
2077       Any source that does not begin with a . or / will  be  treated  as  the
2078       name  of  a named volume. If a volume with that name does not exist, it
2079       will be created.  Volumes created with names  are  not  anonymous,  and
2080       they  are  not  removed  by the --rm option and the podman rm --volumes
2081       command.
2082
2083
2084       Specify multiple -v options to mount one or more volumes  into  a  con‐
2085       tainer.
2086
2087
2088       Write Protected Volume Mounts
2089
2090
2091       Add  :ro  or  :rw  option  to mount a volume in read-only or read-write
2092       mode, respectively. By default, the  volumes  are  mounted  read-write.
2093       See examples.
2094
2095
2096       Chowning Volume Mounts
2097
2098
2099       By default, Podman does not change the owner and group of source volume
2100       directories mounted into containers. If a container is created in a new
2101       user  namespace, the UID and GID in the container may correspond to an‐
2102       other UID and GID on the host.
2103
2104
2105       The :U suffix tells Podman to use the correct host UID and GID based on
2106       the  UID  and GID within the container, to change recursively the owner
2107       and group of the source volume.
2108
2109
2110       Warning use with caution since this will modify the host filesystem.
2111
2112
2113       Labeling Volume Mounts
2114
2115
2116       Labeling systems like SELinux require that proper labels are placed  on
2117       volume  content mounted into a container. Without a label, the security
2118       system might prevent the processes running inside  the  container  from
2119       using the content. By default, Podman does not change the labels set by
2120       the OS.
2121
2122
2123       To change a label in the container context, add either of two  suffixes
2124       :z  or  :Z  to  the volume mount. These suffixes tell Podman to relabel
2125       file objects on the shared volumes. The z option tells Podman that  two
2126       containers  share  the  volume  content. As a result, Podman labels the
2127       content with a shared content label. Shared  volume  labels  allow  all
2128       containers  to  read/write content.  The Z option tells Podman to label
2129       the content with a private unshared label.  Only the current  container
2130       can use a private volume.
2131
2132
2133       Note:  Do  not  relabel system files and directories. Relabeling system
2134       content might cause other confined services on your  machine  to  fail.
2135       For  these  types  of containers we recommend disabling SELinux separa‐
2136       tion.  The option --security-opt label=disable disables SELinux separa‐
2137       tion  for  the container.  For example if a user wanted to volume mount
2138       their entire home directory into a  container,  they  need  to  disable
2139       SELinux separation.
2140
2141
2142                 $ podman create --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file
2143
2144
2145
2146       Overlay Volume Mounts
2147
2148
2149       The :O flag tells Podman to mount the directory from the host as a tem‐
2150       porary storage using the overlay file system. The  container  processes
2151       can  modify  content  within the mountpoint which is stored in the con‐
2152       tainer storage in a separate directory. In overlay  terms,  the  source
2153       directory  will  be the lower, and the container storage directory will
2154       be the upper. Modifications to the mount point are destroyed  when  the
2155       container  finishes executing, similar to a tmpfs mount point being un‐
2156       mounted.
2157
2158
2159       For advanced users,  the  overlay  option  also  supports  custom  non-
2160       volatile  upperdir  and  workdir for the overlay mount. Custom upperdir
2161       and workdir can be fully managed by the users  themselves,  and  Podman
2162       will   not   remove   it   on  lifecycle  completion.   Example  :O,up‐
2163       perdir=/some/upper,workdir=/some/work
2164
2165
2166       Subsequent executions of the container will see the original source di‐
2167       rectory  content,  any  changes  from  previous container executions no
2168       longer exist.
2169
2170
2171       One use case of the overlay mount is sharing the package cache from the
2172       host into the container to allow speeding up builds.
2173
2174
2175       Note:
2176
2177
2178               - The `O` flag conflicts with other options listed above.
2179
2180
2181
2182       Content mounted into the container is labeled with the private label.
2183              On SELinux systems, labels in the source directory must be read‐
2184       able by the  container label. Usually containers can read/execute  con‐
2185       tainer_share_t and can read/write container_file_t. If unable to change
2186       the labels on a source volume, SELinux  container  separation  must  be
2187       disabled for the  container to work.
2188            -  The source directory mounted into the container with an overlay
2189       mount should not be modified, it can cause unexpected failures.  It  is
2190       recommended  to  not  modify the directory until the container finishes
2191       running.
2192
2193
2194       Mounts propagation
2195
2196
2197       By default bind mounted volumes are private. That means any mounts done
2198       inside  the  container  will not be visible on host and vice versa. One
2199       can change this behavior by specifying a volume mount propagation prop‐
2200       erty.  Making  a volume shared mounts done under that volume inside the
2201       container will be visible on host and vice versa. Making a volume slave
2202       enables  only one way mount propagation and that is mounts done on host
2203       under that volume will be visible inside container but  not  the  other
2204       way around. [1] ⟨#Footnote1⟩
2205
2206
2207       To  control  mount  propagation  property  of  a volume one can use the
2208       [r]shared, [r]slave, [r]private or the [r]unbindable propagation  flag.
2209       Propagation property can be specified only for bind mounted volumes and
2210       not for internal volumes or named volumes.  For  mount  propagation  to
2211       work  the  source  mount  point  (the  mount  point where source dir is
2212       mounted on) has to have the right propagation  properties.  For  shared
2213       volumes,  the  source  mount point has to be shared. And for slave vol‐
2214       umes, the source mount point has to be either  shared  or  slave.   [1]
2215       ⟨#Footnote1⟩
2216
2217
2218       To  recursively  mount  a  volume  and all of its submounts into a con‐
2219       tainer, use the rbind option. By default the bind option is  used,  and
2220       submounts  of  the  source  directory will not be mounted into the con‐
2221       tainer.
2222
2223
2224       Mounting the volume with the nosuid options means  that  SUID  applica‐
2225       tions  on the volume will not be able to change their privilege. By de‐
2226       fault volumes are mounted with nosuid.
2227
2228
2229       Mounting the volume with the noexec option means that no executables on
2230       the volume will be able to be executed within the container.
2231
2232
2233       Mounting  the volume with the nodev option means that no devices on the
2234       volume will be able to be used by processes within  the  container.  By
2235       default volumes are mounted with nodev.
2236
2237
2238       If  the HOST-DIR is a mount point, then dev, suid, and exec options are
2239       ignored by the kernel.
2240
2241
2242       Use df HOST-DIR to figure out the source mount,  then  use  findmnt  -o
2243       TARGET,PROPAGATION  source-mount-dir  to figure out propagation proper‐
2244       ties of source mount. If findmnt(1) utility is not available, then  one
2245       can   look   at   the  mount  entry  for  the  source  mount  point  in
2246       /proc/self/mountinfo. Look at the "optional  fields"  and  see  if  any
2247       propagation  properties  are  specified.   In there, shared:N means the
2248       mount is shared, master:N means mount  is  slave,  and  if  nothing  is
2249       there, the mount is private. [1] ⟨#Footnote1⟩
2250
2251
2252       To  change  propagation  properties of a mount point, use mount(8) com‐
2253       mand. For example, if one wants to bind mount  source  directory  /foo,
2254       one  can  do  mount  --bind  /foo /foo and mount --make-private --make-
2255       shared /foo. This will convert /foo into a shared mount point. Alterna‐
2256       tively, one can directly change propagation properties of source mount.
2257       Say / is source mount for /foo, then use mount --make-shared / to  con‐
2258       vert / into a shared mount.
2259
2260
2261       Note:  if  the  user  only has access rights via a group, accessing the
2262       volume from inside a rootless container will fail.
2263
2264
2265       Use the --group-add keep-groups option to pass the user's supplementary
2266       group access into the container.
2267
2268
2269   --volumes-from=CONTAINER[:OPTIONS]
2270       Mount  volumes  from  the specified container(s). Used to share volumes
2271       between containers. The options is a comma-separated list with the fol‐
2272       lowing available elements:
2273
2274
2275rw|ro
2276
2277z
2278
2279
2280
2281       Mounts  already  mounted  volumes  from a source container onto another
2282       container. CONTAINER may be a name or ID.  To share a volume,  use  the
2283       --volumes-from option when running the target container. Volumes can be
2284       shared even if the source container is not running.
2285
2286
2287       By default, Podman mounts the volumes in the same mode  (read-write  or
2288       read-only)  as  it  is  mounted  in  the source container.  This can be
2289       changed by adding a ro or rw option.
2290
2291
2292       Labeling systems like SELinux require that proper labels are placed  on
2293       volume  content mounted into a container. Without a label, the security
2294       system might prevent the processes running inside  the  container  from
2295       using the content. By default, Podman does not change the labels set by
2296       the OS.
2297
2298
2299       To change a label in the container context, add z to the volume  mount.
2300       This suffix tells Podman to relabel file objects on the shared volumes.
2301       The z option tells Podman that two entities share the  volume  content.
2302       As  a  result,  Podman  labels the content with a shared content label.
2303       Shared volume labels allow all containers to read/write content.
2304
2305
2306       If the location of the volume from the source container  overlaps  with
2307       data residing on a target container, then the volume hides that data on
2308       the target.
2309
2310
2311   --workdir, -w=dir
2312       Working directory inside the container.
2313
2314
2315       The default working directory for running binaries within  a  container
2316       is the root directory (/).  The image developer can set a different de‐
2317       fault with the WORKDIR instruction. The operator can override the work‐
2318       ing directory by using the -w option.
2319
2320

EXAMPLES

2322   Create a container using a local image
2323              $ podman create alpine ls
2324
2325
2326
2327   Create a container using a local image and annotate it
2328              $ podman create --annotation HELLO=WORLD alpine ls
2329
2330
2331
2332   Create  a  container  using a local image, allocating a pseudo-TTY, keeping
2333       stdin open and name it myctr
2334                podman create -t -i --name myctr alpine ls
2335
2336
2337
2338   Set UID/GID mapping in a new user namespace
2339       Running a container in a new user namespace requires a mapping  of  the
2340       uids and gids from the host.
2341
2342
2343              $ podman create --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello
2344
2345
2346
2347   Setting automatic user namespace separated containers
2348              # podman create --userns=auto:size=65536 ubi8-init
2349
2350
2351
2352   Configure timezone in a container
2353              $ podman create --tz=local alpine date
2354              $ podman create --tz=Asia/Shanghai alpine date
2355              $ podman create --tz=US/Eastern alpine date
2356
2357
2358
2359   Adding dependency containers
2360       Podman  will  make sure the first container, container1, is running be‐
2361       fore the second container (container2) is started.
2362
2363
2364              $ podman create --name container1 -t -i fedora bash
2365              $ podman create --name container2 --requires container1 -t -i fedora bash
2366              $ podman start --attach container2
2367
2368
2369
2370       Multiple containers can be required.
2371
2372
2373              $ podman create --name container1 -t -i fedora bash
2374              $ podman create --name container2 -t -i fedora bash
2375              $ podman create --name container3 --requires container1,container2 -t -i fedora bash
2376              $ podman start --attach container3
2377
2378
2379
2380   Configure keep supplemental groups for access to volume
2381              $ podman create -v /var/lib/design:/var/lib/design --group-add keep-groups ubi8
2382
2383
2384
2385   Configure execution domain for containers using personality flag
2386              $ podman create --name container1 --personality=LINUX32 fedora bash
2387
2388
2389
2390   Create a container with external rootfs mounted as an overlay
2391              $ podman create --name container1 --rootfs /path/to/rootfs:O bash
2392
2393
2394
2395   Create a container connected to two networks (called net1 and net2) with  a
2396       static ip
2397              $ podman create --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 alpine ip addr
2398
2399
2400
2401   Rootless Containers
2402       Podman  runs  as a non-root user on most systems. This feature requires
2403       that a new enough version of shadow-utils  be  installed.  The  shadow-
2404       utils package must include the newuidmap and newgidmap executables.
2405
2406
2407       In  order  for  users to run rootless, there must be an entry for their
2408       username in /etc/subuid and /etc/subgid which lists the UIDs for  their
2409       user namespace.
2410
2411
2412       Rootless  Podman  works  better  if  the fuse-overlayfs and slirp4netns
2413       packages  are  installed.   The  fuse-overlayfs  package   provides   a
2414       userspace  overlay  storage driver, otherwise users need to use the vfs
2415       storage driver, which is diskspace expensive and does not perform well.
2416       slirp4netns  is  required for VPN, without it containers need to be run
2417       with the --network=host flag.
2418
2419

ENVIRONMENT

2421       Environment variables within containers can be set using multiple  dif‐
2422       ferent options:  This section describes the precedence.
2423
2424
2425       Precedence order (later entries override earlier entries):
2426
2427
2428--env-host  : Host environment of the process executing Podman
2429                is added.
2430
2431--http-proxy: By default, several environment  variables  will
2432                be  passed  in from the host, such as http_proxy and no_proxy.
2433                See --http-proxy for details.
2434
2435              • Container image : Any environment variables specified  in  the
2436                container image.
2437
2438--env-file  :  Any  environment  variables  specified via env-
2439                files. If multiple files specified, then  they  override  each
2440                other in order of entry.
2441
2442--env : Any environment variables specified will override pre‐
2443                vious settings.
2444
2445
2446
2447       Create containers and set the environment ending with a *.  The  trail‐
2448       ing * glob functionality is only active when no value is specified:
2449
2450
2451              $ export ENV1=a
2452              $ podman create --name ctr1 --env 'ENV*' alpine env
2453              $ podman start --attach ctr1 | grep ENV
2454              ENV1=a
2455              $ podman create --name ctr2 --env 'ENV*=b' alpine env
2456              $ podman start --attach ctr2 | grep ENV
2457              ENV*=b
2458
2459
2460

CONMON

2462       When Podman starts a container it actually executes the conmon program,
2463       which then executes the OCI Runtime.  Conmon is the container  monitor.
2464       It  is a small program whose job is to watch the primary process of the
2465       container, and if the container dies, save  the  exit  code.   It  also
2466       holds  open  the  tty  of  the container, so that it can be attached to
2467       later. This is what allows  Podman  to  run  in  detached  mode  (back‐
2468       grounded),  so  Podman can exit but conmon continues to run.  Each con‐
2469       tainer has their own instance of conmon. Conmon waits for the container
2470       to  exit,  gathers  and saves the exit code, and then launches a Podman
2471       process to complete the container cleanup, by shutting down the network
2472       and  storage.    For  more  information on conmon, please reference the
2473       conmon(8) man page.
2474
2475

FILES

2477       /etc/subuid /etc/subgid
2478
2479
2480       NOTE: Use the environment variable TMPDIR to change the temporary stor‐
2481       age  location  of  downloaded  container images. Podman defaults to use
2482       /var/tmp.
2483
2484

SEE ALSO

2486       podman(1), podman-save(1), podman-ps(1), podman-attach(1),  podman-pod-
2487       create(1),  podman-port(1),  podman-start(1),  podman-kill(1),  podman-
2488       stop(1),  podman-generate-systemd(1),  podman-rm(1),  subgid(5),   sub‐
2489       uid(5),      containers.conf(5),     systemd.unit(5),     setsebool(8),
2490       slirp4netns(1), fuse-overlayfs(1), proc(5), conmon(8), personality(2)
2491
2492

HISTORY

2494       October 2017, converted from Docker  documentation  to  Podman  by  Dan
2495       Walsh for Podman <dwalsh@redhat.com>
2496
2497
2498       November 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
2499
2500
2501       September 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
2502
2503
2504       August 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
2505
2506

FOOTNOTES

2508       1: The Podman project is committed to inclusivity, a core value of open
2509       source. The master and slave mount propagation terminology used here is
2510       problematic  and  divisive, and should be changed. However, these terms
2511       are currently used within the Linux kernel and must be  used  as-is  at
2512       this  time. When the kernel maintainers rectify this usage, Podman will
2513       follow suit immediately.
2514
2515
2516
2517                                                              podman-create(1)
Impressum