From c64a6ba07205c2f9fa2a874d9343babf68ee21d2 Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Tue, 23 Aug 2022 17:40:46 -0600 Subject: Man pages: Refactor common options: --workdir I chose the version from podman-run because it is the most up-to-date, and most correct wrt current syntax guidelines. Differences are in arg description, language, and asterisks. Signed-off-by: Ed Santiago --- docs/source/markdown/.gitignore | 1 + docs/source/markdown/options/workdir.md | 7 ++ docs/source/markdown/podman-create.1.md.in | 8 +- docs/source/markdown/podman-exec.1.md | 121 ----------------------------- docs/source/markdown/podman-exec.1.md.in | 115 +++++++++++++++++++++++++++ docs/source/markdown/podman-run.1.md.in | 8 +- 6 files changed, 125 insertions(+), 135 deletions(-) create mode 100644 docs/source/markdown/options/workdir.md delete mode 100644 docs/source/markdown/podman-exec.1.md create mode 100644 docs/source/markdown/podman-exec.1.md.in diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore index 2bdcce197..85aed3be0 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -3,6 +3,7 @@ podman-build.1.md podman-container-clone.1.md podman-container-runlabel.1.md podman-create.1.md +podman-exec.1.md podman-image-sign.1.md podman-kill.1.md podman-kube-play.1.md diff --git a/docs/source/markdown/options/workdir.md b/docs/source/markdown/options/workdir.md new file mode 100644 index 000000000..12f3ddd44 --- /dev/null +++ b/docs/source/markdown/options/workdir.md @@ -0,0 +1,7 @@ +#### **--workdir**, **-w**=*dir* + +Working directory inside the container. + +The default working directory for running binaries within a container is the root directory (**/**). +The image developer can set a different default with the WORKDIR instruction. The operator +can override the working directory by using the **-w** option. diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 9518568bb..8710af110 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -975,13 +975,7 @@ If the location of the volume from the source container overlaps with data residing on a target container, then the volume hides that data on the target. -#### **--workdir**, **-w**=*dir* - -Working directory inside the container - -The default working directory for running binaries within a container is the root directory (/). -The image developer can set a different default with the WORKDIR instruction. The operator -can override the working directory by using the **-w** option. +@@option workdir ## EXAMPLES diff --git a/docs/source/markdown/podman-exec.1.md b/docs/source/markdown/podman-exec.1.md deleted file mode 100644 index da61f3456..000000000 --- a/docs/source/markdown/podman-exec.1.md +++ /dev/null @@ -1,121 +0,0 @@ -% podman-exec(1) - -## NAME -podman\-exec - Execute a command in a running container - -## SYNOPSIS -**podman exec** [*options*] *container* [*command* [*arg* ...]] - -**podman container exec** [*options*] *container* [*command* [*arg* ...]] - -## DESCRIPTION -**podman exec** executes a command in a running container. - -## OPTIONS - -#### **--detach**, **-d** - -Start the exec session, but do not attach to it. The command will run in the background and the exec session will be automatically removed when it completes. The **podman exec** command will print the ID of the exec session and exit immediately after it starts. - -#### **--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*. - -#### **--env**, **-e**=*env* - -Set environment variables. - -This option allows arbitrary environment variables that are available for the process to be launched inside of the container. If an environment variable is specified without a value, Podman will check the host environment for a value and set the variable only if it is set on the host. As a special case, if an environment variable ending in __*__ is specified without a value, Podman will search the host environment for variables starting with the prefix and will add those variables to the container. - -#### **--env-file**=*file* - -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*. - -#### **--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. - -#### **--privileged** - -Give extended privileges to this container. The default is *false*. - -By default, Podman containers are -"unprivileged" and cannot, for example, modify parts of the operating system. -This is because by default a container is only allowed limited access to devices. -A "privileged" container is given the same access to devices as the user launching the container. - -A privileged container turns off the security features that isolate the -container from the host. Dropped Capabilities, limited devices, read/only mount -points, Apparmor/SELinux separation, and Seccomp filters are all disabled. - -Rootless containers cannot have more privileges than the account that launched them. - - -#### **--tty**, **-t** - -Allocate a pseudo-TTY. - -#### **--user**, **-u** - -Sets the username or UID used and optionally the groupname or GID for the specified command. -The following examples are all valid: ---user [user | user:group | uid | uid:gid | user:gid | uid:group ] - -#### **--workdir**, **-w**=*path* - -Working directory inside the container - -The default working directory for running binaries within a container is the root directory (/). -The image developer can set a different default with the WORKDIR instruction, which can be overridden -when creating the container. - -## Exit Status - -The exit code from `podman exec` gives information about why the command within the container failed to run or why it exited. When `podman exec` exits with a -non-zero code, the exit codes follow the `chroot` standard, see below: - - **125** The error is with Podman itself - - $ podman exec --foo ctrID /bin/sh; echo $? - Error: unknown flag: --foo - 125 - - **126** The _contained command_ cannot be invoked - - $ podman exec ctrID /etc; echo $? - Error: container_linux.go:346: starting container process caused "exec: \"/etc\": permission denied": OCI runtime error - 126 - - **127** The _contained command_ cannot be found - - $ podman exec ctrID foo; echo $? - Error: container_linux.go:346: starting container process caused "exec: \"foo\": executable file not found in $PATH": OCI runtime error - 127 - - **Exit code** The _contained command_ exit code - - $ podman exec ctrID /bin/sh -c 'exit 3'; echo $? - 3 - -## EXAMPLES - -``` -$ podman exec -it ctrID ls -$ podman exec -it -w /tmp myCtr pwd -$ podman exec --user root ctrID ls -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-run(1)](podman-run.1.md)** - -## HISTORY -December 2017, Originally compiled by Brent Baude diff --git a/docs/source/markdown/podman-exec.1.md.in b/docs/source/markdown/podman-exec.1.md.in new file mode 100644 index 000000000..4f78f1c31 --- /dev/null +++ b/docs/source/markdown/podman-exec.1.md.in @@ -0,0 +1,115 @@ +% podman-exec(1) + +## NAME +podman\-exec - Execute a command in a running container + +## SYNOPSIS +**podman exec** [*options*] *container* [*command* [*arg* ...]] + +**podman container exec** [*options*] *container* [*command* [*arg* ...]] + +## DESCRIPTION +**podman exec** executes a command in a running container. + +## OPTIONS + +#### **--detach**, **-d** + +Start the exec session, but do not attach to it. The command will run in the background and the exec session will be automatically removed when it completes. The **podman exec** command will print the ID of the exec session and exit immediately after it starts. + +#### **--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*. + +#### **--env**, **-e**=*env* + +Set environment variables. + +This option allows arbitrary environment variables that are available for the process to be launched inside of the container. If an environment variable is specified without a value, Podman will check the host environment for a value and set the variable only if it is set on the host. As a special case, if an environment variable ending in __*__ is specified without a value, Podman will search the host environment for variables starting with the prefix and will add those variables to the container. + +#### **--env-file**=*file* + +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*. + +#### **--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. + +#### **--privileged** + +Give extended privileges to this container. The default is *false*. + +By default, Podman containers are +"unprivileged" and cannot, for example, modify parts of the operating system. +This is because by default a container is only allowed limited access to devices. +A "privileged" container is given the same access to devices as the user launching the container. + +A privileged container turns off the security features that isolate the +container from the host. Dropped Capabilities, limited devices, read/only mount +points, Apparmor/SELinux separation, and Seccomp filters are all disabled. + +Rootless containers cannot have more privileges than the account that launched them. + + +#### **--tty**, **-t** + +Allocate a pseudo-TTY. + +#### **--user**, **-u** + +Sets the username or UID used and optionally the groupname or GID for the specified command. +The following examples are all valid: +--user [user | user:group | uid | uid:gid | user:gid | uid:group ] + +@@option workdir + +## Exit Status + +The exit code from `podman exec` gives information about why the command within the container failed to run or why it exited. When `podman exec` exits with a +non-zero code, the exit codes follow the `chroot` standard, see below: + + **125** The error is with Podman itself + + $ podman exec --foo ctrID /bin/sh; echo $? + Error: unknown flag: --foo + 125 + + **126** The _contained command_ cannot be invoked + + $ podman exec ctrID /etc; echo $? + Error: container_linux.go:346: starting container process caused "exec: \"/etc\": permission denied": OCI runtime error + 126 + + **127** The _contained command_ cannot be found + + $ podman exec ctrID foo; echo $? + Error: container_linux.go:346: starting container process caused "exec: \"foo\": executable file not found in $PATH": OCI runtime error + 127 + + **Exit code** The _contained command_ exit code + + $ podman exec ctrID /bin/sh -c 'exit 3'; echo $? + 3 + +## EXAMPLES + +``` +$ podman exec -it ctrID ls +$ podman exec -it -w /tmp myCtr pwd +$ podman exec --user root ctrID ls +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-run(1)](podman-run.1.md)** + +## HISTORY +December 2017, Originally compiled by Brent Baude diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index 3e31ccc45..a0cd49d4e 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -1034,13 +1034,7 @@ If the location of the volume from the source container overlaps with data residing on a target container, then the volume hides that data on the target. -#### **--workdir**, **-w**=*dir* - -Working directory inside the container. - -The default working directory for running binaries within a container is the root directory (**/**). -The image developer can set a different default with the WORKDIR instruction. The operator -can override the working directory by using the **-w** option. +@@option workdir ## Exit Status -- cgit v1.2.3-54-g00ecf