1podman-pod-create(1) General Commands Manual podman-pod-create(1)
2
6 podman-pod-create - Create a new pod
7
10 podman pod create [options] [name]
11
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 The operator can identify a pod in three ways: UUID long identifier
23 (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”)
24 UUID short identifier (“f78375b1c487”) Name (“jonah”)
25 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 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
44 --add-host=host:ip
45 Add a custom host-to-IP mapping (host:ip)
46 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 The /etc/hosts file is shared between all containers in the pod.
53 --blkio-weight=weight
56 Block IO relative weight. The weight is a value between 10 and 1000.
57 This option is not supported on cgroups V1 rootless systems.
60 --blkio-weight-device=device:weight
63 Block IO relative device weight.
64 --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 --cpu-shares, -c=shares
74 CPU shares (relative weight).
75 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 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 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 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 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 ┌────┬───────────┬─────┬──────────────┐
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 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 This option is not supported on cgroups V1 rootless systems.
125 --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 --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 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 This option is not supported on cgroups V1 rootless systems.
145 --cpuset-mems=nodes
148 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effec‐
149 tive on NUMA systems.
150 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 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 This option is not supported on cgroups V1 rootless systems.
164 --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 Example: --device=/dev/sdc:/dev/xvdc:rwm.
173 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 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 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 $ sudo setsebool -P container_use_devices=true
193 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 --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 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 This option is not supported on cgroups V1 rootless systems.
212 --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 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 This option is not supported on cgroups V1 rootless systems.
226 --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 --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 --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 --exit-policy=continue | stop
245 Set the exit policy of the pod when the last container exits. Sup‐
246 ported policies are:
247 ┌────────────┬────────────────────────────┐
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 --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 --help, -h
271 Print usage statement.
272 --hostname=name
275 Set a hostname to the pod.
276 --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 --infra-command=command
285 The command that will be run to start the infra container. Default:
286 "/pause".
287 --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 --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 --infra-name=name
302 The name that will be used for the pod's infra container.
303 --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 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 --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 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 --label, -l=key=value
334 Add metadata to a pod.
335 --label-file=file
338 Read in a line-delimited file of labels.
339 --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 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 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 --memory, -m=number[unit]
360 Memory limit. A unit can be b (bytes), k (kibibytes), m (mebibytes), or
361 g (gibibytes).
362 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 This option is not supported on cgroups V1 rootless systems.
373 --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 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 Set number to -1 to enable unlimited swap.
386 This option is not supported on cgroups V1 rootless systems.
389 --name, -n=name
392 Assign a name to the pod.
393 --network=mode, --net
396 Set the network mode for the pod.
397 Valid mode values are:
400 • 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 • alias=name: Add network-scoped alias for the container.
407 • ip=IPv4: Specify a static ipv4 address for this container.
409 • ip=IPv6: Specify a static ipv6 address for this container.
411 • mac=MAC: Specify a static mac address for this container.
413 • interface_name: Specify a name for the created network in‐
415 terface inside the container.
416 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 Invalid if using --dns, --dns-option, or --dns-search with --network
472 set to none or container:id.
473 --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 --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 This option conflicts with --add-host.
494 --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 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 --pod-id-file=path
509 Write the pod ID to the file.
510 --publish, -p=[[ip:][hostPort]:]containerPort[/protocol]
513 Publish a container's port, or range of ports, within this pod to the
514 host.
515 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 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 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 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 Use podman port to see the actual mapping: podman port $CONTAINER $CON‐
538 TAINERPORT.
539 Note: You must not publish ports of containers in the pod individually,
542 but only by the pod itself.
543 Note: This cannot be modified once the pod is created.
546 --replace
549 If another pod with the same name already exists, replace and remove
550 it. The default is false.
551 --security-opt=option
554 Security Options
555 • apparmor=unconfined : Turn off apparmor confinement for the
558 pod
559 • apparmor=your-profile : Set the apparmor confinement profile
561 for the pod
562 • label=user:USER : Set the label user for the pod processes
564 • label=role:ROLE : Set the label role for the pod processes
566 • label=type:TYPE : Set the label process type for the pod
568 processes
569 • label=level:LEVEL : Set the label level for the pod pro‐
571 cesses
572 • label=filetype:TYPE : Set the label file type for the pod
574 files
575 • label=disable : Turn off label separation for the pod
577 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 • 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 • no-new-privileges : Disable container processes from gaining
590 additional privileges
591 • seccomp=unconfined : Turn off seccomp confinement for the pod
593 • seccomp=profile.json : Whitelisted syscalls seccomp Json file
595 to be used as a seccomp filter
596 • 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 • 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 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 --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 --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 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 --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 --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 --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 --sysctl=name=value
664 Configure namespaced kernel parameters for all containers in the pod.
665 For the IPC namespace, the following sysctls are allowed:
668 • kernel.msgmax
671 • kernel.msgmnb
673 • kernel.msgmni
675 • kernel.sem
677 • kernel.shmall
679 • kernel.shmmax
681 • kernel.shmmni
683 • kernel.shm_rmid_forced
685 • Sysctls beginning with fs.mqueue.*
687 Note: if the ipc namespace is not shared within the pod, the above
691 sysctls are not allowed.
692 For the network namespace, only sysctls beginning with net.* are al‐
695 lowed.
696 Note: if the network namespace is not shared within the pod, the above
699 sysctls are not allowed.
700 --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 --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 Rootless user --userns=Key mappings:
716 ┌────────┬───────────┬─────────────────────┐
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 Valid mode values are:
740 • auto[:OPTIONS,...]: automatically create a namespace. It is
743 possible to specify these options to auto:
744 • gidmapping=_CONTAINER_GID:HOSTGID:SIZE to force a GID mapping
746 to be present in the user namespace.
747 • 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 • uidmapping=_CONTAINER_UID:HOSTUID:SIZE to force a UID mapping
753 to be present in the user namespace.
754 • 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 • 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 • 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 --uts=mode
772 Set the UTS namespace mode for the pod. The following values are sup‐
773 ported:
774 • host: use the host's UTS namespace inside the pod.
777 • private: create a new namespace for the pod (default).
779 • ns:[path]: run the pod in the given existing UTS namespace.
781 --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 (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 The OPTIONS is a comma-separated list and can be: [1] ⟨#Footnote1⟩
801 • rw|ro
804 • z|Z
806 • [O]
808 • [U]
810 • [no]copy
812 • [no]dev
814 • [no]exec
816 • [no]suid
818 • [r]bind
820 • [r]shared|[r]slave|[r]private[r]unbindable
822 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 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 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 Specify multiple -v options to mount one or more volumes into a pod.
844 Write Protected Volume Mounts
847 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 Chowning Volume Mounts
855 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 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 Warning use with caution since this will modify the host filesystem.
869 Labeling Volume Mounts
872 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 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 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 $ podman pod create --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file
900 Overlay Volume Mounts
904 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 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 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 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 Note:
932 - The `O` flag conflicts with other options listed above.
935 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 Mounts propagation
951 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 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 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 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 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 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 If the HOST-DIR is a mount point, then dev, suid, and exec options are
994 ignored by the kernel.
995 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 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 Note: if the user only has access rights via a group, accessing the
1017 volume from inside a rootless pod will fail.
1018 --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 • rw|ro
1027 • z
1029 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 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 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 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 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
1062 $ podman pod create --name test
1063 $ podman pod create mypod
1065 $ podman pod create --infra=false
1067 $ podman pod create --infra-command /top toppod
1069 $ podman pod create --publish 8443:443
1071 $ podman pod create --network slirp4netns:outbound_addr=127.0.0.1,allow_host_loopback=true
1073 $ podman pod create --network slirp4netns:cidr=192.168.0.0/24
1075 $ podman pod create --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10
1077
1081 podman(1), podman-pod(1), podman-kube-play(1), containers.conf(1),
1082 cgroups(7)
1083
1086 July 2018, Originally compiled by Peter Hunt pehunt@redhat.com
1087 ⟨mailto:pehunt@redhat.com⟩
1088
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 podman-pod-create(1)