summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/source/markdown/options/README.md3
-rw-r--r--docs/source/markdown/options/volume.md176
-rw-r--r--docs/source/markdown/podman-create.1.md.in170
-rw-r--r--docs/source/markdown/podman-pod-clone.1.md.in164
-rw-r--r--docs/source/markdown/podman-pod-create.1.md.in162
-rw-r--r--docs/source/markdown/podman-run.1.md.in174
-rwxr-xr-xhack/markdown-preprocess13
-rwxr-xr-xhack/markdown-preprocess.t1
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__':