summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorEd Santiago <santiago@redhat.com>2022-09-06 06:39:09 -0600
committerEd Santiago <santiago@redhat.com>2022-09-06 08:20:32 -0600
commit40cd1c0ff5d4c1e99e51cf60046c957a1a6ba81e (patch)
tree626b8f9fdc93e148327a529418952a1c3765cd33 /docs
parentcd09e3b6d0b0eb32f6ad6062b13194f97873c664 (diff)
downloadpodman-40cd1c0ff5d4c1e99e51cf60046c957a1a6ba81e.tar.gz
podman-40cd1c0ff5d4c1e99e51cf60046c957a1a6ba81e.tar.bz2
podman-40cd1c0ff5d4c1e99e51cf60046c957a1a6ba81e.zip
Man pages: refactor common options: --device
The refactors are starting to get harder to review - sorry. Here the differences are pretty small, mostly changes to the "it is a combination" wording and some asteriskization. The more significant diffs are that there are some Notes that are pod- or container- or build-specific; I needed to move those from the middle to the end, then keep them in the source files themselves. I don't think this affects readability of the resulting man pages, but your opinion may differ. Last important thing: I included the /dev/fuse text in the common option, which means it will now show up in podman-build (it was not previously there). If this text is not applicable to podman-build, please LMK ASAP so I can just move it back to individual source files. Signed-off-by: Ed Santiago <santiago@redhat.com>
Diffstat (limited to 'docs')
-rw-r--r--docs/source/markdown/options/device.md14
-rw-r--r--docs/source/markdown/podman-build.1.md.in11
-rw-r--r--docs/source/markdown/podman-create.1.md.in15
-rw-r--r--docs/source/markdown/podman-pod-clone.1.md.in15
-rw-r--r--docs/source/markdown/podman-pod-create.1.md.in15
-rw-r--r--docs/source/markdown/podman-run.1.md.in15
6 files changed, 19 insertions, 66 deletions
diff --git a/docs/source/markdown/options/device.md b/docs/source/markdown/options/device.md
new file mode 100644
index 000000000..619c70a9b
--- /dev/null
+++ b/docs/source/markdown/options/device.md
@@ -0,0 +1,14 @@
+#### **--device**=*host-device[:container-device][:permissions]*
+
+Add a host device to the <<container|pod>>. Optional *permissions* parameter
+can be used to specify device permissions by combining
+**r** for read, **w** for write, and **m** for **mknod**(2).
+
+Example: **--device=/dev/sdc:/dev/xvdc:rwm**.
+
+Note: if *host-device* is a symbolic link then it will be resolved first.
+The <<container|pod>> will only store the major and minor numbers of the host device.
+
+Podman may load kernel modules required for using the specified
+device. The devices that Podman will load modules for when necessary are:
+/dev/fuse.
diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in
index bc1e03e4c..29d792aaa 100644
--- a/docs/source/markdown/podman-build.1.md.in
+++ b/docs/source/markdown/podman-build.1.md.in
@@ -205,16 +205,7 @@ keys and/or certificates. Decryption will be tried with all keys. If the key is
protected by a passphrase, it is required to be passed in the argument and
omitted otherwise.
-#### **--device**=*host-device[:container-device][:permissions]*
-
-Add a host device to the container. Optional *permissions* parameter
-can be used to specify device permissions, it is combination of
-**r** for read, **w** for write, and **m** for **mknod**(2).
-
-Example: **--device=/dev/sdc:/dev/xvdc:rwm**.
-
-Note: if *host-device* is a symbolic link then it will be resolved first.
-The container will only store the major and minor numbers of the host device.
+@@option device
Note: if the user only has access rights via a group, accessing the device
from inside a rootless container will fail. The **[crun(1)](https://github.com/containers/crun/tree/main/crun.1.md)** runtime offers a
diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in
index 25726af8c..f8c3c8511 100644
--- a/docs/source/markdown/podman-create.1.md.in
+++ b/docs/source/markdown/podman-create.1.md.in
@@ -123,25 +123,12 @@ each of stdin, stdout, and stderr.
@@option cpuset-mems
-#### **--device**=*host-device[:container-device][:permissions]*
-
-Add a host device to the container. Optional *permissions* parameter
-can be used to specify device permissions, it is combination of
-**r** for read, **w** for write, and **m** for **mknod**(2).
-
-Example: **--device=/dev/sdc:/dev/xvdc:rwm**.
-
-Note: if *host-device* is a symbolic link then it will be resolved first.
-The container will only store the major and minor numbers of the host device.
+@@option device
Note: if the user only has access rights via a group, accessing the device
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.
-Podman may load kernel modules required for using the specified
-device. The devices that podman will load modules when necessary are:
-/dev/fuse.
-
@@option device-cgroup-rule
@@option device-read-bps
diff --git a/docs/source/markdown/podman-pod-clone.1.md.in b/docs/source/markdown/podman-pod-clone.1.md.in
index d1e1b3468..d078ef35d 100644
--- a/docs/source/markdown/podman-pod-clone.1.md.in
+++ b/docs/source/markdown/podman-pod-clone.1.md.in
@@ -31,23 +31,10 @@ If none are specified, the original pod's CPUset is used.
@@option destroy
-#### **--device**=*host-device[:container-device][:permissions]*
-
-Add a host device to the pod. Optional *permissions* parameter
-can be used to specify device permissions. It is a combination of
-**r** for read, **w** for write, and **m** for **mknod**(2).
-
-Example: **--device=/dev/sdc:/dev/xvdc:rwm**.
-
-Note: if _host_device_ is a symbolic link then it will be resolved first.
-The pod will only store the major and minor numbers of the host device.
+@@option device
Note: the pod implements devices by storing the initial configuration passed by the user and recreating the device on each container added to the pod.
-Podman may load kernel modules required for using the specified
-device. The devices that Podman will load modules for when necessary are:
-/dev/fuse.
-
@@option device-read-bps
@@option device-write-bps
diff --git a/docs/source/markdown/podman-pod-create.1.md.in b/docs/source/markdown/podman-pod-create.1.md.in
index bad39b66f..22a8d90c4 100644
--- a/docs/source/markdown/podman-pod-create.1.md.in
+++ b/docs/source/markdown/podman-pod-create.1.md.in
@@ -48,23 +48,10 @@ Set the total number of CPUs delegated to the pod. Default is 0.000 which indica
@@option cpuset-mems
-#### **--device**=_host-device_[**:**_container-device_][**:**_permissions_]
-
-Add a host device to the pod. Optional *permissions* parameter
-can be used to specify device permissions. It is a combination of
-**r** for read, **w** for write, and **m** for **mknod**(2).
-
-Example: **--device=/dev/sdc:/dev/xvdc:rwm**.
-
-Note: if *host-device* is a symbolic link then it will be resolved first.
-The pod will only store the major and minor numbers of the host device.
+@@option device
Note: the pod implements devices by storing the initial configuration passed by the user and recreating the device on each container added to the pod.
-Podman may load kernel modules required for using the specified
-device. The devices that Podman will load modules for when necessary are:
-/dev/fuse.
-
@@option device-read-bps
@@option device-write-bps
diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in
index 3ad338662..db56459d2 100644
--- a/docs/source/markdown/podman-run.1.md.in
+++ b/docs/source/markdown/podman-run.1.md.in
@@ -159,25 +159,12 @@ Specify the key sequence for detaching a container. Format is a single character
This option can also be set in **containers.conf**(5) file.
-#### **--device**=*host-device[:container-device][:permissions]*
-
-Add a host device to the container. Optional *permissions* parameter
-can be used to specify device permissions by combining
-**r** for read, **w** for write, and **m** for **mknod**(2).
-
-Example: **--device=/dev/sdc:/dev/xvdc:rwm**.
-
-Note: if _host_device_ is a symbolic link then it will be resolved first.
-The container will only store the major and minor numbers of the host device.
+@@option device
Note: if the user only has access rights via a group, accessing the device
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.
-Podman may load kernel modules required for using the specified
-device. The devices that Podman will load modules when necessary are:
-/dev/fuse.
-
@@option device-cgroup-rule
@@option device-read-bps