From b6c75a3cc572b9a8299aaad5af287ec82c424ba8 Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Tue, 13 Sep 2022 13:49:24 -0600 Subject: Man pages: refactor common options: --preserve-fds, -it Three simple options shared among podman-create, exec, run. I mostly went with the podman-run versions. For --tty, this means that create and exec get the long stdout/stderr note. (The example, though, remains only in podman-run). For -i, mostly boldspace changes. For --preserve-fds, podman-exec now has the "not with remote" note (which it didn't until now) Signed-off-by: Ed Santiago --- docs/source/markdown/.gitignore | 1 + docs/source/markdown/options/interactive.md | 3 + docs/source/markdown/options/preserve-fds.md | 5 ++ docs/source/markdown/options/tty.md | 9 +++ docs/source/markdown/podman-create.1.md.in | 15 +---- docs/source/markdown/podman-exec.1.md.in | 12 +--- docs/source/markdown/podman-run.1.md.in | 19 +------ docs/source/markdown/podman-start.1.md | 83 ---------------------------- docs/source/markdown/podman-start.1.md.in | 81 +++++++++++++++++++++++++++ 9 files changed, 107 insertions(+), 121 deletions(-) create mode 100644 docs/source/markdown/options/interactive.md create mode 100644 docs/source/markdown/options/preserve-fds.md create mode 100644 docs/source/markdown/options/tty.md delete mode 100644 docs/source/markdown/podman-start.1.md create mode 100644 docs/source/markdown/podman-start.1.md.in diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore index 552e6f520..69911b5b8 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -26,6 +26,7 @@ podman-push.1.md podman-rm.1.md podman-run.1.md podman-search.1.md +podman-start.1.md podman-stop.1.md podman-unpause.1.md podman-update.1.md diff --git a/docs/source/markdown/options/interactive.md b/docs/source/markdown/options/interactive.md new file mode 100644 index 000000000..a28088368 --- /dev/null +++ b/docs/source/markdown/options/interactive.md @@ -0,0 +1,3 @@ +#### **--interactive**, **-i** + +When set to **true**, keep stdin open even if not attached. The default is **false**. diff --git a/docs/source/markdown/options/preserve-fds.md b/docs/source/markdown/options/preserve-fds.md new file mode 100644 index 000000000..61e33bdf4 --- /dev/null +++ b/docs/source/markdown/options/preserve-fds.md @@ -0,0 +1,5 @@ +#### **--preserve-fds**=*N* + +Pass down to the process N additional file descriptors (in addition to 0, 1, 2). +The total FDs will be 3+N. +(This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) diff --git a/docs/source/markdown/options/tty.md b/docs/source/markdown/options/tty.md new file mode 100644 index 000000000..04bd8af2c --- /dev/null +++ b/docs/source/markdown/options/tty.md @@ -0,0 +1,9 @@ +#### **--tty**, **-t** + +Allocate a pseudo-TTY. The default is **false**. + +When set to **true**, Podman will allocate a pseudo-tty and attach to the standard +input of the container. This can be used, for example, to run a throwaway +interactive shell. + +**NOTE**: The --tty flag prevents redirection of standard output. It combines STDOUT and STDERR, it can insert control characters, and it can hang pipes. This option should only be used when run interactively in a terminal. When feeding input to Podman, use -i only, not -it. diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index e407ff4d4..44e524dd6 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -224,9 +224,7 @@ pod when that pod is not running. @@option init-path -#### **--interactive**, **-i** - -Keep STDIN open even if not attached. The default is *false*. +@@option interactive @@option ip @@ -438,16 +436,7 @@ When size is `0`, there is no limit on the amount of memory used for IPC by the @@option tmpfs -#### **--tty**, **-t** - -Allocate a pseudo-TTY. The default is *false*. - -When set to true Podman will allocate a pseudo-tty and attach to the standard -input of the container. This can be used, for example, to run a throwaway -interactive shell. The default is false. - -Note: The **-t** option is incompatible with a redirection of the Podman client -standard input. +@@option tty @@option tz diff --git a/docs/source/markdown/podman-exec.1.md.in b/docs/source/markdown/podman-exec.1.md.in index 0d161ef66..a3931df1d 100644 --- a/docs/source/markdown/podman-exec.1.md.in +++ b/docs/source/markdown/podman-exec.1.md.in @@ -31,24 +31,18 @@ This option allows arbitrary environment variables that are available for the pr Read in a line delimited file of environment variables. -#### **--interactive**, **-i** - -When set to true, keep stdin open even if not attached. The default is *false*. +@@option interactive #### **--latest**, **-l** Instead of providing the container name or ID, use the last created container. If you use methods other than Podman to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) -#### **--preserve-fds**=*N* - -Pass down to the process N additional file descriptors (in addition to 0, 1, 2). The total FDs will be 3+N. +@@option preserve-fds @@option privileged -#### **--tty**, **-t** - -Allocate a pseudo-TTY. +@@option tty #### **--user**, **-u** diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index d9dcd60f9..96605ee3f 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -245,9 +245,7 @@ Print usage statement @@option init-path -#### **--interactive**, **-i** - -When set to **true**, keep stdin open even if not attached. The default is **false**. +@@option interactive @@option ip @@ -366,10 +364,7 @@ If a container is run with a pod, and the pod has an infra-container, the infra- @@option pod-id-file.container -#### **--preserve-fds**=*N* - -Pass down to the process N additional file descriptors (in addition to 0, 1, 2). -The total FDs will be 3+N. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) +@@option preserve-fds @@option privileged @@ -478,15 +473,7 @@ Sets whether the signals sent to the **podman run** command are proxied to the c @@option tmpfs -#### **--tty**, **-t** - -Allocate a pseudo-TTY. The default is **false**. - -When set to **true**, Podman will allocate a pseudo-tty and attach to the standard -input of the container. This can be used, for example, to run a throwaway -interactive shell. The default is **false**. - -**NOTE**: The --tty flag prevents redirection of standard output. It combines STDOUT and STDERR, it can insert control characters, and it can hang pipes. This option should only be used when run interactively in a terminal. When feeding input to Podman, use -i only, not -it. +@@option tty ``` echo "asdf" | podman run --rm -i someimage /bin/cat diff --git a/docs/source/markdown/podman-start.1.md b/docs/source/markdown/podman-start.1.md deleted file mode 100644 index fd24c6bf4..000000000 --- a/docs/source/markdown/podman-start.1.md +++ /dev/null @@ -1,83 +0,0 @@ -% podman-start 1 - -## NAME -podman\-start - Start one or more containers - -## SYNOPSIS -**podman start** [*options*] *container* ... - -**podman container start** [*options*] *container* ... - -## DESCRIPTION -Start one or more containers. You may use container IDs or names as input. The *attach* and *interactive* -options cannot be used to override the *--tty* and *--interactive* options from when the container -was created. If you attempt to start a running container with the *--attach* option, podman will simply -attach to the container. - -## OPTIONS - -#### **--all** - -Start all the containers created by Podman, default is only running containers. - -#### **--attach**, **-a** - -Attach container's STDOUT and STDERR. The default is false. This option cannot be used when -starting multiple containers. - -#### **--detach-keys**=*sequence* - -Specify the key sequence for detaching a container. Format is a single character `[a-Z]` or one or more `ctrl-` characters where `` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. Specifying "" will disable this feature. The default is *ctrl-p,ctrl-q*. - -#### **--filter**, **-f** - -Filter what containers are going to be started from the given arguments. -Multiple filters can be given with multiple uses of the --filter flag. -Filters with the same key work inclusive with the only exception being -`label` which is exclusive. Filters with different keys always work exclusive. - -Valid filters are listed below: - -| **Filter** | **Description** | -| --------------- | -------------------------------------------------------------------------------- | -| id | [ID] Container's ID (accepts regex) | -| name | [Name] Container's name (accepts regex) | -| label | [Key] or [Key=Value] Label assigned to a container | -| exited | [Int] Container's exit code | -| status | [Status] Container's status: 'created', 'exited', 'paused', 'running', 'unknown' | -| ancestor | [ImageName] Image or descendant used to create container | -| before | [ID] or [Name] Containers created before this container | -| since | [ID] or [Name] Containers created since this container | -| volume | [VolumeName] or [MountpointDestination] Volume mounted in container | -| health | [Status] healthy or unhealthy | -| pod | [Pod] name or full or partial ID of pod | -| network | [Network] name or full ID of network | - -#### **--interactive**, **-i** - -Attach container's STDIN. The default is false. - -#### **--latest**, **-l** - -Instead of providing the container name or ID, use the last created container. If you use methods other than Podman -to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--sig-proxy** - -Proxy received signals to the process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied. The default is *true* when attaching, *false* otherwise. - -## EXAMPLE - -podman start mywebserver - -podman start 860a4b231279 5421ab43b45 - -podman start --interactive --attach 860a4b231279 - -podman start -i -l - -## SEE ALSO -**[podman(1)](podman.1.md)** - -## HISTORY -November 2018, Originally compiled by Brent Baude diff --git a/docs/source/markdown/podman-start.1.md.in b/docs/source/markdown/podman-start.1.md.in new file mode 100644 index 000000000..6fa41018b --- /dev/null +++ b/docs/source/markdown/podman-start.1.md.in @@ -0,0 +1,81 @@ +% podman-start 1 + +## NAME +podman\-start - Start one or more containers + +## SYNOPSIS +**podman start** [*options*] *container* ... + +**podman container start** [*options*] *container* ... + +## DESCRIPTION +Start one or more containers. You may use container IDs or names as input. The *attach* and *interactive* +options cannot be used to override the *--tty* and *--interactive* options from when the container +was created. If you attempt to start a running container with the *--attach* option, podman will simply +attach to the container. + +## OPTIONS + +#### **--all** + +Start all the containers created by Podman, default is only running containers. + +#### **--attach**, **-a** + +Attach container's STDOUT and STDERR. The default is false. This option cannot be used when +starting multiple containers. + +#### **--detach-keys**=*sequence* + +Specify the key sequence for detaching a container. Format is a single character `[a-Z]` or one or more `ctrl-` characters where `` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. Specifying "" will disable this feature. The default is *ctrl-p,ctrl-q*. + +#### **--filter**, **-f** + +Filter what containers are going to be started from the given arguments. +Multiple filters can be given with multiple uses of the --filter flag. +Filters with the same key work inclusive with the only exception being +`label` which is exclusive. Filters with different keys always work exclusive. + +Valid filters are listed below: + +| **Filter** | **Description** | +| --------------- | -------------------------------------------------------------------------------- | +| id | [ID] Container's ID (accepts regex) | +| name | [Name] Container's name (accepts regex) | +| label | [Key] or [Key=Value] Label assigned to a container | +| exited | [Int] Container's exit code | +| status | [Status] Container's status: 'created', 'exited', 'paused', 'running', 'unknown' | +| ancestor | [ImageName] Image or descendant used to create container | +| before | [ID] or [Name] Containers created before this container | +| since | [ID] or [Name] Containers created since this container | +| volume | [VolumeName] or [MountpointDestination] Volume mounted in container | +| health | [Status] healthy or unhealthy | +| pod | [Pod] name or full or partial ID of pod | +| network | [Network] name or full ID of network | + +@@option interactive + +#### **--latest**, **-l** + +Instead of providing the container name or ID, use the last created container. If you use methods other than Podman +to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +#### **--sig-proxy** + +Proxy received signals to the process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied. The default is *true* when attaching, *false* otherwise. + +## EXAMPLE + +podman start mywebserver + +podman start 860a4b231279 5421ab43b45 + +podman start --interactive --attach 860a4b231279 + +podman start -i -l + +## SEE ALSO +**[podman(1)](podman.1.md)** + +## HISTORY +November 2018, Originally compiled by Brent Baude -- cgit v1.2.3-54-g00ecf