1podman-pod-create(1) General Commands Manual podman-pod-create(1)
2
3
4
6 podman-pod-create - Create a new pod
7
8
10 podman pod create [options] [name]
11
12
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
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 ┌────┬───────────┬─────┬──────────────┐
109 │PID │ 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 ┌────────────┬────────────────────────────┐
250 │Exit Policy │ Description │
251 ├────────────┼────────────────────────────┤
252 │continue │ The pod continues running, │
253 │ │ by keeping its infra con‐ │
254 │ │ tainer alive, when the │
255 │ │ last container exits. Used │
256 │ │ by default. │
257 ├────────────┼────────────────────────────┤
258 │stop │ 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
402 • bridge[: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
406 • alias=name: Add network-scoped alias for the container.
407
408 • ip=IPv4: Specify a static ipv4 address for this container.
409
410 • ip=IPv6: Specify a static ipv6 address for this container.
411
412 • mac=MAC: Specify a static mac address for this container.
413
414 • interface_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
557 • apparmor=unconfined : Turn off apparmor confinement for the
558 pod
559
560 • apparmor=your-profile : Set the apparmor confinement profile
561 for the pod
562
563 • label=user:USER : Set the label user for the pod processes
564
565 • label=role:ROLE : Set the label role for the pod processes
566
567 • label=type:TYPE : Set the label process type for the pod
568 processes
569
570 • label=level:LEVEL : Set the label level for the pod pro‐
571 cesses
572
573 • label=filetype:TYPE : Set the label file type for the pod
574 files
575
576 • label=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
585 • mask=/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
589 • no-new-privileges : Disable container processes from gaining
590 additional privileges
591
592 • seccomp=unconfined : Turn off seccomp confinement for the pod
593
594 • seccomp=profile.json : Whitelisted syscalls seccomp Json file
595 to be used as a seccomp filter
596
597 • proc-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
601 • unmask=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 ┌────────┬───────────┬─────────────────────┐
719 │Key │ 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
742 • auto[:OPTIONS,...]: automatically create a namespace. It is
743 possible to specify these options to auto:
744
745 • gidmapping=_CONTAINER_GID:HOSTGID:SIZE to force a GID mapping
746 to be present in the user namespace.
747
748 • size=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
752 • uidmapping=_CONTAINER_UID:HOSTUID:SIZE to force a UID mapping
753 to be present in the user namespace.
754
755 • host: 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
760 • keep-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
765 • nomap: 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
776 • host: use the host's UTS namespace inside the pod.
777
778 • private: create a new namespace for the pod (default).
779
780 • ns:[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
803 • rw|ro
804
805 • z|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[4m(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
1026 • rw|ro
1027
1028 • z
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
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
1081 podman(1), podman-pod(1), podman-kube-play(1), containers.conf(1),
1082 cgroups(7)
1083
1084
1086 July 2018, Originally compiled by Peter Hunt pehunt@redhat.com
1087 ⟨mailto:pehunt@redhat.com⟩
1088
1089
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)