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

OPTIONS

96   --add-host=host
97       Add a custom host-to-IP mapping (host:ip)
98
99
100       Add a line to /etc/hosts. The format is hostname:ip. The --add-host op‐
101       tion can be set multiple times.
102
103
104   --annotation=key=value
105       Add an annotation to the container. The format is key=value.  The --an‐
106       notation option can be set multiple times.
107
108
109   --arch=ARCH
110       Override  the  architecture,  defaults  to  hosts,  of  the image to be
111       pulled. For example, arm.
112
113
114   --attach, -a=location
115       Attach to STDIN, STDOUT or STDERR.
116
117
118       In foreground mode (the default when -d is not specified),  podman  run
119       can  start  the  process in the container and attach the console to the
120       process's standard input, output, and standard error. It can even  pre‐
121       tend  to  be  a TTY (this is what most command line executables expect)
122       and pass along signals. The -a option can be set  for  each  of  stdin,
123       stdout, and stderr.
124
125
126   --authfile=path
127       Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
128       ers/auth.json
129
130
131       Note: You can also override the default path of the authentication file
132       by  setting  the  REGISTRY_AUTH_FILE  environment variable. export REG‐
133       ISTRY_AUTH_FILE=path
134
135
136   --blkio-weight=weight
137       Block IO weight (relative weight) accepts a weight value between 10 and
138       1000.
139
140
141   --blkio-weight-device=weight
142       Block IO weight (relative device weight, format: DEVICE_NAME:WEIGHT).
143
144
145   --cap-add=capability
146       Add Linux capabilities
147
148
149   --cap-drop=capability
150       Drop Linux capabilities
151
152
153   --cgroupns=mode
154       Set the cgroup namespace mode for the container.
155           host: use the host's cgroup namespace inside the container.
156           container:<NAME|ID>: join the namespace of the specified container.
157           ns:<PATH>: join the namespace at the specified path.
158           private: create a new cgroup namespace.
159
160
161       If  the host uses cgroups v1, the default is set to host. On cgroups v2
162       the default is private.
163
164
165   --cgroups=mode
166       Determines whether the container will create CGroups.  Valid values are
167       enabled, disabled, no-conmon, split, which the default being enabled.
168
169
170       The  enabled  option  will create a new cgroup under the cgroup-parent.
171       The disabled option will force the container to not create CGroups, and
172       thus  conflicts  with  CGroup options (--cgroupns and --cgroup-parent).
173       The no-conmon option disables a new CGroup only for the conmon process.
174       The  split option splits the current cgroup in two sub-cgroups: one for
175       conmon and one for the container payload. It is  not  possible  to  set
176       --cgroup-parent with split.
177
178
179   --cgroup-parent=path
180       Path  to  cgroups under which the cgroup for the container will be cre‐
181       ated. If the path is not absolute, the path is considered to  be  rela‐
182       tive  to  the cgroups path of the init process. Cgroups will be created
183       if they do not already exist.
184
185
186   --cgroup-conf=KEY=VALUE
187       When running on cgroup v2, specify the cgroup file to write to and  its
188       value.  For  example --cgroup-conf=memory.high=1073741824 sets the mem‐
189       ory.high limit to 1GB.
190
191
192   --cidfile=id
193       Write the container ID to the file
194
195
196   --conmon-pidfile=path
197       Write the pid of the conmon process to a file. conmon runs in  a  sepa‐
198       rate  process  than  Podman, so this is necessary when using systemd to
199       restart Podman containers.  (This option is not available with the  re‐
200       mote Podman client)
201
202
203   --cpu-period=limit
204       Set  the CPU period for the Completely Fair Scheduler (CFS), which is a
205       duration in microseconds. Once the container's CPU quota is used up, it
206       will not be scheduled to run until the current period ends. Defaults to
207       100000 microseconds.
208
209
210       On some systems, changing  the  CPU  limits  may  not  be  allowed  for
211       non-root  users.  For  more  details,  see  https://github.com/contain
212       ers/podman/blob/master/troubleshooting.md#26-running-contain‐
213       ers-with-cpu-limits-fails-with-a-permissions-error
214
215
216   --cpu-quota=limit
217       Limit the CPU Completely Fair Scheduler (CFS) quota.
218
219
220       Limit  the  container's  CPU usage. By default, containers run with the
221       full CPU resource. The limit is a number in microseconds. If  you  pro‐
222       vide  a number, the container will be allowed to use that much CPU time
223       until the CPU period ends (controllable via --cpu-period).
224
225
226       On some systems, changing  the  CPU  limits  may  not  be  allowed  for
227       non-root  users.  For  more  details,  see  https://github.com/contain
228       ers/podman/blob/master/troubleshooting.md#26-running-contain‐
229       ers-with-cpu-limits-fails-with-a-permissions-error
230
231
232   --cpu-rt-period=microseconds
233       Limit the CPU real-time period in microseconds
234
235
236       Limit the container's Real Time CPU usage. This flag tell the kernel to
237       restrict the container's Real Time CPU usage to the period you specify.
238
239
240   --cpu-rt-runtime=microseconds
241       Limit the CPU real-time runtime in microseconds
242
243
244       Limit the containers Real Time CPU usage. This flag tells the kernel to
245       limit the amount of time in a given CPU period Real Time tasks may con‐
246       sume. Ex: Period of 1,000,000us and Runtime  of  950,000us  means  that
247       this container could consume 95% of available CPU and leave the remain‐
248       ing 5% to normal priority tasks.
249
250
251       The sum of all runtimes across containers cannot exceed the amount  al‐
252       lotted to the parent cgroup.
253
254
255   --cpu-shares=shares
256       CPU shares (relative weight)
257
258
259       By  default, all containers get the same proportion of CPU cycles. This
260       proportion can be  modified  by  changing  the  container's  CPU  share
261       weighting relative to the weighting of all other running containers.
262
263
264       To modify the proportion from the default of 1024, use the --cpu-shares
265       flag to set the weighting to 2 or higher.
266
267
268       The proportion will only apply when CPU-intensive  processes  are  run‐
269       ning.   When  tasks in one container are idle, other containers can use
270       the left-over CPU time. The actual amount of CPU time will vary depend‐
271       ing on the number of containers running on the system.
272
273
274       For example, consider three containers, one has a cpu-share of 1024 and
275       two others have a cpu-share setting of 512. When processes in all three
276       containers  attempt  to  use 100% of CPU, the first container would re‐
277       ceive 50% of the total CPU time. If you add a fourth container  with  a
278       cpu-share  of  1024,  the first container only gets 33% of the CPU. The
279       remaining containers receive 16.5%, 16.5% and 33% of the CPU.
280
281
282       On a multi-core system, the shares of CPU time are distributed over all
283       CPU  cores.  Even  if  a  container is limited to less than 100% of CPU
284       time, it can use 100% of each individual CPU core.
285
286
287       For example, consider a system with more than three cores. If you start
288       one  container  {C0}  with -c=512 running one process, and another con‐
289       tainer {C1} with -c=1024 running two processes, this can result in  the
290       following division of CPU shares:
291
292
293       PID     container    CPU  CPU  share  100     {C0}         0    100% of
294       CPU0      101         {C1}         1    100%      of      CPU1      102
295       {C1}         2    100% of CPU2
296
297
298   --cpus=number
299       Number of CPUs. The default is 0.0 which means no limit. This is short‐
300       hand for --cpu-period and --cpu-quota, so you may only set either
301
302
303   --cpus or --cpu-period and --cpu-quota.
304       On some systems, changing  the  CPU  limits  may  not  be  allowed  for
305       non-root  users.  For  more  details,  see  https://github.com/contain
306       ers/podman/blob/master/troubleshooting.md#26-running-contain‐
307       ers-with-cpu-limits-fails-with-a-permissions-error
308
309
310   --cpuset-cpus=cpus
311       CPUs in which to allow execution (0-3, 0,1)
312
313
314   --cpuset-mems=nodes
315       Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effec‐
316       tive on NUMA systems.
317
318
319       If  you  have  four  memory   nodes   on   your   system   (0-3),   use
320       --cpuset-mems=0,1 then processes in your container will only use memory
321       from the first two memory nodes.
322
323
324   --device=host-device[:container-device][:permissions]
325       Add a host device to the container. Optional permissions parameter  can
326       be used to specify device permissions, it is combination of r for read,
327       w for write, and m for mknod(2).
328
329
330       Example: --device=/dev/sdc:/dev/xvdc:rwm.
331
332
333       Note: if _hostdevice is a symbolic link then it will be resolved first.
334       The  container  will only store the major and minor numbers of the host
335       device.
336
337
338       Note: if the user only has access rights via a group, accessing the de‐
339       vice  from  inside  a rootless container will fail. Use the --group-add
340       keep-groups flag to pass the user's supplementary group access into the
341       container.
342
343
344       Podman may load kernel modules required for using the specified device.
345       The  devices  that  podman  will  load  modules  when  necessary   are:
346       /dev/fuse.
347
348
349   --device-cgroup-rule="type major:minor mode"
350       Add  a rule to the cgroup allowed devices list. The rule is expected to
351       be in the format specified in the Linux kernel documentation  (Documen‐
352       tation/cgroup-v1/devices.txt):
353              - type: a (all), c (char), or b (block);
354              - major and minor: either a number, or * for all;
355              - mode: a composition of r (read), w (write), and m (mknod(2)).
356
357
358   --device-read-bps=path
359       Limit   read  rate  (bytes  per  second)  from  a  device  (e.g.  --de‐
360       vice-read-bps=/dev/sda:1mb)
361
362
363   --device-read-iops=path
364       Limit  read  rate  (IO  per  second)  from   a   device   (e.g.   --de‐
365       vice-read-iops=/dev/sda:1000)
366
367
368   --device-write-bps=path
369       Limit   write   rate  (bytes  per  second)  to  a  device  (e.g.  --de‐
370       vice-write-bps=/dev/sda:1mb)
371
372
373   --device-write-iops=path
374       Limit  write  rate  (IO  per  second)   to   a   device   (e.g.   --de‐
375       vice-write-iops=/dev/sda:1000)
376
377
378   --disable-content-trust
379       This  is  a  Docker  specific option to disable image verification to a
380       Docker registry and is not supported by Podman. This flag is a NOOP and
381       provided solely for scripting compatibility.
382
383
384   --dns=dns
385       Set  custom  DNS  servers. Invalid if using --dns and --network that is
386       set to 'none' or container:<name|id>.
387
388
389       This option can be used to override the DNS configuration passed to the
390       container.  Typically this is necessary when the host DNS configuration
391       is invalid for the container (e.g., 127.0.0.1). When this is  the  case
392       the --dns flags is necessary for every run.
393
394
395       The special value none can be specified to disable creation of /etc/re‐
396       solv.conf in the container by Podman.  The /etc/resolv.conf file in the
397       image will be used without changes.
398
399
400   --dns-opt=option
401       Set  custom  DNS options. Invalid if using --dns-opt and --network that
402       is set to 'none' or container:<name|id>.
403
404
405   --dns-search=domain
406       Set custom DNS search domains. Invalid if using --dns-search and --net‐
407       work  that is set to 'none' or container:<name|id>. (Use --dns-search=.
408       if you don't wish to set the search domain)
409
410
411   --entrypoint="command" | '["command", arg1 , ...]'
412       Overwrite the default ENTRYPOINT of the image
413
414
415       This option allows you to overwrite the default entrypoint of  the  im‐
416       age.   The  ENTRYPOINT  of  an image is similar to a COMMAND because it
417       specifies what executable to run when the container starts, but  it  is
418       (purposely)  more  difficult  to  override. The ENTRYPOINT gives a con‐
419       tainer its default nature or behavior, so that when you set  an  ENTRY‐
420       POINT  you  can  run  the container as if it were that binary, complete
421       with default options, and you can pass in more options via the COMMAND.
422       But,  sometimes  an  operator may want to run something else inside the
423       container, so you can override the default ENTRYPOINT at runtime by us‐
424       ing a --entrypoint and a string to specify the new ENTRYPOINT.
425
426
427       You need to specify multi option commands in the form of a json string.
428
429
430   --env, -e=env
431       Set environment variables
432
433
434       This  option  allows arbitrary environment variables that are available
435       for the process to be launched inside of the container. If an  environ‐
436       ment  variable is specified without a value, Podman will check the host
437       environment for a value and set the variable only if it is set  on  the
438       host.  If an environment variable ending in * is specified, Podman will
439       search the host environment for variables starting with the prefix  and
440       will  add  those variables to the container. If an environment variable
441       with a trailing ***** is specified, then a value must be supplied.
442
443
444       See Environment ⟨#environment⟩ note below for precedence and examples.
445
446
447   --env-host=true|false
448       Use host environment inside of the container. See Environment note  be‐
449       low  for precedence. (This option is not available with the remote Pod‐
450       man client)
451
452
453   --env-file=file
454       Read in a line delimited file of environment variables. See Environment
455       note below for precedence.
456
457
458   --expose=port
459       Expose  a port, or a range of ports (e.g. --expose=3300-3310) to set up
460       port redirection on the host system.
461
462
463   --gidmap=container_gid:host_gid:amount
464       GID map for the user namespace. Using this flag will run the  container
465       with  user namespace enabled. It conflicts with the --userns and --sub‐
466       gidname flags.
467
468
469       The following example maps uids 0-2000 in the  container  to  the  uids
470       30000-31999  on  the  host and gids 0-2000 in the container to the gids
471       30000-31999 on the host. --gidmap=0:30000:2000
472
473
474   --group-add=group|keep-groups
475       Add additional groups to assign to primary user running within the con‐
476       tainer process.
477
478
479keep-groups  is  a  special flag that tells Podman to keep the
480                supplementary group access.
481
482
483
484       Allows container to use the user's supplementary group access. If  file
485       systems  or  devices  are only accessible by the rootless user's group,
486       this flag tells the OCI runtime to pass the group access into the  con‐
487       tainer.  Currently  only  available  with  the  crun OCI runtime. Note:
488       keep-groups is exclusive, you cannot add any  other  groups  with  this
489       flag. (Not available for remote commands)
490
491
492   --health-cmd="command" | '["command", arg1 , ...]'
493       Set  or  alter  a healthcheck command for a container. The command is a
494       command to be executed inside your container that determines your  con‐
495       tainer health. The command is required for other healthcheck options to
496       be applied. A value of none disables existing healthchecks.
497
498
499       Multiple options can be passed in the form of a JSON array;  otherwise,
500       the command will be interpreted as an argument to /bin/sh -c.
501
502
503   --health-interval=interval
504       Set  an interval for the healthchecks (a value of disable results in no
505       automatic timer setup) (default "30s")
506
507
508   --health-retries=retries
509       The number of retries allowed before a healthcheck is considered to  be
510       unhealthy. The default value is 3.
511
512
513   --health-start-period=period
514       The  initialization time needed for a container to bootstrap. The value
515       can be expressed in time format like 2m3s. The default value is 0s
516
517
518   --health-timeout=timeout
519       The maximum time allowed to complete the healthcheck before an interval
520       is  considered failed. Like start-period, the value can be expressed in
521       a time format such as 1m22s. The default value is 30s.
522
523
524   --hostname=name, -h
525       Container host name
526
527
528       Sets the container host name that is available  inside  the  container.
529       Can  only be used with a private UTS namespace --uts=private (default).
530       If --pod is specified and the pod shares the  UTS  namespace  (default)
531       the pod's hostname will be used.
532
533
534   --help
535       Print usage statement
536
537
538   --http-proxy=true|false
539       By default proxy environment variables are passed into the container if
540       set for the Podman  process.  This  can  be  disabled  by  setting  the
541       --http-proxy  option  to false. The environment variables passed in in‐
542       clude http_proxy, https_proxy, ftp_proxy, no_proxy, and also the  upper
543       case versions of those. This option is only needed when the host system
544       must use a proxy but the container should not use any proxy. Proxy  en‐
545       vironment  variables  specified for the container in any other way will
546       override the values that would have been passed through from the  host.
547       (Other  ways to specify the proxy for the container include passing the
548       values with the --env flag, or hard coding  the  proxy  environment  at
549       container  build  time.)  (This option is not available with the remote
550       Podman client)
551
552
553       For example, to disable passing these environment variables  from  host
554       to container:
555
556
557       --http-proxy=false
558
559
560       Defaults to true
561
562
563   --image-volume, builtin-volume=bind|tmpfs|ignore
564       Tells Podman how to handle the builtin image volumes. Default is bind.
565
566
567bind:  An  anonymous  named volume will be created and mounted
568                into the container.
569
570tmpfs: The volume is mounted onto the container  as  a  tmpfs,
571                which  allows the users to create content that disappears when
572                the container is stopped.
573
574ignore: All volumes are just ignored and no action is taken.
575
576
577
578   --init
579       Run an init inside the container that forwards signals and  reaps  pro‐
580       cesses.
581
582
583   --init-path=path
584       Path to the container-init binary.
585
586
587   --interactive, -i=true|false
588       Keep STDIN open even if not attached. The default is false.
589
590
591   --ip6=ip
592       Not implemented
593
594
595   --ip=ip
596       Specify   a   static   IP   address  for  the  container,  for  example
597       10.88.64.128.  This option can only be used if the container is  joined
598       to  only  a  single network - i.e., --network=_network-name_ is used at
599       most once - and if the container is  not  joining  another  container's
600       network  namespace  via  --network=container:_id_.  The address must be
601       within the CNI network's IP address pool (default 10.88.0.0/16).
602
603
604   --ipc=ipc
605       Default is to create a private IPC namespace (POSIX SysV IPC)  for  the
606       container             container:<name|id>:   reuses  another  container
607       shared memory, semaphores and message queues            host:  use  the
608       host  shared memory,semaphores and message queues inside the container.
609       Note: the host mode gives the container full  access  to  local  shared
610       memory  and is therefore considered insecure.            ns:<path> path
611       to an IPC namespace to join.
612
613
614   --kernel-memory=number[unit]
615       Kernel memory limit (format: <number>[<unit>], where unit = b  (bytes),
616       k (kilobytes), m (megabytes), or g (gigabytes))
617
618
619       Constrains  the kernel memory available to a container. If a limit of 0
620       is specified (not using --kernel-memory), the container's kernel memory
621       is  not limited. If you specify a limit, it may be rounded up to a mul‐
622       tiple of the operating system's page size and the  value  can  be  very
623       large, millions of trillions.
624
625
626   --label, -l=label
627       Add metadata to a container (e.g., --label com.example.key=value)
628
629
630   --label-file=file
631       Read in a line delimited file of labels
632
633
634   --link-local-ip=ip
635       Not implemented
636
637
638   --log-driver="k8s-file"
639       Logging  driver  for  the  container.  Currently  available options are
640       k8s-file, journald, and none, with json-file aliased  to  k8s-file  for
641       scripting compatibility.
642
643
644   --log-opt=name=value
645       Set custom logging configuration. The following *name*s are supported:
646
647
648path:   specify  a  path  to  the  log  file  (e.g.  --log-opt
649                path=/var/log/container/mycontainer.json);
650
651max-size: specify a max size of the log file  (e.g.  --log-opt
652                max-size=10mb);
653
654tag:  specify  a  custom  log  tag  for  the  container  (e.g.
655                --log-opt tag="{{.ImageName}}".
656
657
658
659       It supports the same keys as podman inspect --format.
660
661
662       This option is currently supported only by the journald log driver.
663
664
665       --log-opt tag="{{.ImageName}}"
666
667
668       It supports the same keys as podman inspect --format.
669
670
671       It is currently supported only by the journald log driver.
672
673
674   --mac-address=address
675       Container MAC address (e.g. 92:d0:c6:0a:29:33)
676
677
678       Remember that the MAC address in an Ethernet network  must  be  unique.
679       The  IPv6  link-local address will be based on the device's MAC address
680       according to RFC4862.
681
682
683   --memory, -m=limit
684       Memory limit (format: <number>[<unit>],  where  unit  =  b  (bytes),  k
685       (kilobytes), m (megabytes), or g (gigabytes))
686
687
688       Allows  you  to  constrain  the memory available to a container. If the
689       host supports swap memory, then the -m memory  setting  can  be  larger
690       than  physical  RAM.  If  a limit of 0 is specified (not using -m), the
691       container's memory is not limited. The actual limit may be  rounded  up
692       to  a  multiple of the operating system's page size (the value would be
693       very large, that's millions of trillions).
694
695
696   --memory-reservation=limit
697       Memory soft limit (format: <number>[<unit>], where unit = b (bytes),  k
698       (kilobytes), m (megabytes), or g (gigabytes))
699
700
701       After  setting  memory reservation, when the system detects memory con‐
702       tention or low memory, containers are forced to restrict their consump‐
703       tion  to  their  reservation.  So you should always set the value below
704       --memory, otherwise the hard limit will take  precedence.  By  default,
705       memory reservation will be the same as memory limit.
706
707
708   --memory-swap=limit
709       A  limit  value  equal  to  memory plus swap. Must be used with the  -m
710       (--memory) flag. The swap LIMIT should always be larger than -m (--mem‐
711       ory)  value. By default, the swap LIMIT will be set to double the value
712       of --memory.
713
714
715       The format of LIMIT is <number>[<unit>].  Unit  can  be  b  (bytes),  k
716       (kilobytes),  m  (megabytes),  or g (gigabytes). If you don't specify a
717       unit, b is used. Set LIMIT to -1 to enable unlimited swap.
718
719
720   --memory-swappiness=number
721       Tune a container's memory swappiness behavior. Accepts an  integer  be‐
722       tween 0 and 100.
723
724
725   --mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]
726       Attach a filesystem mount to the container
727
728
729       Current  supported  mount  TYPEs are bind, volume, image, tmpfs and de‐
730       vpts. [1] ⟨#Footnote1⟩
731
732
733                 e.g.
734
735                 type=bind,source=/path/on/host,destination=/path/in/container
736
737                 type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared
738
739                 type=volume,source=vol1,destination=/path/in/container,ro=true
740
741                 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
742
743                 type=image,source=fedora,destination=/fedora-image,rw=true
744
745                 type=devpts,destination=/dev/pts
746
747                 Common Options:
748
749                    · src, source: mount source spec for bind and volume. Mandatory for bind.
750
751                    · dst, destination, target: mount destination spec.
752
753                 Options specific to volume:
754
755                    · ro, readonly: true or false (default).
756
757                 Options specific to image:
758
759                    · rw, readwrite: true or false (default).
760
761                 Options specific to bind:
762
763                    · ro, readonly: true or false (default).
764
765                    · bind-propagation: shared, slave, private, unbindable, rshared, rslave, runbindable, or rprivate(default). See also mount(2).
766
767                    . bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive.
768
769                    . relabel: shared, private.
770
771                 Options specific to tmpfs:
772
773                    · ro, readonly: true or false (default).
774
775                    · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
776
777                    · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
778
779                    · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs. Used by default.
780
781                    · notmpcopyup: Disable copying files from the image to the tmpfs.
782
783
784
785   --name=name
786       Assign a name to the container
787
788
789       The operator can identify a container in three ways: UUID long  identi‐
790       fier
791       (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”)
792       UUID short identifier (“f78375b1c487”) Name (“jonah”)
793
794
795       podman  generates  a  UUID for each container, and if a name is not as‐
796       signed to the container with --name then  it  will  generate  a  random
797       string  name.  The name is useful any place you need to identify a con‐
798       tainer.  This works for both background and foreground containers.
799
800
801   --network=mode, --net
802       Set the network  mode  for  the  container.  Invalid  if  using  --dns,
803       --dns-opt,  or  --dns-search with --network that is set to none or con‐
804       tainer:id. If used together with --pod, the container will not join the
805       pod's network namespace.
806
807
808       Valid mode values are:
809
810
811bridge: create a network stack on the default bridge;
812
813none: no networking;
814
815container:id: reuse another container's network stack;
816
817host:  use  the Podman host network stack. Note: the host mode
818                gives the container full access to local system services  such
819                as D-bus and is therefore considered insecure;
820
821network-id:  connect  to a user-defined network, multiple net‐
822                works should be comma-separated;
823
824ns:path: path to a network namespace to join;
825
826private: create a new namespace for the container (default)
827
828slirp4netns[:OPTIONS,...]: use slirp4netns(1) to create a user
829                network stack. This is the default for rootless containers. It
830                is possible to specify these additional options:
831
832allow_host_loopback=true|false:  Allow  the  slirp4netns  to
833                  reach the host loopback IP (10.0.2.2). Default is false.
834
835mtu=MTU:  Specify  the MTU to use for this network. (Default
836                  is 65520).
837
838cidr=CIDR: Specify ip range to use for  this  network.  (De‐
839                  fault is 10.0.2.0/24).
840
841enable_ipv6=true|false:  Enable IPv6. Default is false. (Re‐
842                  quired for outbound_addr6).
843
844outbound_addr=INTERFACE:  Specify  the  outbound   interface
845                  slirp should bind to (ipv4 traffic only).
846
847outbound_addr=IPv4:  Specify the outbound ipv4 address slirp
848                  should bind to.
849
850outbound_addr6=INTERFACE:  Specify  the  outbound  interface
851                  slirp should bind to (ipv6 traffic only).
852
853outbound_addr6=IPv6: Specify the outbound ipv6 address slirp
854                  should bind to.
855
856port_handler=rootlesskit: Use rootlesskit for port  forward‐
857                  ing. Default.
858
859port_handler=slirp4netns:  Use the slirp4netns port forward‐
860                  ing.
861
862
863
864
865
866   --network-alias=alias
867       Add network-scoped alias for the container
868
869
870   --no-healthcheck=true|false
871       Disable any defined healthchecks for container.
872
873
874   --no-hosts=true|false
875       Do not create /etc/hosts for the container.  By  default,  Podman  will
876       manage  /etc/hosts, adding the container's own IP address and any hosts
877       from --add-host.
878
879
880   --no-hosts disables this, and the image's /etc/host will be  preserved  un‐
881       modified.
882       This option conflicts with --add-host.
883
884
885   --oom-kill-disable=true|false
886       Whether to disable OOM Killer for the container or not.
887
888
889   --oom-score-adj=num
890       Tune the host's OOM preferences for containers (accepts -1000 to 1000)
891
892
893   --os=OS
894       Override  the OS, defaults to hosts, of the image to be pulled. For ex‐
895       ample, windows.
896
897
898   --pid=pid
899       Set the PID mode for the container Default is to create a  private  PID
900       namespace  for  the  container - container:<name|id>: join another con‐
901       tainer's PID namespace - host: use the host's  PID  namespace  for  the
902       container. Note: the host mode gives the container full access to local
903       PID and is therefore considered insecure.  - ns: join the specified PID
904       namespace - private: create a new namespace for the container (default)
905
906
907   --pids-limit=limit
908       Tune  the  container's pids limit. Set 0 to have unlimited pids for the
909       container. (default "4096" on systems that support PIDS cgroups).
910
911
912   --platform=OS/ARCH
913       Specify the platform for selecting the image.   (Conflicts with  --arch
914       and --os) The --platform option can be used to override the current ar‐
915       chitecture and operating system.
916
917
918   --pod=name
919       Run container in an existing pod. If you want Podman to  make  the  pod
920       for  you,  preference  the pod name with new:.  To make a pod with more
921       granular options, use the podman pod create command before  creating  a
922       container.
923
924
925   --pod-id-file=path
926       Run  container in an existing pod and read the pod's ID from the speci‐
927       fied file. If a container is run within a pod, and the pod has  an  in‐
928       fra-container, the infra-container will be started before the container
929       is.
930
931
932   --privileged=true|false
933       Give extended privileges to this container. The default is false.
934
935
936       By default, Podman containers are “unprivileged” (=false)  and  cannot,
937       for  example, modify parts of the operating system.  This is because by
938       default a container is not allowed to access any  devices.   A  “privi‐
939       leged” container is given access to all devices.
940
941
942       When  the  operator executes a privileged container, Podman enables ac‐
943       cess to all devices on the host, turns off graphdriver  mount  options,
944       as  well  as  turning  off most of the security measures protecting the
945       host from the container.
946
947
948       Rootless containers cannot have more privileges than the  account  that
949       launched them.
950
951
952   --publish, -p=port
953       Publish a container's port, or range of ports, to the host
954
955
956       Format:  ip:hostPort:containerPort  | ip::containerPort | hostPort:con‐
957       tainerPort | containerPort Both hostPort and containerPort can be spec‐
958       ified as a range of ports.  When specifying ranges for both, the number
959       of container ports in the range must match the number of host ports  in
960       the  range.   (e.g., podman run -p 1234-1236:1222-1224 --name thisWorks
961       -t busybox but not podman run -p 1230-1236:1230-1240  --name  RangeCon‐
962       tainerPortsBiggerThanRangeHostPorts  -t  busybox)  With host IP: podman
963       run -p 127.0.0.1:$HOSTPORT:$CONTAINERPORT --name CONTAINER -t someimage
964       If  host IP is set to 0.0.0.0 or not set at all, the port will be bound
965       on all IPs on the host.  Host port does not have to be specified  (e.g.
966       podman run -p 127.0.0.1::80).  If it is not, the container port will be
967       randomly assigned a port on the host.  Use podman port to see  the  ac‐
968       tual mapping: podman port CONTAINER $CONTAINERPORT
969
970
971       Note:  if  a container will be run within a pod, it is not necessary to
972       publish the port for the containers in the pod. The port must  only  be
973       published  by  the  pod itself. Pod network stacks act like the network
974       stack on the host - you have a variety of containers in  the  pod,  and
975       programs  in  the  container, all sharing a single interface and IP ad‐
976       dress, and associated ports. If one container binds to a port, no other
977       container can use that port within the pod while it is in use. Contain‐
978       ers in the pod can also communicate over localhost by having  one  con‐
979       tainer bind to localhost in the pod, and another connect to that port.
980
981
982   --publish-all, -P=true|false
983       Publish  all  exposed ports to random ports on the host interfaces. The
984       default is false.
985
986
987       When set to true publish all exposed ports to the host interfaces.  The
988       default is false. If the operator uses -P (or -p) then Podman will make
989       the exposed port accessible on the host and the ports will be available
990       to  any client that can reach the host. When using -P, Podman will bind
991       any exposed port to a random port on the host within an ephemeral  port
992       range  defined  by  /proc/sys/net/ipv4/ip_local_port_range. To find the
993       mapping between the host ports and the exposed ports, use podman port.
994
995
996   --pull=missing
997       Pull image before creating ("always"|"missing"|"never") (default "miss‐
998       ing").
999              'missing':  default value, attempt to pull the latest image from
1000       the registries listed in registries.conf if a local image does not  ex‐
1001       ist.Raise  an  error  if the image is not in any listed registry and is
1002       not present locally.
1003              'always': Pull the image from the first registry it is found  in
1004       as  listed in  registries.conf. Raise an error if not found in the reg‐
1005       istries, even if the image is present locally.
1006              'never': do not pull the image from the registry, use  only  the
1007       local version. Raise an error if the image is not present locally.
1008
1009
1010       Defaults to missing.
1011
1012
1013   --quiet, -q
1014       Suppress output information when pulling images
1015
1016
1017   --read-only=true|false
1018       Mount the container's root filesystem as read only.
1019
1020
1021       By  default a container will have its root filesystem writable allowing
1022       processes to write files anywhere. By specifying the  --read-only  flag
1023       the  container  will have its root filesystem mounted as read only pro‐
1024       hibiting any writes.
1025
1026
1027   --read-only-tmpfs=true|false
1028       If container is running in --read-only mode, then  mount  a  read-write
1029       tmpfs on /run, /tmp, and /var/tmp. The default is true
1030
1031
1032   --replace=true|false
1033       If another container with the same name already exists, replace and re‐
1034       move it. The default is false.
1035
1036
1037   --requires=container
1038       Specify one or more requirements.  A requirement is a  dependency  con‐
1039       tainer  that  will be started before this container.  Containers can be
1040       specified by name or ID, with multiple containers  being  separated  by
1041       commas.
1042
1043
1044   --restart=policy
1045       Restart policy to follow when containers exit.  Restart policy will not
1046       take effect if a container is stopped via the  podman  kill  or  podman
1047       stop commands.
1048
1049
1050       Valid values are:
1051
1052
1053no                       : Do not restart containers on exit
1054
1055on-failure[:max_retries]  :  Restart containers when they exit
1056                with a non-0 exit code, retrying indefinitely or until the op‐
1057                tional max_retries count is hit
1058
1059always                    : Restart containers when they exit,
1060                regardless of status, retrying indefinitely
1061
1062unless-stopped           : Identical to always
1063
1064
1065
1066       Please note that restart will not restart containers after a system re‐
1067       boot.   If  this functionality is required in your environment, you can
1068       invoke Podman from a systemd unit file, or create an  init  script  for
1069       whichever  init  system  is  in  use.   To generate systemd unit files,
1070       please see podman generate systemd
1071
1072
1073   --rm=true|false
1074       Automatically remove the container when it exits. The default is false.
1075
1076
1077   --rootfs
1078       If specified, the first argument refers to an exploded container on the
1079       file system.
1080
1081
1082       This  is  useful to run a container without requiring any image manage‐
1083       ment, the rootfs of the container is assumed to be managed externally.
1084
1085
1086   --sdnotify=container|conmon|ignore
1087       Determines how to use the NOTIFY_SOCKET, as  passed  with  systemd  and
1088       Type=notify.
1089
1090
1091       Default  is  container,  which means allow the OCI runtime to proxy the
1092       socket into the container to receive ready  notification.  Podman  will
1093       set  the  MAINPID  to  conmon's pid.  The conmon option sets MAINPID to
1094       conmon's pid, and sends READY  when  the  container  has  started.  The
1095       socket is never passed to the runtime or the container.  The ignore op‐
1096       tion removes NOTIFY_SOCKET from the environment for  itself  and  child
1097       processes,  for the case where some other process above Podman uses NO‐
1098       TIFY_SOCKET and Podman should not use it.
1099
1100
1101   --seccomp-policy=policy
1102       Specify the policy to select the seccomp profile. If set to image, Pod‐
1103       man  will  look for a "io.containers.seccomp.profile" label in the con‐
1104       tainer-image config and use its value as a seccomp profile.  Otherwise,
1105       Podman  will  follow the default policy by applying the default profile
1106       unless specified otherwise via --security-opt seccomp as described  be‐
1107       low.
1108
1109
1110       Note that this feature is experimental and may change in the future.
1111
1112
1113   --secret=secret[,opt=opt ...]
1114       Give the container access to a secret. Can be specified multiple times.
1115
1116
1117       A secret is a blob of sensitive data which a container needs at runtime
1118       but should not be stored in the image or in  source  control,  such  as
1119       usernames  and  passwords, TLS certificates and keys, SSH keys or other
1120       important generic strings or binary content (up to 500 kb in size).
1121
1122
1123       When secrets are specified as type mount, the secrets  are  copied  and
1124       mounted  into  the container when a container is created.  When secrets
1125       are specified as type env, the secret will be  set  as  an  environment
1126       variable within the container.  Secrets are written in the container at
1127       the time of container creation, and modifying the secret  using  podman
1128       secret  commands after the container is created will not affect the se‐
1129       cret inside the container.
1130
1131
1132       Secrets and its storage are managed using the podman secret command.
1133
1134
1135       Secret Options
1136
1137
1138type=mount|env    : How the secret will be exposed to the con‐
1139                tainer. Default mount.
1140
1141target=target     : Target of secret. Defauts to secret name.
1142
1143
1144
1145   --security-opt=option
1146       Security Options
1147
1148
1149apparmor=unconfined  :  Turn  off apparmor confinement for the
1150                container
1151
1152apparmor=your-profile : Set the apparmor  confinement  profile
1153                for the container
1154
1155label=user:USER      :  Set  the  label user for the container
1156                processes
1157
1158label=role:ROLE     : Set the label  role  for  the  container
1159                processes
1160
1161label=type:TYPE      : Set the label process type for the con‐
1162                tainer processes
1163
1164label=level:LEVEL   : Set the label level  for  the  container
1165                processes
1166
1167label=filetype:TYPE  :  Set  the  label file type for the con‐
1168                tainer files
1169
1170label=disable       : Turn off label separation for  the  con‐
1171                tainer
1172
1173
1174
1175       Note:  Labeling  can  be  disabled  for  all  containers by setting la‐
1176       bel=false in the  containers.conf  (/etc/containers/containers.conf  or
1177       $HOME/.config/containers/containers.conf) file.
1178
1179
1180mask=/path/1:/path/2 : The paths to mask separated by a colon.
1181                A masked path cannot be accessed inside the container.
1182
1183no-new-privileges : Disable container processes  from  gaining
1184                additional privileges
1185
1186seccomp=unconfined : Turn off seccomp confinement for the con‐
1187                tainer
1188
1189seccomp=profile.json :  White  listed  syscalls  seccomp  Json
1190                file to be used as a seccomp filter
1191
1192proc-opts=OPTIONS : Comma-separated list of options to use for
1193                the /proc mount. More details for the possible  mount  options
1194                are specified in the proc(5) man page.
1195
1196unmask=ALL   or   /path/1:/path/2,  or  shell  expanded  paths
1197                (/proc/*): Paths to unmask separated by a  colon.  If  set  to
1198                ALL, it will unmask all the paths that are masked or made read
1199                only by default.  The default  masked  paths  are  /proc/acpi,
1200                /proc/kcore,  /proc/keys, /proc/latency_stats, /proc/sched_de‐
1201                bug,    /proc/scsi,    /proc/timer_list,    /proc/timer_stats,
1202                /sys/firmware,  and  /sys/fs/selinux.   The default paths that
1203                are  read  only   are   /proc/asound,   /proc/bus,   /proc/fs,
1204                /proc/irq, /proc/sys, /proc/sysrq-trigger, /sys/fs/cgroup.
1205
1206
1207
1208       Note:  Labeling  can  be  disabled  for  all  containers by setting la‐
1209       bel=false in the  containers.conf  (/etc/containers/containers.conf  or
1210       $HOME/.config/containers/containers.conf) file.
1211
1212
1213   --shm-size=size
1214       Size  of  /dev/shm (format: <number>[<unit>], where unit = b (bytes), k
1215       (kilobytes), m (megabytes), or g (gigabytes)) If you omit the unit, the
1216       system  uses bytes. If you omit the size entirely, the system uses 64m.
1217       When size is 0, there is no limit on the amount of memory used for  IPC
1218       by the container.
1219
1220
1221   --stop-signal=SIGTERM
1222       Signal to stop a container. Default is SIGTERM.
1223
1224
1225   --stop-timeout=seconds
1226       Timeout  (in  seconds) to stop a container. Default is 10.  Remote con‐
1227       nections use local containers.conf for defaults
1228
1229
1230   --subgidname=name
1231       Name for GID map from the /etc/subgid file. Using this  flag  will  run
1232       the  container  with  user  namespace enabled. This flag conflicts with
1233       --userns and --gidmap.
1234
1235
1236   --subuidname=name
1237       Name for UID map from the /etc/subuid file. Using this  flag  will  run
1238       the  container  with  user  namespace enabled. This flag conflicts with
1239       --userns and --uidmap.
1240
1241
1242   --sysctl=SYSCTL
1243       Configure namespaced kernel parameters at runtime
1244
1245
1246       IPC Namespace - current sysctls allowed:
1247
1248
1249       kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall,
1250       kernel.shmmax,  kernel.shmmni, kernel.shm_rmid_forced Sysctls beginning
1251       with fs.mqueue.*
1252
1253
1254       Note: if you use the --ipc=host option these sysctls will  not  be  al‐
1255       lowed.
1256
1257
1258       Network Namespace - current sysctls allowed:
1259           Sysctls beginning with net.*
1260
1261
1262       Note:  if  you  use the --network=host option these sysctls will not be
1263       allowed.
1264
1265
1266   --systemd=true|false|always
1267       Run container in systemd mode. The default is true.
1268
1269
1270       The value always enforces the systemd mode is enforced without  looking
1271       at  the  executable name. Otherwise, if set to true and the command you
1272       are running inside the container is systemd, /usr/sbin/init, /sbin/init
1273       or /usr/local/sbin/init.
1274
1275
1276       If the command you are running inside of the container is systemd, Pod‐
1277       man will setup tmpfs mount points in the following directories:
1278
1279
1280       /run, /run/lock, /tmp, /sys/fs/cgroup/systemd, /var/lib/journal
1281
1282
1283       It will also set the default stop signal to SIGRTMIN+3.
1284
1285
1286       This allow systemd to run in a confined container without any modifica‐
1287       tions.
1288
1289
1290       Note:  On SELinux systems, systemd attempts to write to the cgroup file
1291       system. Containers writing to the cgroup file system are denied by  de‐
1292       fault.  The container_manage_cgroup boolean must be enabled for this to
1293       be allowed on an SELinux separated system.
1294
1295
1296       setsebool -P container_manage_cgroup true
1297
1298
1299   --timeout=seconds
1300       Maximum time a container is allowed to run before conmon sends  it  the
1301       kill  signal.   By  default  containers will run until they exit or are
1302       stopped by podman stop.
1303
1304
1305   --tmpfs=fs
1306       Create a tmpfs mount
1307
1308
1309       Mount a temporary filesystem (tmpfs) mount into a container, for  exam‐
1310       ple:
1311
1312
1313       $ podman create -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image
1314
1315
1316       This command mounts a tmpfs at /tmp within the container. The supported
1317       mount options are the same as the Linux default mount flags. If you  do
1318       not  specify  any  options,  the  systems  uses  the following options:
1319       rw,noexec,nosuid,nodev.
1320
1321
1322   --tty, -t=true|false
1323       Allocate a pseudo-TTY. The default is false.
1324
1325
1326       When set to true Podman will allocate a pseudo-tty and  attach  to  the
1327       standard  input of the container. This can be used, for example, to run
1328       a throwaway interactive shell. The default is false.
1329
1330
1331       Note: The -t option is incompatible with a redirection  of  the  Podman
1332       client standard input.
1333
1334
1335   --tz=timezone
1336       Set  timezone  in  container. This flag takes area-based timezones, GMT
1337       time, as well as local, which sets the timezone  in  the  container  to
1338       match  the  host machine. See /usr/share/zoneinfo/ for valid timezones.
1339       Remote connections use local containers.conf for defaults
1340
1341
1342   --umask=umask
1343       Set the umask inside the container. Defaults to 0022.   Remote  connec‐
1344       tions use local containers.conf for defaults
1345
1346
1347   --uidmap=container_uid:from_uid:amount
1348       Run  the  container in a new user namespace using the supplied mapping.
1349       This option conflicts with the --userns and --subuidname options.  This
1350       option  provides  a  way  to map host UIDs to container UIDs. It can be
1351       passed several times to map different ranges.
1352
1353
1354       The _fromuid value is based upon the user running the  command,  either
1355       rootfull    or    rootless    users.     *    rootfull    user:    con‐
1356       tainer_uid:host_uid:amount *  rootless  user:  container_uid:intermedi‐
1357       ate_uid:amount
1358
1359
1360       When  podman create is called by a privileged user, the option --uidmap
1361       works as a direct mapping between host UIDs and container UIDs.
1362
1363
1364       host UID -> container UID
1365
1366
1367       The amount specifies the  number  of  consecutive  UIDs  that  will  be
1368       mapped.  If for example amount is 4 the mapping would look like:
1369
1370
1371       |    host  UID      |     container  UID     |  |  -               |  -
1372       | | _fromuid     | _containeruid     | | _fromuid + 1 | _containeruid +
1373       1 | | _fromuid + 2 | _containeruid + 2 | | _fromuid + 3 | _containeruid
1374       + 3 |
1375
1376
1377       When podman create is called by  an  unprivileged  user  (i.e.  running
1378       rootless),  the value _fromuid is interpreted as an "intermediate UID".
1379       In the rootless case, host UIDs are not mapped  directly  to  container
1380       UIDs. Instead the mapping happens over two mapping steps:
1381
1382
1383       host UID -> intermediate UID -> container UID
1384
1385
1386       The --uidmap option only influences the second mapping step.
1387
1388
1389       The  first  mapping  step is derived by Podman from the contents of the
1390       file /etc/subuid and the UID of the user calling Podman.
1391
1392
1393       First mapping step:
1394
1395
1396       | host UID                                         | intermediate UID |
1397       | -                                                |                - |
1398       | UID for the user starting Podman                 |                0 |
1399       | 1st subordinate UID for the user starting Podman |                1 |
1400       | 2nd subordinate UID for the user starting Podman |                2 |
1401       | 3rd subordinate UID for the user starting Podman |                3 |
1402       | nth subordinate UID for the user starting Podman |                n |
1403
1404
1405       To be able to use intermediate UIDs greater than zero, the  user  needs
1406       to have subordinate UIDs configured in /etc/subuid. See subuid(5).
1407
1408
1409       The second mapping step is configured with --uidmap.
1410
1411
1412       If for example amount is 5 the second mapping step would look like:
1413
1414
1415       |   intermediate UID   |    container UID    | | -                    |
1416       -                   | |  _fromuid            |  _containeruid      |  |
1417       _fromuid  +  1       | _containeruid + 1 | | _fromuid + 2       | _con‐
1418       taineruid + 2 | | _fromuid + 3       | _containeruid + 3 | | _fromuid +
1419       4       | _containeruid + 4 |
1420
1421
1422       Even  if  a  user  does  not have any subordinate UIDs in  /etc/subuid,
1423       --uidmap could still be used to map the normal UID of  the  user  to  a
1424       container  UID  by  running  podman  create --uidmap $container_uid:0:1
1425       --user $container_uid ....
1426
1427
1428   --ulimit=option
1429       Ulimit options
1430
1431
1432       You can pass host to copy the current configuration from the host.
1433
1434
1435   --user, -u=user
1436       Sets the username or UID used and optionally the groupname or  GID  for
1437       the specified command.
1438
1439
1440       The following examples are all valid: --user [user | user:group | uid |
1441       uid:gid | user:gid | uid:group ]
1442
1443
1444       Without this argument the command will be run as root in the container.
1445
1446
1447   --userns=mode
1448       Set the user namespace mode for the container. It defaults to the  POD‐
1449       MAN_USERNS  environment  variable. An empty value ("") means user name‐
1450       spaces are disabled unless an explicit mapping is set with the --uidmap
1451       and --gidmap options.
1452
1453
1454       Valid mode values are:
1455
1456
1457auto[:OPTIONS,...]:  automatically  create  a namespace. It is
1458                possible to specify these options to auto:
1459
1460gidmapping=_HOST_GID:CONTAINERGID:SIZE: to force a GID  map‐
1461                  ping to be present in the user namespace.
1462
1463size=SIZE:  to  specify  an  explicit size for the automatic
1464                  user namespace. e.g. --userns=auto:size=8192. If size is not
1465                  specified, auto will estimate a size for the user namespace.
1466
1467uidmapping=_HOST_UID:CONTAINERUID:SIZE:  to force a UID map‐
1468                  ping to be present in the user namespace.
1469
1470
1471
1472container:id: join the user namespace of  the  specified  con‐
1473                tainer.
1474
1475host:  run  in the user namespace of the caller. The processes
1476                running in the container will have the same privileges on  the
1477                host  as  any  other process launched by the calling user (de‐
1478                fault).
1479
1480keep-id: creates a user namespace where the  current  rootless
1481                user's UID:GID are mapped to the same values in the container.
1482                This option is ignored for  containers  created  by  the  root
1483                user.
1484
1485ns:namespace:  run  the  container  in the given existing user
1486                namespace.
1487
1488private: create a new namespace for the container.
1489
1490
1491
1492       This option is incompatible with --gidmap, --uidmap,  --subuidname  and
1493       --subgidname.
1494
1495
1496   --uts=mode
1497       Set  the UTS namespace mode for the container. The following values are
1498       supported:
1499
1500
1501host: use the host's UTS namespace inside the container.
1502
1503private: create a new namespace for the container (default).
1504
1505ns:[path]: run the container in the given existing  UTS  name‐
1506                space.
1507
1508container:[container]: join the UTS namespace of the specified
1509                container.
1510
1511
1512
1513   --variant=VARIANT
1514       Use VARIANT instead of the default architecture  variant  of  the  con‐
1515       tainer  image.  Some images can use multiple variants of the arm archi‐
1516       tectures, such as arm/v5 and arm/v7.
1517
1518
1519   --volume, -v[=[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]]
1520       Create a bind mount. If you specify, -v /HOST-DIR:/CONTAINER-DIR,  Pod‐
1521       man  bind  mounts /HOST-DIR in the host to /CONTAINER-DIR in the Podman
1522       container. Similarly, -v SOURCE-VOLUME:/CONTAINER-DIR  will  mount  the
1523       volume  in  the  host to the container. If no such named volume exists,
1524       Podman will create one. The OPTIONS are a comma-separated list and  can
1525       be:  [1]  ⟨#Footnote1⟩  (Note when using the remote client, the volumes
1526       will be mounted from the remote server, not necessarily the client  ma‐
1527       chine.)
1528
1529
1530       The options is a comma-separated list and can be:
1531
1532
1533rw|ro
1534
1535z|Z
1536
1537              • [r]shared|[r]slave|[r]private[r]unbindable
1538
1539              • [r]bind
1540
1541              • [no]exec
1542
1543              • [no]dev
1544
1545              • [no]suid
1546
1547              • [O]
1548
1549              • [U]
1550
1551
1552
1553       The  CONTAINER-DIR must be an absolute path such as /src/docs. The vol‐
1554       ume will be mounted into the container at this directory.
1555
1556
1557       Volumes may specify a source as well, as either a directory on the host
1558       or  the  name of a named volume. If no source is given, the volume will
1559       be created as an anonymously named volume  with  a  randomly  generated
1560       name,  and  will  be removed when the container is removed via the --rm
1561       flag or podman rm --volumes.
1562
1563
1564       If a volume source is specified, it must be a path on the host  or  the
1565       name  of a named volume. Host paths are allowed to be absolute or rela‐
1566       tive; relative paths are resolved relative to the directory  Podman  is
1567       run  in.  If  the  source  does not exist, Podman will return an error.
1568       Users must pre-create the source files or directories.
1569
1570
1571       Any source that does not begin with a . or / will  be  treated  as  the
1572       name  of  a named volume. If a volume with that name does not exist, it
1573       will be created.  Volumes created with names  are  not  anonymous,  and
1574       they  are  not  removed  by the --rm option and the podman rm --volumes
1575       command.
1576
1577
1578       You can specify multiple  -v options to mount one or more volumes  into
1579       a container.
1580
1581
1582       Write Protected Volume Mounts
1583
1584
1585       You  can  add  :ro  or  :rw suffix to a volume to mount it read-only or
1586       read-write mode, respectively. By  default,  the  volumes  are  mounted
1587       read-write.  See examples.
1588
1589
1590       Chowning Volume Mounts
1591
1592
1593       By default, Podman does not change the owner and group of source volume
1594       directories mounted into containers. If a container is created in a new
1595       user  namespace, the UID and GID in the container may correspond to an‐
1596       other UID and GID on the host.
1597
1598
1599       The :U suffix tells Podman to use the correct host UID and GID based on
1600       the  UID  and GID within the container, to change recursively the owner
1601       and group of the source volume.
1602
1603
1604       Warning use with caution since this will modify the host filesystem.
1605
1606
1607       Labeling Volume Mounts
1608
1609
1610       Labeling systems like SELinux require that proper labels are placed  on
1611       volume  content mounted into a container. Without a label, the security
1612       system might prevent the processes running inside  the  container  from
1613       using the content. By default, Podman does not change the labels set by
1614       the OS.
1615
1616
1617       To change a label in the container context, you can add either  of  two
1618       suffixes  :z  or  :Z to the volume mount. These suffixes tell Podman to
1619       relabel file objects on the shared volumes. The z option  tells  Podman
1620       that  two  containers share the volume content. As a result, Podman la‐
1621       bels the content with a shared content label. Shared volume labels  al‐
1622       low all containers to read/write content.  The Z option tells Podman to
1623       label the content with a private unshared label.  Only the current con‐
1624       tainer can use a private volume.
1625
1626
1627       Overlay Volume Mounts
1628
1629
1630       The :O flag tells Podman to mount the directory from the host as a tem‐
1631       porary storage using the overlay file system. The  container  processes
1632       can  modify  content  within the mountpoint which is stored in the con‐
1633       tainer storage in a separate directory. In overlay  terms,  the  source
1634       directory  will  be the lower, and the container storage directory will
1635       be the upper. Modifications to the mount point are destroyed  when  the
1636       container  finishes executing, similar to a tmpfs mount point being un‐
1637       mounted.
1638
1639
1640       Subsequent executions of the container will see the original source di‐
1641       rectory  content,  any  changes  from  previous container executions no
1642       longer exist.
1643
1644
1645       One use case of the overlay mount is sharing the package cache from the
1646       host into the container to allow speeding up builds.
1647
1648
1649       Note:
1650
1651
1652               - The `O` flag conflicts with other options listed above.
1653
1654
1655
1656       Content mounted into the container is labeled with the private label.
1657              On SELinux systems, labels in the source directory must be read‐
1658       able by the container label. Usually containers can  read/execute  con‐
1659       tainer_share_t  and  can  read/write  container_file_t.  If  you cannot
1660       change the labels on a source volume, SELinux container separation must
1661       be disabled for the container to work.
1662            -  The source directory mounted into the container with an overlay
1663       mount should not be modified, it can cause unexpected failures.  It  is
1664       recommended  that  you  do not modify the directory until the container
1665       finishes running.
1666
1667
1668       Mounts propagation
1669
1670
1671       By default bind mounted volumes are private. That means any mounts done
1672       inside  container  will  not be visible on host and vice versa. One can
1673       change this behavior by specifying a volume mount propagation property.
1674       Making  a  volume shared mounts done under that volume inside container
1675       will be visible on host and vice versa. Making a volume  slave  enables
1676       only  one  way  mount propagation and that is mounts done on host under
1677       that volume will be visible inside container  but  not  the  other  way
1678       around. [1] ⟨#Footnote1⟩
1679
1680
1681       To  control  mount  propagation  property  of  a volume one can use the
1682       [r]shared, [r]slave, [r]private or the [r]unbindable propagation  flag.
1683       Propagation property can be specified only for bind mounted volumes and
1684       not for internal volumes or named volumes.  For  mount  propagation  to
1685       work  the  source  mount  point  (the  mount  point where source dir is
1686       mounted on) has to have the right propagation  properties.  For  shared
1687       volumes,  the  source  mount point has to be shared. And for slave vol‐
1688       umes, the source mount point has to be either  shared  or  slave.   [1]
1689       ⟨#Footnote1⟩
1690
1691
1692       If you want to recursively mount a volume and all of its submounts into
1693       a container, then you can use the rbind option. By default the bind op‐
1694       tion is used, and submounts of the source directory will not be mounted
1695       into the container.
1696
1697
1698       Mounting the volume with the nosuid options means  that  SUID  applica‐
1699       tions  on the volume will not be able to change their privilege. By de‐
1700       fault volumes are mounted with nosuid.
1701
1702
1703       Mounting the volume with the noexec option means that no executables on
1704       the volume will be able to executed within the container.
1705
1706
1707       Mounting  the volume with the nodev option means that no devices on the
1708       volume will be able to be used by processes within  the  container.  By
1709       default volumes are mounted with nodev.
1710
1711
1712       If  the  <source-dir>  is a mount point, then "dev", "suid", and "exec"
1713       options are ignored by the kernel.
1714
1715
1716       Use df <source-dir> to figure out the source mount and then use findmnt
1717       -o  TARGET,PROPAGATION  <source-mount-dir>  to  figure  out propagation
1718       properties of source mount. If findmnt utility is not  available,  then
1719       one   can   look   at   mount   entry   for   source   mount  point  in
1720       /proc/self/mountinfo. Look at optional fields and see if  any  propaga‐
1721       tion  properties  are  specified.  shared:X means mount is shared, mas‐
1722       ter:X means mount is slave and if nothing is there that means mount  is
1723       private. [1] ⟨#Footnote1⟩
1724
1725
1726       To  change  propagation  properties of a mount point use mount command.
1727       For example, if one wants to bind mount source directory /foo  one  can
1728       do  mount --bind /foo /foo and mount --make-private --make-shared /foo.
1729       This will convert /foo into a shared mount point. Alternatively one can
1730       directly change propagation properties of source mount. Say / is source
1731       mount for /foo, then use mount --make-shared /  to  convert  /  into  a
1732       shared mount.
1733
1734
1735       Note:  if  the  user  only has access rights via a group, accessing the
1736       volume from inside a rootless container will fail. Use the  --group-add
1737       keep-groups flag to pass the user's supplementary group access into the
1738       container.
1739
1740
1741   --volumes-from[=CONTAINER[:OPTIONS]]
1742       Mount volumes from the specified container(s). Used  to  share  volumes
1743       between containers. The options is a comma-separated list with the fol‐
1744       lowing available elements:
1745
1746
1747rw|ro
1748
1749z
1750
1751
1752
1753       Mounts already mounted volumes from a  source  container  onto  another
1754       container. You must supply the source's container-id or container-name.
1755       To share a volume, use the --volumes-from option when running the  tar‐
1756       get  container.  You  can share volumes even if the source container is
1757       not running.
1758
1759
1760       By default, Podman mounts the volumes in the same mode  (read-write  or
1761       read-only)  as  it  is mounted in the source container.  You can change
1762       this by adding a ro or rw option.
1763
1764
1765       Labeling systems like SELinux require that proper labels are placed  on
1766       volume  content mounted into a container. Without a label, the security
1767       system might prevent the processes running inside  the  container  from
1768       using the content. By default, Podman does not change the labels set by
1769       the OS.
1770
1771
1772       To change a label in the container context, you can add z to the volume
1773       mount.   This suffix tells Podman to relabel file objects on the shared
1774       volumes. The z option tells Podman that two containers share the volume
1775       content.  As  a result, Podman labels the content with a shared content
1776       label. Shared volume labels allow all containers to read/write content.
1777
1778
1779       If the location of the volume from the source container  overlaps  with
1780       data residing on a target container, then the volume hides that data on
1781       the target.
1782
1783
1784   --workdir, -w=dir
1785       Working directory inside the container
1786
1787
1788       The default working directory for running binaries within  a  container
1789       is the root directory (/).  The image developer can set a different de‐
1790       fault with the WORKDIR instruction. The operator can override the work‐
1791       ing directory by using the -w option.
1792
1793
1794   --pidfile=path
1795       When the pidfile location is specified, the container process' PID will
1796       be written to the pidfile. (This option is not available with  the  re‐
1797       mote  Podman  client)  If the pidfile option is not specified, the con‐
1798       tainer process' PID will be written to  /run/containers/storage/${stor‐
1799       age-driver}-containers/$CID/userdata/pidfile.
1800
1801
1802       After  the  container  is  started, the location for the pidfile can be
1803       discovered with the following podman inspect command:
1804
1805
1806              $ podman inspect --format '{{ .PidFile }}' $CID
1807              /run/containers/storage/${storage-driver}-containers/$CID/userdata/pidfile
1808
1809
1810

EXAMPLES

1812   Create a container using a local image
1813              $ podman create alpine ls
1814
1815
1816
1817   Create a container using a local image and annotate it
1818              $ podman create --annotation HELLO=WORLD alpine ls
1819
1820
1821
1822   Create a container using a local image, allocating  a  pseudo-TTY,  keeping
1823       stdin open and name it myctr
1824                podman create -t -i --name myctr alpine ls
1825
1826
1827
1828   Set UID/GID mapping in a new user namespace
1829       Running  a  container in a new user namespace requires a mapping of the
1830       uids and gids from the host.
1831
1832
1833              $ podman create --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello
1834
1835
1836
1837   Configure timezone in a container
1838              $ podman create --tz=local alpine date
1839              $ podman create --tz=Asia/Shanghai alpine date
1840              $ podman create --tz=US/Eastern alpine date
1841
1842
1843
1844   Adding dependency containers
1845       Podman will make sure the first container, container1, is  running  be‐
1846       fore the second container (container2) is started.
1847
1848
1849              $ podman create --name container1 -t -i fedora bash
1850              $ podman create --name container2 --requires container1 -t -i fedora bash
1851              $ podman start --attach container2
1852
1853
1854
1855       Multiple containers can be required.
1856
1857
1858              $ podman create --name container1 -t -i fedora bash
1859              $ podman create --name container2 -t -i fedora bash
1860              $ podman create --name container3 --requires container1,container2 -t -i fedora bash
1861              $ podman start --attach container3
1862
1863
1864
1865   Configure keep supplemental groups for access to volume
1866              $ podman create -v /var/lib/design:/var/lib/design --group-add keep-groups ubi8
1867
1868
1869
1870   Rootless Containers
1871       Podman  runs  as a non root user on most systems. This feature requires
1872       that  a  new  enough  version  of  shadow-utils   be   installed.   The
1873       shadow-utils  package must include the newuidmap and newgidmap executa‐
1874       bles.
1875
1876
1877       Note: RHEL7 and Centos 7 will not have this feature  until  RHEL7.7  is
1878       released.
1879
1880
1881       In  order  for  users to run rootless, there must be an entry for their
1882       username in /etc/subuid and /etc/subgid which lists the UIDs for  their
1883       user namespace.
1884
1885
1886       Rootless  Podman  works  better  if  the fuse-overlayfs and slirp4netns
1887       packages are installed.  The fuse-overlay package provides a  userspace
1888       overlay  storage  driver,  otherwise  users need to use the vfs storage
1889       driver, which  is  diskspace  expensive  and  does  not  perform  well.
1890       slirp4netns  is  required for VPN, without it containers need to be run
1891       with the --network=host flag.
1892
1893

ENVIRONMENT

1895       Environment variables within containers can be set using multiple  dif‐
1896       ferent options:  This section describes the precedence.
1897
1898
1899       Precedence order (later entries override earlier entries):
1900
1901
1902--env-host  : Host environment of the process executing Podman
1903                is added.
1904
1905--http-proxy: By default, several environment  variables  will
1906                be  passed  in from the host, such as http_proxy and no_proxy.
1907                See --http-proxy for details.
1908
1909              • Container image : Any environment variables specified  in  the
1910                container image.
1911
1912--env-file   :   Any   environment   variables  specified  via
1913                env-files. If multiple files  specified,  then  they  override
1914                each other in order of entry.
1915
1916--env : Any environment variables specified will override pre‐
1917                vious settings.
1918
1919
1920
1921       Create containers and set the environment ending with a * and a *****
1922
1923
1924              $ export ENV1=a
1925              $ podman create --name ctr --env ENV* alpine printenv ENV1
1926              $ podman start --attach ctr
1927              a
1928
1929              $ podman create --name ctr --env ENV*****=b alpine printenv ENV*****
1930              $ podman start --attach ctr
1931              b
1932
1933
1934

CONMON

1936       When Podman starts a container it actually executes the conmon program,
1937       which  then executes the OCI Runtime.  Conmon is the container monitor.
1938       It is a small program whose job is to watch the primary process of  the
1939       container,  and  if  the  container  dies, save the exit code.  It also
1940       holds open the tty of the container, so that  it  can  be  attached  to
1941       later.  This  is  what  allows  Podman  to  run in detached mode (back‐
1942       grounded), so Podman can exit but conmon continues to run.   Each  con‐
1943       tainer has their own instance of conmon. Conmon waits for the container
1944       to exit, gathers and saves the exit code, and then  launches  a  Podman
1945       process to complete the container cleanup, by shutting down the network
1946       and storage.   For more information on  conmon,  please  reference  the
1947       conmon(8) man page.
1948
1949

FILES

1951       /etc/subuid /etc/subgid
1952
1953
1954       NOTE: Use the environment variable TMPDIR to change the temporary stor‐
1955       age location of downloaded container images.  Podman  defaults  to  use
1956       /var/tmp.
1957
1958

SEE ALSO

1960       podman(1),  podman-secret(1),  podman-save(1), podman-ps(1), podman-at‐
1961       tach(1), podman-pod-create(1), podman-port(1),  *podman-start(1),  pod‐
1962       man-kill(1),  podman-stop(1),  podman-generate-systemd(1) podman-rm(1),
1963       subgid(5),  subuid(5),  containers.conf(5),   systemd.unit(5),   setse‐
1964       bool(8), slirp4netns(1), fuse-overlayfs(1), proc(5), conmon(8).
1965
1966

HISTORY

1968       October  2017,  converted  from  Docker  documentation to Podman by Dan
1969       Walsh for Podman <dwalsh@redhat.com>
1970
1971
1972       November 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
1973
1974
1975       September 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
1976
1977
1978       August 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
1979
1980

FOOTNOTES

1982       1: The Podman project is committed to inclusivity, a core value of open
1983       source. The master and slave mount propagation terminology used here is
1984       problematic and divisive, and should be changed. However,  these  terms
1985       are  currently  used  within the Linux kernel and must be used as-is at
1986       this time. When the kernel maintainers rectify this usage, Podman  will
1987       follow suit immediately.
1988
1989
1990
1991                                                            podman-create(1)()
Impressum