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

NAME

6       podman-pod-create - Create a new pod
7
8

SYNOPSIS

10       podman pod create [options] [name]
11
12

DESCRIPTION

14       Creates  an  empty pod, or unit of multiple containers, and prepares it
15       to have containers added to it. The pod can be created with a  specific
16       name.  If a name is not given a random name is generated. The pod id is
17       printed  to  STDOUT.   You   can   then   use   podman   create   --pod
18       <pod_id|pod_name>  ...  to  add  containers  to the pod, and podman pod
19       start <pod_id|pod_name> to start the pod.
20
21
22       The operator can identify a pod in three  ways:  UUID  long  identifier
23       (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”)
24       UUID short identifier (“f78375b1c487”) Name (“jonah”)
25
26
27       podman generates a UUID for each pod, and if a name is not assigned  to
28       the  container  with --name then a random string name will be generated
29       for it. The name is useful any place you need to identify a pod.
30
31
32       Note: resource limit related flags work by setting the  limits  explic‐
33       itly in the pod's cgroup which by default, is the cgroup parent for all
34       containers joining the pod. Containers are still delegated the  ability
35       to set their own resource limits when joining a pod meaning that if you
36       run podman pod create --cpus=5 you can also run podman container create
37       --pod=<pod_id|pod_name>  --cpus=4  and  the container will only see the
38       smaller limit. containers do NOT get the pod level cgroup resources  if
39       they   specify   their   own   cgroup   when  joining  a  pod  such  as
40       --cgroupns=host
41
42

OPTIONS

44   --add-host=host:ip
45       Add a custom host-to-IP mapping (host:ip)
46
47
48       Add a line to /etc/hosts. The format is hostname:ip. The --add-host op‐
49       tion can be set multiple times. Conflicts with the --no-hosts option.
50
51
52       The /etc/hosts file is shared between all containers in the pod.
53
54
55   --blkio-weight=weight
56       Block IO relative weight. The weight is a value between 10 and 1000.
57
58
59       This option is not supported on cgroups V1 rootless systems.
60
61
62   --blkio-weight-device=device:weight
63       Block IO relative device weight.
64
65
66   --cgroup-parent=path
67       Path  to cgroups under which the cgroup for the pod will be created. If
68       the path is not absolute, the path is considered to be relative to  the
69       cgroups  path  of  the init process. Cgroups will be created if they do
70       not already exist.
71
72
73   --cpu-shares, -c=shares
74       CPU shares (relative weight).
75
76
77       By default, all containers get the same proportion of CPU cycles.  This
78       proportion  can  be  modified  by  changing  the  container's CPU share
79       weighting relative to the combined weight of all the  running  contain‐
80       ers.  Default weight is 1024.
81
82
83       The  proportion  will  only apply when CPU-intensive processes are run‐
84       ning.  When tasks in one container are idle, other containers  can  use
85       the left-over CPU time. The actual amount of CPU time will vary depend‐
86       ing on the number of containers running on the system.
87
88
89       For example, consider three containers, one has a cpu-share of 1024 and
90       two others have a cpu-share setting of 512. When processes in all three
91       containers attempt to use 100% of CPU, the first  container  would  re‐
92       ceive  50% of the total CPU time. If a fourth container is added with a
93       cpu-share of 1024, the first container only gets 33% of  the  CPU.  The
94       remaining containers receive 16.5%, 16.5% and 33% of the CPU.
95
96
97       On a multi-core system, the shares of CPU time are distributed over all
98       CPU cores. Even if a container is limited to  less  than  100%  of  CPU
99       time, it can use 100% of each individual CPU core.
100
101
102       For example, consider a system with more than three cores.  If the con‐
103       tainer C0 is started with --cpu-shares=512 running one process, and an‐
104       other  container  C1 with --cpu-shares=1024 running two processes, this
105       can result in the following division of CPU shares:
106
107
108       ┌────┬───────────┬─────┬──────────────┐
109PID container CPU CPU share    
110       ├────┼───────────┼─────┼──────────────┤
111       │100 │ C0        │ 0   │ 100% of CPU0 │
112       ├────┼───────────┼─────┼──────────────┤
113       │101 │ C1        │ 1   │ 100% of CPU1 │
114       ├────┼───────────┼─────┼──────────────┤
115       │102 │ C1        │ 2   │ 100% of CPU2 │
116       └────┴───────────┴─────┴──────────────┘
117
118       On some systems, changing the resource limits may not  be  allowed  for
119       non-root  users.  For  more  details,  see  https://github.com/contain
120       ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
121       source-limits-fails-with-a-permissions-error
122
123
124       This option is not supported on cgroups V1 rootless systems.
125
126
127   --cpus=amount
128       Set  the  total  number  of CPUs delegated to the pod. Default is 0.000
129       which indicates that there is no limit on computation power.
130
131
132   --cpuset-cpus=number
133       CPUs in which to allow execution. Can be specified as a comma-separated
134       list  (e.g.  0,1),  as  a  range (e.g. 0-3), or any combination thereof
135       (e.g. 0-3,7,11-15).
136
137
138       On some systems, changing the resource limits may not  be  allowed  for
139       non-root  users.  For  more  details,  see  https://github.com/contain
140       ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
141       source-limits-fails-with-a-permissions-error
142
143
144       This option is not supported on cgroups V1 rootless systems.
145
146
147   --cpuset-mems=nodes
148       Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effec‐
149       tive on NUMA systems.
150
151
152       If there are four memory nodes  on  the  system  (0-3),  use  --cpuset-
153       mems=0,1  then processes in the container will only use memory from the
154       first two memory nodes.
155
156
157       On some systems, changing the resource limits may not  be  allowed  for
158       non-root  users.  For  more  details,  see  https://github.com/contain
159       ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
160       source-limits-fails-with-a-permissions-error
161
162
163       This option is not supported on cgroups V1 rootless systems.
164
165
166   --device=host-device[:container-device][:permissions]
167       Add  a  host  device  to the pod. Optional permissions parameter can be
168       used to specify device permissions by  combining  r  for  read,  w  for
169       write, and m for mknod(2).
170
171
172       Example: --device=/dev/sdc:/dev/xvdc:rwm.
173
174
175       Note: if host-device is a symbolic link then it will be resolved first.
176       The pod will only store the major and minor numbers of the host device.
177
178
179       Podman may load kernel modules required for using the specified device.
180       The  devices  that  Podman  will  load  modules for when necessary are:
181       /dev/fuse.
182
183
184       In rootless mode, the new device is bind mounted in the container  from
185       the host rather than Podman creating it within the container space. Be‐
186       cause the bind mount retains its SELinux label on SELinux systems,  the
187       container  can get permission denied when accessing the mounted device.
188       Modify SELinux settings to allow containers to use  all  device  labels
189       via the following command:
190
191
192       $ sudo setsebool -P  container_use_devices=true
193
194
195       Note:  the  pod implements devices by storing the initial configuration
196       passed by the user and recreating the device on each container added to
197       the pod.
198
199
200   --device-read-bps=path:rate
201       Limit  read  rate  (in  bytes per second) from a device (e.g. --device-
202       read-bps=/dev/sda:1mb).
203
204
205       On some systems, changing the resource limits may not  be  allowed  for
206       non-root  users.  For  more  details,  see  https://github.com/contain
207       ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
208       source-limits-fails-with-a-permissions-error
209
210
211       This option is not supported on cgroups V1 rootless systems.
212
213
214   --device-write-bps=path:rate
215       Limit  write  rate  (in  bytes  per second) to a device (e.g. --device-
216       write-bps=/dev/sda:1mb).
217
218
219       On some systems, changing the resource limits may not  be  allowed  for
220       non-root  users.  For  more  details,  see  https://github.com/contain
221       ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
222       source-limits-fails-with-a-permissions-error
223
224
225       This option is not supported on cgroups V1 rootless systems.
226
227
228   --dns=ipaddr
229       Set custom DNS servers in the /etc/resolv.conf file that will be shared
230       between all containers in the pod. A special option, "none" is  allowed
231       which disables creation of /etc/resolv.conf for the pod.
232
233
234   --dns-option=option
235       Set custom DNS options in the /etc/resolv.conf file that will be shared
236       between all containers in the pod.
237
238
239   --dns-search=domain
240       Set custom DNS search domains in the /etc/resolv.conf file that will be
241       shared between all containers in the pod.
242
243
244   --exit-policy=continue | stop
245       Set  the  exit  policy  of the pod when the last container exits.  Sup‐
246       ported policies are:
247
248
249       ┌────────────┬────────────────────────────┐
250Exit Policy Description                
251       ├────────────┼────────────────────────────┤
252continue    │ The pod continues running, │
253       │            │ by  keeping its infra con‐ │
254       │            │ tainer  alive,  when   the │
255       │            │ last container exits. Used │
256       │            │ by default.                │
257       ├────────────┼────────────────────────────┤
258stop        │ The pod (including its in‐ │
259       │            │ fra  container) is stopped │
260       │            │ when  the  last  container │
261       │            │ exits. Used in kube play.  │
262       └────────────┴────────────────────────────┘
263
264   --gidmap=pod_gid:host_gid:amount
265       GID map for the user namespace. Using this flag will run all containers
266       in the pod with user namespace enabled.  It conflicts with the --userns
267       and --subgidname flags.
268
269
270   --help, -h
271       Print usage statement.
272
273
274   --hostname=name
275       Set a hostname to the pod.
276
277
278   --infra
279       Create  an infra container and associate it with the pod. An infra con‐
280       tainer is a lightweight container used to coordinate the shared  kernel
281       namespace of a pod. Default: true.
282
283
284   --infra-command=command
285       The  command  that  will  be run to start the infra container. Default:
286       "/pause".
287
288
289   --infra-conmon-pidfile=file
290       Write the pid of the infra container's conmon process  to  a  file.  As
291       conmon  runs  in a separate process than Podman, this is necessary when
292       using systemd to manage Podman containers and pods.
293
294
295   --infra-image=image
296       The custom image that will be used for  the  infra  container.   Unless
297       specified,  Podman  builds  a custom local image which does not require
298       pulling down an image.
299
300
301   --infra-name=name
302       The name that will be used for the pod's infra container.
303
304
305   --ip=ipv4
306       Specify a static IPv4 address for the pod,  for  example  10.88.64.128.
307       This option can only be used if the pod is joined to only a single net‐
308       work - i.e., --network=network-name is used at most once - and  if  the
309       pod  is  not  joining  another container's network namespace via --net‐
310       work=container:id.  The address must be within the network's IP address
311       pool (default 10.88.0.0/16).
312
313
314       To  specify multiple static IP addresses per pod, set multiple networks
315       using the --network option with a static IP address specified for  each
316       using the ip mode for that option.
317
318
319   --ip6=ipv6
320       Specify   a   static   IPv6   address   for   the   pod,   for  example
321       fd46:db93:aa76:ac37::10.  This option can only be used if  the  pod  is
322       joined  to only a single network - i.e., --network=network-name is used
323       at most once - and if the pod is not joining another  container's  net‐
324       work  namespace via --network=container:id.  The address must be within
325       the network's IPv6 address pool.
326
327
328       To specify multiple static IPv6 addresses per pod,  set  multiple  net‐
329       works  using  the --network option with a static IPv6 address specified
330       for each using the ip6 mode for that option.
331
332
333   --label, -l=key=value
334       Add metadata to a pod.
335
336
337   --label-file=file
338       Read in a line-delimited file of labels.
339
340
341   --mac-address=address
342       Pod network interface MAC address (e.g. 92:d0:c6:0a:29:33) This  option
343       can  only be used if the pod is joined to only a single network - i.e.,
344       --network=network-name is used at most once - and if  the  pod  is  not
345       joining   another  container's  network  namespace  via  --network=con‐
346       tainer:id.
347
348
349       Remember that the MAC address in an Ethernet network  must  be  unique.
350       The  IPv6  link-local address will be based on the device's MAC address
351       according to RFC4862.
352
353
354       To specify multiple static MAC addresses per pod, set multiple networks
355       using the --network option with a static MAC address specified for each
356       using the mac mode for that option.
357
358
359   --memory, -m=number[unit]
360       Memory limit. A unit can be b (bytes), k (kibibytes), m (mebibytes), or
361       g (gibibytes).
362
363
364       Allows  the  memory  available to a container to be constrained. If the
365       host supports swap memory, then the -m memory  setting  can  be  larger
366       than  physical  RAM.  If  a limit of 0 is specified (not using -m), the
367       container's memory is not limited. The actual limit may be  rounded  up
368       to  a  multiple of the operating system's page size (the value would be
369       very large, that's millions of trillions).
370
371
372       This option is not supported on cgroups V1 rootless systems.
373
374
375   --memory-swap=number[unit]
376       A limit value equal to memory plus swap.  A unit can be  b  (bytes),  k
377       (kibibytes), m (mebibytes), or g (gibibytes).
378
379
380       Must  be  used  with the -m (--memory) flag.  The argument value should
381       always be larger than that of
382        -m (--memory) By default, it is set to double the value of --memory.
383
384
385       Set number to -1 to enable unlimited swap.
386
387
388       This option is not supported on cgroups V1 rootless systems.
389
390
391   --name, -n=name
392       Assign a name to the pod.
393
394
395   --network=mode, --net
396       Set the network mode for the pod.
397
398
399       Valid mode values are:
400
401
402bridge[:OPTIONS,...]: Create a network stack  on  the  default
403                bridge. This is the default for rootful containers. It is pos‐
404                sible to specify these additional options:
405
406alias=name: Add network-scoped alias for the container.
407
408ip=IPv4: Specify a static ipv4 address for this container.
409
410ip=IPv6: Specify a static ipv6 address for this container.
411
412mac=MAC: Specify a static mac address for this container.
413
414interface_name: Specify a name for the created  network  in‐
415                  terface inside the container.
416
417
418
419
420
421       For  example to set a static ipv4 address and a static mac address, use
422       --network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99.  - <network  name
423       or  ID>[:OPTIONS,...]:  Connect  to a user-defined network; this is the
424       network name or ID from a network created by podman network create. Us‐
425       ing the network name implies the bridge network mode. It is possible to
426       specify the same options described under the bridge mode above. You can
427       use the --network option multiple times to specify additional networks.
428       - none: Create a network namespace for the container but do not config‐
429       ure  network  interfaces for it, thus the container has no network con‐
430       nectivity.  - container:id: Reuse another container's network stack.  -
431       host:  Do  not  create  a network namespace, the container will use the
432       host's network. Note: The host mode gives the container full access  to
433       local  system  services such as D-bus and is therefore considered inse‐
434       cure.  - ns:path: Path to a network namespace to join.  - private: Cre‐
435       ate  a  new  namespace for the container. This will use the bridge mode
436       for  rootful  containers  and  slirp4netns  for   rootless   ones.    -
437       slirp4netns[:OPTIONS,...]:  use slirp4netns(1) to create a user network
438       stack. This is the default for rootless containers. It is  possible  to
439       specify  these  additional  options,  they  can  also  be set with net‐
440       work_cmd_options in containers.conf:
441         - allow_host_loopback=true|false: Allow slirp4netns to reach the host
442       loopback IP (default is 10.0.2.2 or the second IP from slirp4netns cidr
443       subnet when changed, see the cidr option below). The default is false.
444         - mtu=MTU: Specify the MTU to  use  for  this  network.  (Default  is
445       65520).
446         -  cidr=CIDR:  Specify  ip range to use for this network. (Default is
447       10.0.2.0/24).
448         - enable_ipv6=true|false: Enable IPv6. Default is true. (Required for
449       outbound_addr6).
450         -  outbound_addr=INTERFACE:  Specify  the  outbound  interface  slirp
451       should bind to (ipv4 traffic only).
452         - outbound_addr=IPv4: Specify the outbound ipv4 address slirp  should
453       bind to.
454         -  outbound_addr6=INTERFACE:  Specify  the  outbound  interface slirp
455       should bind to (ipv6 traffic only).
456         - outbound_addr6=IPv6: Specify the outbound ipv6 address slirp should
457       bind to.
458         -  port_handler=rootlesskit: Use rootlesskit for port forwarding. De‐
459       fault.
460         Note: Rootlesskit changes the source IP address of  incoming  packets
461       to   an   IP  address  in  the  container  network  namespace,  usually
462       10.0.2.100. If your application requires the real  source  IP  address,
463       e.g. web server logs, use the slirp4netns port handler. The rootlesskit
464       port handler is also used for rootless  containers  when  connected  to
465       user-defined networks.
466         -  port_handler=slirp4netns:  Use the slirp4netns port forwarding, it
467       is slower than rootlesskit but preserves the correct source IP address.
468       This port handler cannot be used for user-defined networks.
469
470
471       Invalid  if  using  --dns, --dns-option, or --dns-search with --network
472       set to none or container:id.
473
474
475   --network-alias=alias
476       Add a network-scoped alias for the pod, setting the alias for all  net‐
477       works  that the container joins. To set a name only for a specific net‐
478       work, use the alias option as described under the --network option.  If
479       the  network has DNS enabled (podman network inspect -f {{.DNSEnabled}}
480       <name>), these aliases can be used for name  resolution  on  the  given
481       network. This option can be specified multiple times.  NOTE: When using
482       CNI a pod will only have access to aliases on the first network that it
483       joins. This limitation does not exist with netavark/aardvark-dns.
484
485
486   --no-hosts
487       Do  not  create /etc/hosts for the pod.  By default, Podman will manage
488       /etc/hosts, adding the container's own IP address and  any  hosts  from
489       --add-host.   --no-hosts disables this, and the image's /etc/hosts will
490       be preserved unmodified.
491
492
493       This option conflicts with --add-host.
494
495
496   --pid=pid
497       Set the PID mode for the pod. The default is to create  a  private  PID
498       namespace  for  the  pod.  Requires  the PID namespace to be shared via
499       --share.
500
501
502              host: use the host’s PID namespace for the pod
503              ns: join the specified PID namespace
504              private: create a new namespace for the pod (default)
505
506
507
508   --pod-id-file=path
509       Write the pod ID to the file.
510
511
512   --publish, -p=[[ip:][hostPort]:]containerPort[/protocol]
513       Publish a container's port, or range of ports, within this pod  to  the
514       host.
515
516
517       Both  hostPort  and containerPort can be specified as a range of ports.
518       When specifying ranges for both, the number of container ports  in  the
519       range must match the number of host ports in the range.
520
521
522       If  host IP is set to 0.0.0.0 or not set at all, the port will be bound
523       on all IPs on the host.
524
525
526       By default, Podman will publish TCP ports. To publish a  UDP  port  in‐
527       stead,  give  udp  as  protocol. To publish both TCP and UDP ports, set
528       --publish twice, with tcp, and udp as protocols  respectively.  Rootful
529       containers can also publish ports using the sctp protocol.
530
531
532       Host   port  does  not  have  to  be  specified  (e.g.  podman  run  -p
533       127.0.0.1::80).  If it is not, the container port will be randomly  as‐
534       signed a port on the host.
535
536
537       Use podman port to see the actual mapping: podman port $CONTAINER $CON‐
538       TAINERPORT.
539
540
541       Note: You must not publish ports of containers in the pod individually,
542       but only by the pod itself.
543
544
545       Note: This cannot be modified once the pod is created.
546
547
548   --replace
549       If  another  pod  with the same name already exists, replace and remove
550       it. The default is false.
551
552
553   --security-opt=option
554       Security Options
555
556
557apparmor=unconfined : Turn off apparmor  confinement  for  the
558                pod
559
560apparmor=your-profile  :  Set the apparmor confinement profile
561                for the pod
562
563label=user:USER     : Set the label user for the pod processes
564
565label=role:ROLE     : Set the label role for the pod processes
566
567label=type:TYPE     : Set the label process type for  the  pod
568                processes
569
570label=level:LEVEL    :  Set  the  label level for the pod pro‐
571                cesses
572
573label=filetype:TYPE : Set the label  file  type  for  the  pod
574                files
575
576label=disable       : Turn off label separation for the pod
577
578
579
580       Note:  Labeling  can be disabled for all pods/containers by setting la‐
581       bel=false in the  containers.conf  (/etc/containers/containers.conf  or
582       $HOME/.config/containers/containers.conf) file.
583
584
585mask=/path/1:/path/2 : The paths to mask separated by a colon.
586                A masked path cannot be accessed inside the containers  within
587                the pod.
588
589no-new-privileges  :  Disable container processes from gaining
590                additional privileges
591
592seccomp=unconfined : Turn off seccomp confinement for the pod
593
594seccomp=profile.json :  Whitelisted syscalls seccomp Json file
595                to be used as a seccomp filter
596
597proc-opts=OPTIONS : Comma-separated list of options to use for
598                the /proc mount. More details for the possible  mount  options
599                are specified in the proc(5) man page.
600
601unmask=ALL   or   /path/1:/path/2,  or  shell  expanded  paths
602                (/proc/*): Paths to unmask separated by a  colon.  If  set  to
603                ALL,  it  will  unmask  all  the paths that are masked or made
604                read-only  by  default.   The   default   masked   paths   are
605                /proc/acpi,   /proc/kcore,   /proc/keys,  /proc/latency_stats,
606                /proc/sched_debug,        /proc/scsi,        /proc/timer_list,
607                /proc/timer_stats,  /sys/firmware,  and  /sys/fs/selinux.  The
608                default paths that are read-only are /proc/asound,  /proc/bus,
609                /proc/fs,     /proc/irq,    /proc/sys,    /proc/sysrq-trigger,
610                /sys/fs/cgroup.
611
612
613
614       Note: Labeling can be  disabled  for  all  containers  by  setting  la‐
615       bel=false  in  the  containers.conf (/etc/containers/containers.conf or
616       $HOME/.config/containers/containers.conf) file.
617
618
619   --share=namespace
620       A comma-separated list of kernel namespaces to share. If none or ""  is
621       specified,  no  namespaces  will be shared and the infra container will
622       not be created unless expiclity specified via --infra=true.  The  name‐
623       spaces  to choose from are cgroup, ipc, net, pid, uts. If the option is
624       prefixed with a "+" then the namespace is appended to the default list,
625       otherwise it replaces the default list. Defaults matches Kubernetes de‐
626       fault (ipc, net, uts)
627
628
629   --share-parent
630       This boolean determines whether or not all containers entering the  pod
631       will use the pod as their cgroup parent. The default value of this flag
632       is true. If you are looking to share the cgroup namespace rather than a
633       cgroup parent in a pod, use --share
634
635
636       Note:  This  options  conflict with --share=cgroup since that would set
637       the pod as the cgroup parent but enter  the  container  into  the  same
638       cgroupNS as the infra container.
639
640
641   --shm-size=number[unit]
642       Size   of  /dev/shm.  A  unit  can  be  b  (bytes),  k  (kibibytes),  m
643       (mebibytes), or g (gibibytes).  If the unit is omitted, the system uses
644       bytes.  If  the  size  is omitted, the default is 64m.  When size is 0,
645       there is no limit on the amount of memory used  for  IPC  by  the  pod.
646       This option conflicts with --ipc=host.
647
648
649   --subgidname=name
650       Run  the  container  in a new user namespace using the map with name in
651       the /etc/subgid file.  If running rootless, the user needs to have  the
652       right  to  use  the  mapping.  See subgid(5).  This flag conflicts with
653       --userns and --gidmap.
654
655
656   --subuidname=name
657       Run the container in a new user namespace using the map  with  name  in
658       the  /etc/subuid file.  If running rootless, the user needs to have the
659       right to use the mapping. See  subuid(5).   This  flag  conflicts  with
660       --userns and --uidmap.
661
662
663   --sysctl=name=value
664       Configure namespaced kernel parameters for all containers in the pod.
665
666
667       For the IPC namespace, the following sysctls are allowed:
668
669
670              • kernel.msgmax
671
672              • kernel.msgmnb
673
674              • kernel.msgmni
675
676              • kernel.sem
677
678              • kernel.shmall
679
680              • kernel.shmmax
681
682              • kernel.shmmni
683
684              • kernel.shm_rmid_forced
685
686              • Sysctls beginning with fs.mqueue.*
687
688
689
690       Note:  if  the  ipc  namespace  is not shared within the pod, the above
691       sysctls are not allowed.
692
693
694       For the network namespace, only sysctls beginning with  net.*  are  al‐
695       lowed.
696
697
698       Note:  if the network namespace is not shared within the pod, the above
699       sysctls are not allowed.
700
701
702   --uidmap=container_uid:from_uid:amount
703       Run all containers in the pod in a new user namespace  using  the  sup‐
704       plied mapping. This option conflicts with the --userns and --subuidname
705       options. This option provides a way to map host UIDs to container UIDs.
706       It can be passed several times to map different ranges.
707
708
709   --userns=mode
710       Set  the  user  namespace  mode for all the containers in a pod. It de‐
711       faults to the PODMAN_USERNS environment variable. An empty  value  ("")
712       means user namespaces are disabled.
713
714
715       Rootless user --userns=Key mappings:
716
717
718       ┌────────┬───────────┬─────────────────────┐
719Key     Host User Container User      
720       ├────────┼───────────┼─────────────────────┤
721       │""      │ $UID      │ 0 (Default User ac‐ │
722       │        │           │ count   mapped   to │
723       │        │           │ root  user  in con‐ │
724       │        │           │ tainer.)            │
725       ├────────┼───────────┼─────────────────────┤
726       │keep-id │ $UID      │ $UID (Map user  ac‐ │
727       │        │           │ count  to  same UID │
728       │        │           │ within container.)  │
729       ├────────┼───────────┼─────────────────────┤
730       │auto    │ $UID      │ nil (Host User  UID │
731       │        │           │ is  not mapped into │
732       │        │           │ container.)         │
733       ├────────┼───────────┼─────────────────────┤
734       │nomap   │ $UID      │ nil (Host User  UID │
735       │        │           │ is  not mapped into │
736       │        │           │ container.)         │
737       └────────┴───────────┴─────────────────────┘
738
739       Valid mode values are:
740
741
742auto[:OPTIONS,...]: automatically create a  namespace.  It  is
743                possible to specify these options to auto:
744
745gidmapping=_CONTAINER_GID:HOSTGID:SIZE  to force a GID mapping
746                to be present in the user namespace.
747
748size=SIZE: to specify an explicit size for the automatic  user
749                namespace. e.g. --userns=auto:size=8192. If size is not speci‐
750                fied, auto will estimate a size for the user namespace.
751
752uidmapping=_CONTAINER_UID:HOSTUID:SIZE to force a UID  mapping
753                to be present in the user namespace.
754
755host:  run  in the user namespace of the caller. The processes
756                running in the container will have the same privileges on  the
757                host  as  any  other process launched by the calling user (de‐
758                fault).
759
760keep-id: creates a user namespace where the  current  rootless
761                user's UID:GID are mapped to the same values in the container.
762                This option is not allowed for containers created by the  root
763                user.
764
765nomap:  creates  a  user  namespace where the current rootless
766                user's UID:GID are not mapped into the container. This  option
767                is not allowed for containers created by the root user.
768
769
770
771   --uts=mode
772       Set  the  UTS namespace mode for the pod. The following values are sup‐
773       ported:
774
775
776host: use the host's UTS namespace inside the pod.
777
778private: create a new namespace for the pod (default).
779
780ns:[path]: run the pod in the given existing UTS namespace.
781
782
783
784   --volume, -v=[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]
785       Create a bind mount. If -v /HOST-DIR:/CONTAINER-DIR is specified,  Pod‐
786       man bind mounts /HOST-DIR from the host into /CONTAINER-DIR in the Pod‐
787       man container. Similarly, -v  SOURCE-VOLUME:/CONTAINER-DIR  will  mount
788       the  named  volume  from  the host into the container. If no such named
789       volume exists, Podman will create one. If no source is given, the  vol‐
790       ume will be created as an anonymously named volume with a randomly gen‐
791       erated name, and will be removed when the pod is removed via  the  --rm
792       flag or the podman rm --volumes command.
793
794
795       (Note  when using the remote client, including Mac and Windows (exclud‐
796       ing WSL2) machines, the volumes will be mounted from the remote server,
797       not necessarily the client machine.)
798
799
800       The OPTIONS is a comma-separated list and can be: [1] ⟨#Footnote1⟩
801
802
803rw|ro
804
805z|Z
806
807              • [O]
808
809              • [U]
810
811              • [no]copy
812
813              • [no]dev
814
815              • [no]exec
816
817              • [no]suid
818
819              • [r]bind
820
821              • [r]shared|[r]slave|[r]private[r]unbindable
822
823
824
825       The  CONTAINER-DIR must be an absolute path such as /src/docs. The vol‐
826       ume will be mounted into the container at this directory.
827
828
829       If a volume source is specified, it must be a path on the host  or  the
830       name  of a named volume. Host paths are allowed to be absolute or rela‐
831       tive; relative paths are resolved relative to the directory  Podman  is
832       run  in.  If  the  source  does not exist, Podman will return an error.
833       Users must pre-create the source files or directories.
834
835
836       Any source that does not begin with a . or / will  be  treated  as  the
837       name  of  a named volume. If a volume with that name does not exist, it
838       will be created.  Volumes created with names  are  not  anonymous,  and
839       they  are  not  removed  by the --rm option and the podman rm --volumes
840       command.
841
842
843       Specify multiple -v options to mount one or more volumes into a pod.
844
845
846       Write Protected Volume Mounts
847
848
849       Add :ro or :rw option to mount a  volume  in  read-only  or  read-write
850       mode,  respectively.  By  default,  the volumes are mounted read-write.
851       See examples.
852
853
854       Chowning Volume Mounts
855
856
857       By default, Podman does not change the owner and group of source volume
858       directories  mounted into containers. If a pod is created in a new user
859       namespace, the UID and GID in the container may correspond  to  another
860       UID and GID on the host.
861
862
863       The :U suffix tells Podman to use the correct host UID and GID based on
864       the UID and GID within the pod, to change  recursively  the  owner  and
865       group of the source volume.
866
867
868       Warning use with caution since this will modify the host filesystem.
869
870
871       Labeling Volume Mounts
872
873
874       Labeling  systems like SELinux require that proper labels are placed on
875       volume content mounted into a pod. Without a label, the security system
876       might  prevent the processes running inside the pod from using the con‐
877       tent. By default, Podman does not change the labels set by the OS.
878
879
880       To change a label in the pod context, add either of two suffixes :z  or
881       :Z  to the volume mount. These suffixes tell Podman to relabel file ob‐
882       jects on the shared volumes. The z option tells Podman  that  two  pods
883       share the volume content. As a result, Podman labels the content with a
884       shared content label. Shared volume  labels  allow  all  containers  to
885       read/write  content.   The  Z  option tells Podman to label the content
886       with a private unshared label.  Only the current pod can use a  private
887       volume.
888
889
890       Note:  Do  not  relabel system files and directories. Relabeling system
891       content might cause other confined services on your  machine  to  fail.
892       For  these  types  of containers we recommend disabling SELinux separa‐
893       tion.  The option --security-opt label=disable disables SELinux separa‐
894       tion  for  the pod.  For example if a user wanted to volume mount their
895       entire home directory into a pod, they need to disable SELinux  separa‐
896       tion.
897
898
899                 $ podman pod create --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file
900
901
902
903       Overlay Volume Mounts
904
905
906       The :O flag tells Podman to mount the directory from the host as a tem‐
907       porary storage using the overlay file system.  The  pod  processes  can
908       modify  content  within the mountpoint which is stored in the container
909       storage in a separate directory. In overlay terms, the source directory
910       will  be the lower, and the container storage directory will be the up‐
911       per. Modifications to the mount point are destroyed when the  pod  fin‐
912       ishes executing, similar to a tmpfs mount point being unmounted.
913
914
915       For  advanced  users,  the  overlay  option  also  supports custom non-
916       volatile upperdir and workdir for the overlay  mount.  Custom  upperdir
917       and  workdir  can  be fully managed by the users themselves, and Podman
918       will  not  remove  it  on   lifecycle   completion.    Example   :O,up‐
919       perdir=/some/upper,workdir=/some/work
920
921
922       Subsequent executions of the container will see the original source di‐
923       rectory content, any changes from previous pod executions no longer ex‐
924       ist.
925
926
927       One use case of the overlay mount is sharing the package cache from the
928       host into the container to allow speeding up builds.
929
930
931       Note:
932
933
934               - The `O` flag conflicts with other options listed above.
935
936
937
938       Content mounted into the container is labeled with the private label.
939              On SELinux systems, labels in the source directory must be read‐
940       able by the pod infra container label. Usually containers can read/exe‐
941       cute container_share_t and can read/write container_file_t.  If  unable
942       to  change  the labels on a source volume, SELinux container separation
943       must be disabled for the pod or infra container to work.
944            - The source directory mounted into the pod with an overlay  mount
945       should  not be modified, it can cause unexpected failures. It is recom‐
946       mended to not modify the directory until the  container  finishes  run‐
947       ning.
948
949
950       Mounts propagation
951
952
953       By default bind mounted volumes are private. That means any mounts done
954       inside the pod will not be visible on host  and  vice  versa.  One  can
955       change this behavior by specifying a volume mount propagation property.
956       Making a volume shared mounts done under that  volume  inside  the  pod
957       will  be  visible on host and vice versa. Making a volume slave enables
958       only one way mount propagation and that is mounts done  on  host  under
959       that  volume  will  be  visible  inside container but not the other way
960       around. [1] ⟨#Footnote1⟩
961
962
963       To control mount propagation property of  a  volume  one  can  use  the
964       [r]shared,  [r]slave, [r]private or the [r]unbindable propagation flag.
965       Propagation property can be specified only for bind mounted volumes and
966       not  for  internal  volumes  or named volumes. For mount propagation to
967       work the source mount point  (the  mount  point  where  source  dir  is
968       mounted  on)  has  to have the right propagation properties. For shared
969       volumes, the source mount point has to be shared. And  for  slave  vol‐
970       umes,  the  source  mount  point has to be either shared or slave.  [1]
971       ⟨#Footnote1⟩
972
973
974       To recursively mount a volume and all of its submounts into a pod,  use
975       the  rbind option. By default the bind option is used, and submounts of
976       the source directory will not be mounted into the pod.
977
978
979       Mounting the volume with the nosuid options means  that  SUID  applica‐
980       tions  on the volume will not be able to change their privilege. By de‐
981       fault volumes are mounted with nosuid.
982
983
984       Mounting the volume with the noexec option means that no executables on
985       the volume will be able to be executed within the pod.
986
987
988       Mounting  the volume with the nodev option means that no devices on the
989       volume will be able to be used by processes within the pod. By  default
990       volumes are mounted with nodev.
991
992
993       If  the HOST-DIR is a mount point, then dev, suid, and exec options are
994       ignored by the kernel.
995
996
997       Use df HOST-DIR to figure out the source mount,  then  use  findmnt  -o
998       TARGET,PROPAGATION  source-mount-dir  to figure out propagation proper‐
999       ties of source mount. If findmnt(1) utility is not available, then  one
1000       can   look   at   the  mount  entry  for  the  source  mount  point  in
1001       /proc/self/mountinfo. Look at the "optional  fields"  and  see  if  any
1002       propagation  properties  are  specified.   In there, shared:N means the
1003       mount is shared, master:N means mount  is  slave,  and  if  nothing  is
1004       there, the mount is private. [1] ⟨#Footnote1⟩
1005
1006
1007       To  change  propagation  properties of a mount point, use mount(8) com‐
1008       mand. For example, if one wants to bind mount  source  directory  /foo,
1009       one  can  do  mount  --bind  /foo /foo and mount --make-private --make-
1010       shared /foo. This will convert /foo into a shared mount point. Alterna‐
1011       tively, one can directly change propagation properties of source mount.
1012       Say / is source mount for /foo, then use mount --make-shared / to  con‐
1013       vert / into a shared mount.
1014
1015
1016       Note:  if  the  user  only has access rights via a group, accessing the
1017       volume from inside a rootless pod will fail.
1018
1019
1020   --volumes-from=CONTAINER[:OPTIONS]
1021       Mount volumes from the specified container(s). Used  to  share  volumes
1022       between containers and pods. The options is a comma-separated list with
1023       the following available elements:
1024
1025
1026rw|ro
1027
1028z
1029
1030
1031
1032       Mounts already mounted volumes from a  source  container  onto  another
1033       pod.  CONTAINER may be a name or ID.  To share a volume, use the --vol‐
1034       umes-from option when running the  target  container.  Volumes  can  be
1035       shared even if the source container is not running.
1036
1037
1038       By  default,  Podman mounts the volumes in the same mode (read-write or
1039       read-only) as it is mounted in  the  source  container.   This  can  be
1040       changed by adding a ro or rw option.
1041
1042
1043       Labeling  systems like SELinux require that proper labels are placed on
1044       volume content mounted into a pod. Without a label, the security system
1045       might prevent the processes running inside the container from using the
1046       content. By default, Podman does not change the labels set by the OS.
1047
1048
1049       To change a label in the pod context, add z to the volume mount.   This
1050       suffix  tells Podman to relabel file objects on the shared volumes. The
1051       z option tells Podman that two entities share the volume content. As  a
1052       result,  Podman  labels the content with a shared content label. Shared
1053       volume labels allow all containers to read/write content.
1054
1055
1056       If the location of the volume from the source container  overlaps  with
1057       data  residing  on a target pod, then the volume hides that data on the
1058       target.
1059
1060

EXAMPLES

1062              $ podman pod create --name test
1063
1064              $ podman pod create mypod
1065
1066              $ podman pod create --infra=false
1067
1068              $ podman pod create --infra-command /top toppod
1069
1070              $ podman pod create --publish 8443:443
1071
1072              $ podman pod create --network slirp4netns:outbound_addr=127.0.0.1,allow_host_loopback=true
1073
1074              $ podman pod create --network slirp4netns:cidr=192.168.0.0/24
1075
1076              $ podman pod create --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10
1077
1078
1079

SEE ALSO

1081       podman(1),  podman-pod(1),   podman-kube-play(1),   containers.conf(1),
1082       cgroups(7)
1083
1084

HISTORY

1086       July   2018,   Originally  compiled  by  Peter  Hunt  pehunt@redhat.com
1087       ⟨mailto:pehunt@redhat.com⟩
1088
1089

FOOTNOTES

1091       1: The Podman project is committed to inclusivity, a core value of open
1092       source. The master and slave mount propagation terminology used here is
1093       problematic and divisive, and should be changed. However,  these  terms
1094       are  currently  used  within the Linux kernel and must be used as-is at
1095       this time. When the kernel maintainers rectify this usage, Podman  will
1096       follow suit immediately.
1097
1098
1099
1100                                                          podman-pod-create(1)
Impressum