diff options
Diffstat (limited to 'docs/source/markdown/podman-pod-create.1.md.in')
| -rw-r--r-- | docs/source/markdown/podman-pod-create.1.md.in | 162 |
1 files changed, 4 insertions, 158 deletions
diff --git a/docs/source/markdown/podman-pod-create.1.md.in b/docs/source/markdown/podman-pod-create.1.md.in index 24edbb918..3a3909340 100644 --- a/docs/source/markdown/podman-pod-create.1.md.in +++ b/docs/source/markdown/podman-pod-create.1.md.in @@ -263,164 +263,7 @@ When size is `0`, there is no limit on the amount of memory used for IPC by the @@option uts.pod -#### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]* - -Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, Podman -bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman -container. Similarly, `-v SOURCE-VOLUME:/CONTAINER-DIR` will mount the volume -in the host to the container. If no such named volume exists, Podman will -create one. The `OPTIONS` are a comma-separated list and can be: <sup>[[1]](#Footnote1)</sup> (Note when using the remote client, including Mac and Windows (excluding WSL2) machines, the volumes will be mounted from the remote server, not necessarily the client machine.) - -The _options_ is a comma-separated list and can be: - -* **rw**|**ro** -* **z**|**Z** -* [**r**]**shared**|[**r**]**slave**|[**r**]**private**[**r**]**unbindable** -* [**r**]**bind** -* [**no**]**exec** -* [**no**]**dev** -* [**no**]**suid** -* [**O**] -* [**U**] - -The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The volume -will be mounted into the container at this directory. - -Volumes may specify a source as well, as either a directory on the host -or the name of a named volume. If no source is given, the volume will be created as an -anonymously named volume with a randomly generated name, and will be removed when -the pod is removed via the `--rm` flag or `podman rm --volumes` commands. - -If a volume source is specified, it must be a path on the host or the name of a -named volume. Host paths are allowed to be absolute or relative; relative paths -are resolved relative to the directory Podman is run in. If the source does not -exist, Podman will return an error. Users must pre-create the source files or -directories. - -Any source that does not begin with a `.` or `/` will be treated as the name of -a named volume. If a volume with that name does not exist, it will be created. -Volumes created with names are not anonymous, and they are not removed by the `--rm` -option and the `podman rm --volumes` command. - -You can specify multiple **-v** options to mount one or more volumes into a -pod. - - `Write Protected Volume Mounts` - -You can add `:ro` or `:rw` suffix to a volume to mount it read-only or -read-write mode, respectively. By default, the volumes are mounted read-write. -See examples. - - `Chowning Volume Mounts` - -By default, Podman does not change the owner and group of source volume -directories mounted into containers. If a pod is created in a new user -namespace, the UID and GID in the container may correspond to another UID and -GID on the host. - -The `:U` suffix tells Podman to use the correct host UID and GID based on the -UID and GID within the pod, to change recursively the owner and group of -the source volume. - -**Warning** use with caution since this will modify the host filesystem. - - `Labeling Volume Mounts` - -Labeling systems like SELinux require that proper labels are placed on volume -content mounted into a pod. Without a label, the security system might -prevent the processes running inside the pod from using the content. By -default, Podman does not change the labels set by the OS. - -To change a label in the pod context, you can add either of two suffixes -`:z` or `:Z` to the volume mount. These suffixes tell Podman to relabel file -objects on the shared volumes. The `z` option tells Podman that two pods -share the volume content. As a result, Podman labels the content with a shared -content label. Shared volume labels allow all containers to read/write content. -The `Z` option tells Podman to label the content with a private unshared label. -Only the current pod can use a private volume. - - `Overlay Volume Mounts` - - The `:O` flag tells Podman to mount the directory from the host as a -temporary storage using the `overlay file system`. The pod processes -can modify content within the mountpoint which is stored in the -container storage in a separate directory. In overlay terms, the source -directory will be the lower, and the container storage directory will be the -upper. Modifications to the mount point are destroyed when the pod -finishes executing, similar to a tmpfs mount point being unmounted. - - Subsequent executions of the container will see the original source directory -content, any changes from previous pod executions no longer exist. - - One use case of the overlay mount is sharing the package cache from the -host into the container to allow speeding up builds. - - Note: - - - The `O` flag conflicts with other options listed above. -Content mounted into the container is labeled with the private label. - On SELinux systems, labels in the source directory must be readable -by the infra container label. Usually containers can read/execute `container_share_t` -and can read/write `container_file_t`. If you cannot change the labels on a -source volume, SELinux container separation must be disabled for the infra container/pod -to work. - - The source directory mounted into the pod with an overlay mount -should not be modified, it can cause unexpected failures. It is recommended -that you do not modify the directory until the container finishes running. - - `Mounts propagation` - -By default bind mounted volumes are `private`. That means any mounts done -inside pod will not be visible on host and vice versa. One can change -this behavior by specifying a volume mount propagation property. Making a -volume `shared` mounts done under that volume inside pod will be -visible on host and vice versa. Making a volume `slave` enables only one -way mount propagation and that is mounts done on host under that volume -will be visible inside container but not the other way around. <sup>[[1]](#Footnote1)</sup> - -To control mount propagation property of a volume one can use the [**r**]**shared**, -[**r**]**slave**, [**r**]**private** or the [**r**]**unbindable** propagation flag. -For mount propagation to work the source mount point (the mount point where source dir -is mounted on) has to have the right propagation properties. For shared volumes, the -source mount point has to be shared. And for slave volumes, the source mount point -has to be either shared or slave. <sup>[[1]](#Footnote1)</sup> - -If you want to recursively mount a volume and all of its submounts into a -pod, then you can use the `rbind` option. By default the bind option is -used, and submounts of the source directory will not be mounted into the -pod. - -Mounting the volume with the `nosuid` options means that SUID applications on -the volume will not be able to change their privilege. By default volumes -are mounted with `nosuid`. - -Mounting the volume with the noexec option means that no executables on the -volume will be able to executed within the pod. - -Mounting the volume with the nodev option means that no devices on the volume -will be able to be used by processes within the pod. By default volumes -are mounted with `nodev`. - -If the `<source-dir>` is a mount point, then "dev", "suid", and "exec" options are -ignored by the kernel. - -Use `df <source-dir>` to figure out the source mount and then use -`findmnt -o TARGET,PROPAGATION <source-mount-dir>` to figure out propagation -properties of source mount. If `findmnt` utility is not available, then one -can look at the mount entry for the source mount point in `/proc/self/mountinfo`. Look -at `optional fields` and see if any propagation properties are specified. -`shared:X` means mount is `shared`, `master:X` means mount is `slave` and if -nothing is there that means mount is `private`. <sup>[[1]](#Footnote1)</sup> - -To change propagation properties of a mount point use `mount` command. For -example, if one wants to bind mount source directory `/foo` one can do -`mount --bind /foo /foo` and `mount --make-private --make-shared /foo`. This -will convert /foo into a `shared` mount point. Alternatively one can directly -change propagation properties of source mount. Say `/` is source mount for -`/foo`, then use `mount --make-shared /` to convert `/` into a `shared` mount. - -Note: if the user only has access rights via a group, accessing the volume -from inside a rootless pod will fail. +@@option volume #### **--volumes-from**=*container[:options]]* @@ -482,3 +325,6 @@ $ podman pod create --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 ## HISTORY July 2018, Originally compiled by Peter Hunt <pehunt@redhat.com> + +## FOOTNOTES +<a name="Footnote1">1</a>: The Podman project is committed to inclusivity, a core value of open source. The `master` and `slave` mount propagation terminology used here is problematic and divisive, and should be changed. However, these terms are currently used within the Linux kernel and must be used as-is at this time. When the kernel maintainers rectify this usage, Podman will follow suit immediately. |