From 74388fe75ffa896993256c5336dabaa071b034f9 Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Mon, 22 Aug 2022 13:06:49 -0600 Subject: Man pages: refactor common options: --pod-id-file Much like --cidfile (#15414), --pod-id-file has two meanings. One is used in pod-related commands, one in container ones. Both meanings read the file, so the read/write split used in --cidfile is not applicable here. podman-pod-create keeps its --pod-id-file option because that one cannot be refactored: that's the only command (now) that writes a pod-id file. Reviewable using hack/markdown-preprocess-review but I did take some liberties with the #### args because they were wrong. And, since I had to much with the description text anyway (resulting in diffs), I also took the liberty of cleaning up a double space. Signed-off-by: Ed Santiago --- docs/source/markdown/.gitignore | 3 + .../markdown/options/pod-id-file.container.md | 4 + docs/source/markdown/options/pod-id-file.pod.md | 3 + docs/source/markdown/podman-create.1.md.in | 4 +- docs/source/markdown/podman-pod-rm.1.md | 81 -------------------- docs/source/markdown/podman-pod-rm.1.md.in | 79 ++++++++++++++++++++ docs/source/markdown/podman-pod-start.1.md | 58 --------------- docs/source/markdown/podman-pod-start.1.md.in | 56 ++++++++++++++ docs/source/markdown/podman-pod-stop.1.md | 86 ---------------------- docs/source/markdown/podman-pod-stop.1.md.in | 84 +++++++++++++++++++++ docs/source/markdown/podman-run.1.md.in | 5 +- 11 files changed, 231 insertions(+), 232 deletions(-) create mode 100644 docs/source/markdown/options/pod-id-file.container.md create mode 100644 docs/source/markdown/options/pod-id-file.pod.md delete mode 100644 docs/source/markdown/podman-pod-rm.1.md create mode 100644 docs/source/markdown/podman-pod-rm.1.md.in delete mode 100644 docs/source/markdown/podman-pod-start.1.md create mode 100644 docs/source/markdown/podman-pod-start.1.md.in delete mode 100644 docs/source/markdown/podman-pod-stop.1.md create mode 100644 docs/source/markdown/podman-pod-stop.1.md.in (limited to 'docs/source') diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore index 5a30aab78..2bdcce197 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -13,6 +13,9 @@ podman-manifest-push.1.md podman-pause.1.md podman-pod-clone.1.md podman-pod-create.1.md +podman-pod-rm.1.md +podman-pod-start.1.md +podman-pod-stop.1.md podman-pull.1.md podman-push.1.md podman-rm.1.md diff --git a/docs/source/markdown/options/pod-id-file.container.md b/docs/source/markdown/options/pod-id-file.container.md new file mode 100644 index 000000000..1c102dc6b --- /dev/null +++ b/docs/source/markdown/options/pod-id-file.container.md @@ -0,0 +1,4 @@ +#### **--pod-id-file**=*file* + +Run container in an existing pod and read the pod's ID from the specified *file*. +If a container is run within a pod, and the pod has an infra-container, the infra-container will be started before the container is. diff --git a/docs/source/markdown/options/pod-id-file.pod.md b/docs/source/markdown/options/pod-id-file.pod.md new file mode 100644 index 000000000..69e2ac6e9 --- /dev/null +++ b/docs/source/markdown/options/pod-id-file.pod.md @@ -0,0 +1,3 @@ +#### **--pod-id-file**=*file* + +Read pod ID from the specified *file* and <> the pod. Can be specified multiple times. diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 2827964f7..b943783cb 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -476,9 +476,7 @@ Default is to create a private PID namespace for the container Run container in an existing pod. If you want Podman to make the pod for you, preference the pod name with `new:`. To make a pod with more granular options, use the `podman pod create` command before creating a container. -#### **--pod-id-file**=*path* - -Run container in an existing pod and read the pod's ID from the specified file. If a container is run within a pod, and the pod has an infra-container, the infra-container will be started before the container is. +@@option pod-id-file.container #### **--privileged** diff --git a/docs/source/markdown/podman-pod-rm.1.md b/docs/source/markdown/podman-pod-rm.1.md deleted file mode 100644 index befab6791..000000000 --- a/docs/source/markdown/podman-pod-rm.1.md +++ /dev/null @@ -1,81 +0,0 @@ -% podman-pod-rm(1) - -## NAME -podman\-pod\-rm - Remove one or more stopped pods and containers - -## SYNOPSIS -**podman pod rm** [*options*] *pod* - -## DESCRIPTION -**podman pod rm** will remove one or more stopped pods and their containers from the host. The pod name or ID can be used. The \-f option stops all containers and then removes them before removing the pod. If all containers added by the user are in an exited state, the pod will be removed. - -## OPTIONS - -#### **--all**, **-a** - -Remove all pods. Can be used in conjunction with \-f as well. - -#### **--force**, **-f** - -Stop running containers and delete all stopped containers before removal of pod. - -#### **--ignore**, **-i** - -Ignore errors when specified pods are not in the container store. A user might -have decided to manually remove a pod which would lead to a failure during the -ExecStop directive of a systemd service referencing that pod. - -#### **--latest**, **-l** - -Instead of providing the pod name or ID, remove the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--pod-id-file** - -Read pod ID from the specified file and remove the pod. Can be specified multiple times. - -#### **--time**, **-t**=*seconds* - -Seconds to wait before forcibly stopping running containers within the pod. The --force option must be specified to use the --time option. - -## EXAMPLE - -Remove pod with a given name -``` -podman pod rm mywebserverpod -``` - -Remove multiple pods with given names and/or IDs -``` -podman pod rm mywebserverpod myflaskserverpod 860a4b23 -``` - -Forcefully remove pod with a given ID -``` -podman pod rm -f 860a4b23 -``` - -Forcefully remove all pods -``` -podman pod rm -f -a -podman pod rm -fa -``` - -Remove pod using ID specified in a given file -``` -podman pod rm --pod-id-file /path/to/id/file -``` - -## Exit Status - **0** All specified pods removed - - **1** One of the specified pods did not exist, and no other failures - - **2** One of the specified pods is attached to a container - - **125** The command fails for any other reason - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)** - -## HISTORY -July 2018, Originally compiled by Peter Hunt diff --git a/docs/source/markdown/podman-pod-rm.1.md.in b/docs/source/markdown/podman-pod-rm.1.md.in new file mode 100644 index 000000000..54646ebe3 --- /dev/null +++ b/docs/source/markdown/podman-pod-rm.1.md.in @@ -0,0 +1,79 @@ +% podman-pod-rm(1) + +## NAME +podman\-pod\-rm - Remove one or more stopped pods and containers + +## SYNOPSIS +**podman pod rm** [*options*] *pod* + +## DESCRIPTION +**podman pod rm** will remove one or more stopped pods and their containers from the host. The pod name or ID can be used. The \-f option stops all containers and then removes them before removing the pod. If all containers added by the user are in an exited state, the pod will be removed. + +## OPTIONS + +#### **--all**, **-a** + +Remove all pods. Can be used in conjunction with \-f as well. + +#### **--force**, **-f** + +Stop running containers and delete all stopped containers before removal of pod. + +#### **--ignore**, **-i** + +Ignore errors when specified pods are not in the container store. A user might +have decided to manually remove a pod which would lead to a failure during the +ExecStop directive of a systemd service referencing that pod. + +#### **--latest**, **-l** + +Instead of providing the pod name or ID, remove the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +@@option pod-id-file.pod + +#### **--time**, **-t**=*seconds* + +Seconds to wait before forcibly stopping running containers within the pod. The --force option must be specified to use the --time option. + +## EXAMPLE + +Remove pod with a given name +``` +podman pod rm mywebserverpod +``` + +Remove multiple pods with given names and/or IDs +``` +podman pod rm mywebserverpod myflaskserverpod 860a4b23 +``` + +Forcefully remove pod with a given ID +``` +podman pod rm -f 860a4b23 +``` + +Forcefully remove all pods +``` +podman pod rm -f -a +podman pod rm -fa +``` + +Remove pod using ID specified in a given file +``` +podman pod rm --pod-id-file /path/to/id/file +``` + +## Exit Status + **0** All specified pods removed + + **1** One of the specified pods did not exist, and no other failures + + **2** One of the specified pods is attached to a container + + **125** The command fails for any other reason + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)** + +## HISTORY +July 2018, Originally compiled by Peter Hunt diff --git a/docs/source/markdown/podman-pod-start.1.md b/docs/source/markdown/podman-pod-start.1.md deleted file mode 100644 index 45fc50c51..000000000 --- a/docs/source/markdown/podman-pod-start.1.md +++ /dev/null @@ -1,58 +0,0 @@ -% podman-pod-start(1) - -## NAME -podman\-pod\-start - Start one or more pods - -## SYNOPSIS -**podman pod start** [*options*] *pod* ... - -## DESCRIPTION -Start containers in one or more pods. You may use pod IDs or names as input. The pod must have a container attached -to be started. - -## OPTIONS - -#### **--all**, **-a** - -Starts all pods - -#### **--latest**, **-l** - -Instead of providing the pod name or ID, start the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--pod-id-file** - -Read pod ID from the specified file and start the pod. Can be specified multiple times. - -## EXAMPLE - -Start pod with a given name -``` -podman pod start mywebserverpod -``` - -Start pods with given IDs -``` -podman pod start 860a4b23 5421ab4 -``` - -Start the latest pod created by Podman -``` -podman pod start --latest -``` - -Start all pods -``` -podman pod start --all -``` - -Start pod using ID specified in a given file -``` -podman pod start --pod-id-file /path/to/id/file -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-pod-stop(1)](podman-pod-stop.1.md)** - -## HISTORY -July 2018, Adapted from podman start man page by Peter Hunt diff --git a/docs/source/markdown/podman-pod-start.1.md.in b/docs/source/markdown/podman-pod-start.1.md.in new file mode 100644 index 000000000..6a47ce1b9 --- /dev/null +++ b/docs/source/markdown/podman-pod-start.1.md.in @@ -0,0 +1,56 @@ +% podman-pod-start(1) + +## NAME +podman\-pod\-start - Start one or more pods + +## SYNOPSIS +**podman pod start** [*options*] *pod* ... + +## DESCRIPTION +Start containers in one or more pods. You may use pod IDs or names as input. The pod must have a container attached +to be started. + +## OPTIONS + +#### **--all**, **-a** + +Starts all pods + +#### **--latest**, **-l** + +Instead of providing the pod name or ID, start the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +@@option pod-id-file.pod + +## EXAMPLE + +Start pod with a given name +``` +podman pod start mywebserverpod +``` + +Start pods with given IDs +``` +podman pod start 860a4b23 5421ab4 +``` + +Start the latest pod created by Podman +``` +podman pod start --latest +``` + +Start all pods +``` +podman pod start --all +``` + +Start pod using ID specified in a given file +``` +podman pod start --pod-id-file /path/to/id/file +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-pod-stop(1)](podman-pod-stop.1.md)** + +## HISTORY +July 2018, Adapted from podman start man page by Peter Hunt diff --git a/docs/source/markdown/podman-pod-stop.1.md b/docs/source/markdown/podman-pod-stop.1.md deleted file mode 100644 index bded0ba7d..000000000 --- a/docs/source/markdown/podman-pod-stop.1.md +++ /dev/null @@ -1,86 +0,0 @@ -% podman-pod-stop(1) - -## NAME -podman\-pod\-stop - Stop one or more pods - -## SYNOPSIS -**podman pod stop** [*options*] *pod* ... - -## DESCRIPTION -Stop containers in one or more pods. You may use pod IDs or names as input. - -## OPTIONS - -#### **--all**, **-a** - -Stops all pods - -#### **--ignore**, **-i** - -Ignore errors when specified pods are not in the container store. A user might -have decided to manually remove a pod which would lead to a failure during the -ExecStop directive of a systemd service referencing that pod. - -#### **--latest**, **-l** - -Instead of providing the pod name or ID, stop the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--pod-id-file** - -Read pod ID from the specified file and stop the pod. Can be specified multiple times. - -#### **--time**, **-t**=*seconds* - -Seconds to wait before forcibly stopping the containers in the pod. - -## EXAMPLE - -Stop a pod called *mywebserverpod* -``` -$ podman pod stop mywebserverpod -cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 -``` - -Stop two pods by their short IDs. -``` -$ podman pod stop 490eb 3557fb -490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5 -3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab -``` - -Stop the most recent pod -``` -$ podman pod stop --latest -3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab -``` - -Stop all pods -``` -$ podman pod stop --all -19456b4cd557eaf9629825113a552681a6013f8c8cad258e36ab825ef536e818 -3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab -490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5 -70c358daecf71ef9be8f62404f926080ca0133277ef7ce4f6aa2d5af6bb2d3e9 -cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 -``` - -Stop two pods via --pod-id-file -``` -$ podman pod stop --pod-id-file file1 --pod-id-file file2 -19456b4cd557eaf9629825113a552681a6013f8c8cad258e36ab825ef536e818 -cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 -``` - -Stop all pods with a timeout of 1 second. -``` -$ podman pod stop -a -t 1 -3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab -490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5 -70c358daecf71ef9be8f62404f926080ca0133277ef7ce4f6aa2d5af6bb2d3e9 -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-pod-start(1)](podman-pod-start.1.md)** - -## HISTORY -July 2018, Originally compiled by Peter Hunt diff --git a/docs/source/markdown/podman-pod-stop.1.md.in b/docs/source/markdown/podman-pod-stop.1.md.in new file mode 100644 index 000000000..879645cd9 --- /dev/null +++ b/docs/source/markdown/podman-pod-stop.1.md.in @@ -0,0 +1,84 @@ +% podman-pod-stop(1) + +## NAME +podman\-pod\-stop - Stop one or more pods + +## SYNOPSIS +**podman pod stop** [*options*] *pod* ... + +## DESCRIPTION +Stop containers in one or more pods. You may use pod IDs or names as input. + +## OPTIONS + +#### **--all**, **-a** + +Stops all pods + +#### **--ignore**, **-i** + +Ignore errors when specified pods are not in the container store. A user might +have decided to manually remove a pod which would lead to a failure during the +ExecStop directive of a systemd service referencing that pod. + +#### **--latest**, **-l** + +Instead of providing the pod name or ID, stop the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +@@option pod-id-file.pod + +#### **--time**, **-t**=*seconds* + +Seconds to wait before forcibly stopping the containers in the pod. + +## EXAMPLE + +Stop a pod called *mywebserverpod* +``` +$ podman pod stop mywebserverpod +cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 +``` + +Stop two pods by their short IDs. +``` +$ podman pod stop 490eb 3557fb +490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5 +3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab +``` + +Stop the most recent pod +``` +$ podman pod stop --latest +3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab +``` + +Stop all pods +``` +$ podman pod stop --all +19456b4cd557eaf9629825113a552681a6013f8c8cad258e36ab825ef536e818 +3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab +490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5 +70c358daecf71ef9be8f62404f926080ca0133277ef7ce4f6aa2d5af6bb2d3e9 +cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 +``` + +Stop two pods via --pod-id-file +``` +$ podman pod stop --pod-id-file file1 --pod-id-file file2 +19456b4cd557eaf9629825113a552681a6013f8c8cad258e36ab825ef536e818 +cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 +``` + +Stop all pods with a timeout of 1 second. +``` +$ podman pod stop -a -t 1 +3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab +490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5 +70c358daecf71ef9be8f62404f926080ca0133277ef7ce4f6aa2d5af6bb2d3e9 +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-pod-start(1)](podman-pod-start.1.md)** + +## HISTORY +July 2018, Originally compiled by Peter Hunt diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index cdfa9366a..077ad7a4a 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -496,10 +496,7 @@ Run container in an existing pod. If you want Podman to make the pod for you, pr To make a pod with more granular options, use the **podman pod create** command before creating a container. If a container is run with a pod, and the pod has an infra-container, the infra-container will be started before the container is. -#### **--pod-id-file**=*path* - -Run container in an existing pod and read the pod's ID from the specified file. -If a container is run within a pod, and the pod has an infra-container, the infra-container will be started before the container is. +@@option pod-id-file.container #### **--preserve-fds**=*N* -- cgit v1.2.3-54-g00ecf