diff options
| -rw-r--r-- | docs/source/markdown/options/README.md | 3 | ||||
| -rw-r--r-- | docs/source/markdown/options/volume.md | 176 | ||||
| -rw-r--r-- | docs/source/markdown/podman-create.1.md.in | 170 | ||||
| -rw-r--r-- | docs/source/markdown/podman-pod-clone.1.md.in | 164 | ||||
| -rw-r--r-- | docs/source/markdown/podman-pod-create.1.md.in | 162 | ||||
| -rw-r--r-- | docs/source/markdown/podman-run.1.md.in | 174 | ||||
| -rwxr-xr-x | hack/markdown-preprocess | 13 | ||||
| -rwxr-xr-x | hack/markdown-preprocess.t | 1 |
8 files changed, 197 insertions, 666 deletions
diff --git a/docs/source/markdown/options/README.md b/docs/source/markdown/options/README.md index 92f3d374e..d8b608fb7 100644 --- a/docs/source/markdown/options/README.md +++ b/docs/source/markdown/options/README.md @@ -43,4 +43,5 @@ This allows the shared use of examples in the option file: Example: podman <<subcommand>> --foo --bar ``` As a special case, `podman-pod-X` becomes just `X` (the "pod" is removed). -This makes the `pod-id-file` man page more useful. +This makes the `pod-id-file` man page more useful. To get the full +subcommand including 'pod', use `<<fullsubcommand>>`. diff --git a/docs/source/markdown/options/volume.md b/docs/source/markdown/options/volume.md new file mode 100644 index 000000000..6d0d9a4b3 --- /dev/null +++ b/docs/source/markdown/options/volume.md @@ -0,0 +1,176 @@ +#### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]* + +Create a bind mount. If `-v /HOST-DIR:/CONTAINER-DIR` is specified, Podman +bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman +container. Similarly, `-v SOURCE-VOLUME:/CONTAINER-DIR` will mount the named +volume from the host into the container. If no such named volume exists, Podman will +create one. (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: <sup>[[1]](#Footnote1)</sup> + +* **rw**|**ro** +* **z**|**Z** +* [**O**] +* [**U**] +* [**no**]**copy** +* [**no**]**dev** +* [**no**]**exec** +* [**no**]**suid** +* [**r**]**bind** +* [**r**]**shared**|[**r**]**slave**|[**r**]**private**[**r**]**unbindable** + +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 <<container|pod>> is removed via the `--rm` flag or the `podman rm --volumes` command. + +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. + +Specify multiple **-v** options to mount one or more volumes into a +<<container|pod>>. + + `Write Protected Volume Mounts` + +Add **:ro** or **:rw** option to mount a volume in 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 <<container|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 <<container|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 <<container|pod>>. Without a label, the security system might +prevent the processes running inside the <<container|pod>> from using the content. By +default, Podman does not change the labels set by the OS. + +To change a label in the <<container|pod>> context, 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 <<containers|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 <<container|pod>> can use a private volume. + +Note: Do not relabel system files and directories. Relabeling system content +might cause other confined services on your machine to fail. For these types +of containers we recommend disabling SELinux separation. The option +**--security-opt label=disable** disables SELinux separation for the <<container|pod>>. +For example if a user wanted to volume mount their entire home directory into a +<<container|pod>>, they need to disable SELinux separation. + + $ podman <<fullsubcommand>> --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file + + `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 <<container|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 <<container|pod>> +finishes executing, similar to a tmpfs mount point being unmounted. + +For advanced users, the **overlay** option also supports custom non-volatile +**upperdir** and **workdir** for the overlay mount. Custom **upperdir** and +**workdir** can be fully managed by the users themselves, and Podman will not +remove it on lifecycle completion. +Example **:O,upperdir=/some/upper,workdir=/some/work** + + Subsequent executions of the container will see the original source directory +content, any changes from previous <<container|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 <<|pod infra>> container label. Usually containers can read/execute `container_share_t` +and can read/write `container_file_t`. If unable to change the labels on a +source volume, SELinux container separation must be disabled for the <<|pod or infra>> container +to work. + - The source directory mounted into the <<container|pod>> with an overlay mount +should not be modified, it can cause unexpected failures. It is recommended +to not modify the directory until the container finishes running. + + `Mounts propagation` + +By default bind mounted volumes are `private`. That means any mounts done +inside the <<container|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 the <<container|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. +Propagation property can be specified only for bind mounted volumes and not for +internal volumes or named volumes. 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> + +To recursively mount a volume and all of its submounts into a +<<container|pod>>, use the **rbind** option. By default the bind option is +used, and submounts of the source directory will not be mounted into the +<<container|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 be executed within the <<container|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 <<container|pod>>. By default volumes +are mounted with **nodev**. + +If the _HOST-DIR_ is a mount point, then **dev**, **suid**, and **exec** options are +ignored by the kernel. + +Use **df HOST-DIR** to figure out the source mount, then use +**findmnt -o TARGET,PROPAGATION _source-mount-dir_** to figure out propagation +properties of source mount. If **findmnt**(1) utility is not available, then one +can look at the mount entry for the source mount point in _/proc/self/mountinfo_. Look +at the "optional fields" and see if any propagation properties are specified. +In there, **shared:N** means the mount is shared, **master:N** means mount +is slave, and if nothing is there, the mount is private. <sup>[[1]](#Footnote1)</sup> + +To change propagation properties of a mount point, use **mount**(8) 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 <<container|pod>> will fail. diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index f74429848..17ef704e6 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -539,175 +539,9 @@ Without this argument the command will be run as root in the container. #### **--variant**=*VARIANT* Use _VARIANT_ instead of the default architecture variant of the container image. Some images can use multiple variants of the arm architectures, such as arm/v5 and arm/v7. -#### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]* +@@option volume -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** -* [**O**] -* [**U**] -* [**no**]**copy** -* [**no**]**dev** -* [**no**]**exec** -* [**no**]**suid** -* [**r**]**bind** -* [**r**]**shared**|[**r**]**slave**|[**r**]**private**[**r**]**unbindable** - -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 container is removed via the `--rm` flag or `podman rm --volumes`. - -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 -container. - - `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 container 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 container, 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 container. Without a label, the security system might -prevent the processes running inside the container from using the content. By -default, Podman does not change the labels set by the OS. - -To change a label in the container 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 containers -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 container can use a private volume. - -Note: Do not relabel system files and directories. Relabeling system content -might cause other confined services on your machine to fail. For these types -of containers we recommend disabling SELinux separation. The option -`--security-opt label=disable` disables SELinux separation for containers used in the build. -For example if a user wanted to volume mount their entire home directory into a -container, they need to disable SELinux separation. - - $ podman create --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file - - `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 container 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 container -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 container 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 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 container -to work. - - The source directory mounted into the container 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 container 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 container 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 -container, 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 -container. - -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 be executed within the container. - -Mounting the volume with the nodev option means that no devices on the volume -will be able to be used by processes within the container. 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 mount entry for 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 container will fail. Use the `--group-add keep-groups` -flag to pass the user's supplementary group access into the container. +Use the **--group-add keep-groups** option to pass the user's supplementary group access into the container. #### **--volumes-from**=*CONTAINER[:OPTIONS]]* diff --git a/docs/source/markdown/podman-pod-clone.1.md.in b/docs/source/markdown/podman-pod-clone.1.md.in index 011efc5b7..1d7b1f259 100644 --- a/docs/source/markdown/podman-pod-clone.1.md.in +++ b/docs/source/markdown/podman-pod-clone.1.md.in @@ -122,166 +122,7 @@ clone process has completed. All containers within the pod are started. @@option uts.pod -#### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]* - -Create a bind mount. If ` -v /HOST-DIR:/CONTAINER-DIR` is specified, 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. - -Specify multiple **-v** options to mount one or more volumes into a -pod. - - `Write Protected Volume Mounts` - -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, 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 unable to 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 -to 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. -Propagation property can be specified only for bind mounted volumes and not for -internal volumes or named volumes. 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> - -To recursively mount a volume and all of its submounts into a -pod, 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]]* @@ -343,3 +184,6 @@ d0cf1f782e2ed67e8c0050ff92df865a039186237a4df24d7acba5b1fa8cc6e7 ## HISTORY May 2022, Originally written by Charlie Doern <cdoern@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. 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. diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index 86066ad9c..493a7494a 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -584,179 +584,9 @@ When a user namespace is not in use, the UID and GID used within the container a #### **--variant**=*VARIANT* Use _VARIANT_ instead of the default architecture variant of the container image. Some images can use multiple variants of the arm architectures, such as arm/v5 and arm/v7. -#### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]* +@@option volume -Create a bind mount. If you specify _/HOST-DIR_:_/CONTAINER-DIR_, Podman -bind mounts _host-dir_ in the host to _CONTAINER-DIR_ in the Podman -container. Similarly, _SOURCE-VOLUME_:_/CONTAINER-DIR_ will mount the volume -in the host to the container. If no such named volume exists, Podman will -create one. (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: <sup>[[1]](#Footnote1)</sup> - -* **rw**|**ro** -* **z**|**Z** -* [**O**] -* [**U**] -* [**no**]**copy** -* [**no**]**dev** -* [**no**]**exec** -* [**no**]**suid** -* [**r**]**bind** -* [**r**]**shared**|[**r**]**slave**|[**r**]**private**[**r**]**unbindable** - -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 container is removed via the `--rm` flag or `podman rm --volumes`. - -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 -container. - - `Write Protected Volume Mounts` - -You can add **:ro** or **:rw** option to mount a volume in read-only or -read-write mode, respectively. By default, the volumes are mounted read-write. - - `Chowning Volume Mounts` - -By default, Podman does not change the owner and group of source volume -directories mounted into containers. If a container 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 container, 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 container. Without a label, the security system might -prevent the processes running inside the container from using the content. By -default, Podman does not change the labels set by the OS. - -To change a label in the container 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 containers -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. - -Note: Do not relabel system files and directories. Relabeling system content -might cause other confined services on your machine to fail. For these types -of containers we recommend disabling SELinux separation. The option -`--security-opt label=disable` disables SELinux separation for the container. -For example if a user wanted to volume mount their entire home directory into a -container, they need to disable SELinux separation. - - $ podman run --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file - - `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 container 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 container -finishes executing, similar to a tmpfs mount point being unmounted. - - For advanced users overlay option also supports custom non-volatile `upperdir` and `workdir` -for the overlay mount. Custom `upperdir` and `workdir` can be fully managed by the users themselves -and `podman` will not remove it on lifecycle completion. Example `:O,upperdir=/some/upper,workdir=/some/work` - - Subsequent executions of the container will see the original source directory -content, any changes from previous container 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 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 container -to work. - - The source directory mounted into the container 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. - -Only the current container can use a private volume. - - `Mounts propagation` - -By default bind mounted volumes are `private`. That means any mounts done -inside container 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 container 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 -container, 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 -container. - -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 be executed within the container. - -Mounting the volume with the **nodev** option means that no devices on the volume -will be able to be used by processes within the container. By default volumes -are mounted with **nodev**. - -If the _host-dir_ is a mount point, then **dev**, **suid**, and **exec** options are -ignored by the kernel. - -Use **df $hostdir** 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**(1) utility is not available, then one -can look at mount entry for source mount point in _/proc/self/mountinfo_. Look -at the "optional fields" and see if any propagation properties are specified. -In there, **shared:N** means the mount is shared, **master:N** means mount -is slave, and if nothing is there, the mount is private. <sup>[[1]](#Footnote1)</sup> - -To change propagation properties of a mount point, use **mount**(8) 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, if _/_ 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 container will fail. Use the `--group-add keep-groups` -flag to pass the user's supplementary group access into the container. +Use the **--group-add keep-groups** option to pass the user's supplementary group access into the container. #### **--volumes-from**=*CONTAINER[:OPTIONS]* diff --git a/hack/markdown-preprocess b/hack/markdown-preprocess index 68e5890d8..9cd1e9605 100755 --- a/hack/markdown-preprocess +++ b/hack/markdown-preprocess @@ -32,9 +32,6 @@ def process(infile): if '-pod-' in infile or '-kube-' in infile: pod_or_container = 'pod' - # Sometimes a man page includes the subcommand. - subcommand = podman_subcommand(infile) - # foo.md.in -> foo.md -- but always write to a tmpfile outfile = os.path.splitext(infile)[0] outfile_tmp = outfile + '.tmp.' + str(os.getpid()) @@ -57,7 +54,8 @@ def process(infile): with open(optionfile, 'r') as fh_optfile: for opt_line in fh_optfile: opt_line = replace_type(opt_line, pod_or_container) - opt_line = opt_line.replace('<<subcommand>>', subcommand) + opt_line = opt_line.replace('<<subcommand>>', podman_subcommand(infile)) + opt_line = opt_line.replace('<<fullsubcommand>>', podman_subcommand(infile, 'full')) fh_out.write(opt_line) fh_out.write("\n[//]: # (END included file " + optionfile + ")\n") else: @@ -67,10 +65,11 @@ def process(infile): os.rename(outfile_tmp, outfile) # Given a file path of the form podman-foo-bar.1.md.in, return "foo bar" -def podman_subcommand(string: str) -> str: +def podman_subcommand(string: str, full=None) -> str: # Special case: 'podman-pod-start' becomes just 'start' - if string.startswith("podman-pod-"): - string = string[len("podman-pod-"):] + if not full: + if string.startswith("podman-pod-"): + string = string[len("podman-pod-"):] if string.startswith("podman-"): string = string[len("podman-"):] if string.endswith(".1.md.in"): diff --git a/hack/markdown-preprocess.t b/hack/markdown-preprocess.t index 3cc983999..152da087b 100755 --- a/hack/markdown-preprocess.t +++ b/hack/markdown-preprocess.t @@ -71,6 +71,7 @@ class TestPodmanSubcommand(unittest.TestCase): self.assertEqual(mp.podman_subcommand("podman-foo.1.md.in"), "foo") self.assertEqual(mp.podman_subcommand("podman-foo-bar.1.md.in"), "foo bar") self.assertEqual(mp.podman_subcommand("podman-pod-rm.1.md.in"), "rm") + self.assertEqual(mp.podman_subcommand("podman-pod-rm.1.md.in", "full"), "pod rm") if __name__ == '__main__': |