diff options
Diffstat (limited to 'docs')
20 files changed, 92 insertions, 136 deletions
diff --git a/docs/README.md b/docs/README.md index 0f2af16d6..abe7d7758 100644 --- a/docs/README.md +++ b/docs/README.md @@ -13,7 +13,6 @@ link on that page. | ------------------------------------ | --------------------------- | | Markdown source for man pages | docs/source/markdown/ | | man pages aliases as .so files | docs/source/markdown/links/ | -| restructured text for readthedocs.io | docs/rst/ | | target for output | docs/build | | man pages | docs/build/man | | remote linux man pages | docs/build/remote/linux | @@ -60,16 +59,24 @@ incorrect, or the file isn't accessible for some other reason. ## Local Testing -Assuming that you have the [dependencies](https://podman.io/getting-started/installation#build-and-run-dependencies) +To build standard man pages, run `make docs`. Results will be in `docs/build/man`. + +To build HTMLized man pages: Assuming that you have the +[dependencies](https://podman.io/getting-started/installation#build-and-run-dependencies) installed, then also install (showing Fedora in the example): ``` -# dnf install python3-sphinx python3-recommonmark -# pip install sphinx-markdown-tables +$ sudo dnf install python3-sphinx python3-recommonmark +$ pip install sphinx-markdown-tables myst_parser ``` +(The above dependencies are current as of 2022-09-15. If you experience problems, +please see [requirements.txt](requirements.txt) in this directory, it will almost +certainly be more up-to-date than this README.) + After that completes, cd to the `docs` directory in your Podman sandbox and then do `make html`. You can then preview the html files in `docs/build/html` with: ``` python -m http.server 8000 --directory build/html ``` +...and point your web browser at `http://localhost:8000/` diff --git a/docs/source/conf.py b/docs/source/conf.py index b58bb3f46..345e289e1 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -86,12 +86,12 @@ def convert_markdown_title(app, docname, source): if docpath.endswith(".md"): # Convert pandoc title line into eval_rst block for myst_parser # - # Remove the ending "(1)" to avoid it from being displayed + # Remove the ending " 1" (section) to avoid it from being displayed # in the web tab. Often such a text indicates that # a web page got an update. For instance GitHub issues # shows the number of new comments that have been written # after the user's last visit. - source[0] = re.sub(r"^% (.*)(\(\d\))", r"```{title} \g<1>\n```", source[0]) + source[0] = re.sub(r"^% (.*)\s(\d)", r"```{title} \g<1>\n```", source[0]) def setup(app): app.connect("source-read", convert_markdown_title) diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore index 552e6f520..af4c5360b 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -20,12 +20,15 @@ podman-pod-kill.1.md podman-pod-logs.1.md podman-pod-rm.1.md podman-pod-start.1.md +podman-pod-stats.1.md podman-pod-stop.1.md podman-pull.1.md podman-push.1.md podman-rm.1.md podman-run.1.md podman-search.1.md +podman-start.1.md +podman-stats.1.md podman-stop.1.md podman-unpause.1.md podman-update.1.md diff --git a/docs/source/markdown/options/dns.md b/docs/source/markdown/options/dns.md new file mode 100644 index 000000000..39380ace2 --- /dev/null +++ b/docs/source/markdown/options/dns.md @@ -0,0 +1,11 @@ +#### **--dns**=*ipaddr* + +Set custom DNS servers. + +This option can be used to override the DNS +configuration passed to the container. Typically this is necessary when the +host DNS configuration is invalid for the container (e.g., **127.0.0.1**). When this +is the case the **--dns** flag is necessary for every run. + +The special value **none** can be specified to disable creation of _/etc/resolv.conf_ in the container by Podman. +The _/etc/resolv.conf_ file in the image will be used without changes. 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/no-reset.md b/docs/source/markdown/options/no-reset.md new file mode 100644 index 000000000..ce5b95057 --- /dev/null +++ b/docs/source/markdown/options/no-reset.md @@ -0,0 +1,3 @@ +#### **--no-reset** + +Do not clear the terminal/screen in between reporting intervals diff --git a/docs/source/markdown/options/no-stream.md b/docs/source/markdown/options/no-stream.md new file mode 100644 index 000000000..a9d548ba0 --- /dev/null +++ b/docs/source/markdown/options/no-stream.md @@ -0,0 +1,3 @@ +#### **--no-stream** + +Disable streaming <<|pod >>stats and only pull the first result, default setting 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/shm-size.md b/docs/source/markdown/options/shm-size.md new file mode 100644 index 000000000..18cafcb86 --- /dev/null +++ b/docs/source/markdown/options/shm-size.md @@ -0,0 +1,6 @@ +#### **--shm-size**=*number[unit]* + +Size of _/dev/shm_. A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes). +If you omit the unit, the system uses bytes. If you omit the size entirely, the default is **64m**. +When _size_ is **0**, there is no limit on the amount of memory used for IPC by the <<container|pod>>. +This option conflicts with **--ipc=host**. 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/options/user.md b/docs/source/markdown/options/user.md new file mode 100644 index 000000000..6cf12d347 --- /dev/null +++ b/docs/source/markdown/options/user.md @@ -0,0 +1,7 @@ +#### **--user**, **-u**=*user[:group]* + +Sets the username or UID used and, optionally, the groupname or GID for the specified command. Both *user* and *group* may be symbolic or numeric. + +Without this argument, the command will run as the user specified in the container image. Unless overridden by a `USER` command in the Containerfile or by a value passed to this option, this user generally defaults to root. + +When a user namespace is not in use, the UID and GID used within the container and on the host will match. When user namespaces are in use, however, the UID and GID in the container may correspond to another UID and GID on the host. In rootless containers, for example, a user namespace is always used, and root in the container will by default correspond to the UID and GID of the user invoking Podman. diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in index 2c636069f..e201806e5 100644 --- a/docs/source/markdown/podman-build.1.md.in +++ b/docs/source/markdown/podman-build.1.md.in @@ -223,18 +223,12 @@ specifying **--disable-compression=false**. @@option disable-content-trust -#### **--dns**=*dns* +@@option dns -Set custom DNS servers to be used during the build. +This option cannot be combined with **--network** that is set to **none**. -This option can be used to override the DNS configuration passed to the -container. Typically this is necessary when the host DNS configuration is -invalid for the container (e.g., 127.0.0.1). When this is the case the `--dns` -option is necessary for every run. - -The special value **none** can be specified to disable creation of -/etc/resolv.conf in the container by Podman. The /etc/resolv.conf file in the -image will be used without changes. +Note: this option takes effect only during *RUN* instructions in the build. +It does not affect _/etc/resolv.conf_ in the final image. #### **--dns-option**=*option* @@ -564,13 +558,7 @@ container - `seccomp=profile.json` : White listed syscalls seccomp Json file to be used as a seccomp filter -#### **--shm-size**=*size* - -Size of `/dev/shm`. The format is `<number><unit>`. `number` must be greater -than `0`. -Unit is optional and can be `b` (bytes), `k` (kibibytes), `m`(mebibytes), or -`g` (gibibytes). If you omit the unit, the system uses bytes. If you omit the -size entirely, the system uses `64m`. +@@option shm-size #### **--sign-by**=*fingerprint* diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index e407ff4d4..72f167a7e 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -141,17 +141,9 @@ flag to pass the user's supplementary group access into the container. @@option disable-content-trust -#### **--dns**=*dns* +@@option dns -Set custom DNS servers. Invalid if using **--dns** and **--network** that is set to 'none' or `container:<name|id>`. - -This option can be used to override the DNS -configuration passed to the container. Typically this is necessary when the -host DNS configuration is invalid for the container (e.g., 127.0.0.1). When this -is the case the **--dns** flag is necessary for every run. - -The special value **none** can be specified to disable creation of **/etc/resolv.conf** in the container by Podman. -The **/etc/resolv.conf** file in the image will be used without changes. +This option cannot be combined with **--network** that is set to **none** or **container:**_id_. @@option dns-opt.container @@ -224,9 +216,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 @@ -414,11 +404,7 @@ Note: Labeling can be disabled for all containers by setting label=false in the Note: Labeling can be disabled for all containers by setting label=false in the **containers.conf** (`/etc/containers/containers.conf` or `$HOME/.config/containers/containers.conf`) file. -#### **--shm-size**=*size* - -Size of `/dev/shm` (format: `<number>[<unit>]`, where unit = b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes)) -If you omit the unit, the system uses bytes. If you omit the size entirely, the system uses `64m`. -When size is `0`, there is no limit on the amount of memory used for IPC by the container. +@@option shm-size @@option stop-signal @@ -438,16 +424,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 @@ -461,14 +438,7 @@ standard input. @@option unsetenv-all -#### **--user**, **-u**=*user* - -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 ] - -Without this argument the command will be run as root in the container. +@@option user @@option userns.container diff --git a/docs/source/markdown/podman-exec.1.md.in b/docs/source/markdown/podman-exec.1.md.in index 0d161ef66..8198c319e 100644 --- a/docs/source/markdown/podman-exec.1.md.in +++ b/docs/source/markdown/podman-exec.1.md.in @@ -31,30 +31,20 @@ 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. - -#### **--user**, **-u** +@@option tty -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 user @@option workdir diff --git a/docs/source/markdown/podman-pod-clone.1.md.in b/docs/source/markdown/podman-pod-clone.1.md.in index 15f7ec208..90b829371 100644 --- a/docs/source/markdown/podman-pod-clone.1.md.in +++ b/docs/source/markdown/podman-pod-clone.1.md.in @@ -99,11 +99,7 @@ Note: Labeling can be disabled for all pods/containers by setting label=false in Note: Labeling can be disabled for all containers by setting label=false in the **containers.conf** (`/etc/containers/containers.conf` or `$HOME/.config/containers/containers.conf`) file. -#### **--shm-size**=*size* - -Size of `/dev/shm` (format: `<number>[<unit>]`, where unit = b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes)) -If the unit is omitted, the system uses bytes. If the size is omitted, the system uses `64m`. -When size is `0`, there is no limit on the amount of memory used for IPC by the pod. This option conflicts with **--ipc=host** when running containers. +@@option shm-size #### **--start** diff --git a/docs/source/markdown/podman-pod-create.1.md.in b/docs/source/markdown/podman-pod-create.1.md.in index b3c13533a..7700f5e62 100644 --- a/docs/source/markdown/podman-pod-create.1.md.in +++ b/docs/source/markdown/podman-pod-create.1.md.in @@ -213,11 +213,7 @@ This boolean determines whether or not all containers entering the pod will use Note: This options conflict with **--share=cgroup** since that would set the pod as the cgroup parent but enter the container into the same cgroupNS as the infra container. -#### **--shm-size**=*size* - -Size of `/dev/shm` (format: `<number>[<unit>]`, where unit = b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes)) -If the unit is omitted, the system uses bytes. If the size is omitted, the system uses `64m`. -When size is `0`, there is no limit on the amount of memory used for IPC by the pod. This option conflicts with **--ipc=host** when running containers. +@@option shm-size @@option subgidname diff --git a/docs/source/markdown/podman-pod-stats.1.md b/docs/source/markdown/podman-pod-stats.1.md.in index c71159f09..83a4b7a1e 100644 --- a/docs/source/markdown/podman-pod-stats.1.md +++ b/docs/source/markdown/podman-pod-stats.1.md.in @@ -40,13 +40,9 @@ When using a GO template, you may precede the format with `table` to print heade Instead of providing the pod name or ID, use the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) -#### **--no-reset** +@@option no-reset -Do not clear the terminal/screen in between reporting intervals - -#### **--no-stream** - -Disable streaming pod stats and only pull the first result, default setting is false +@@option no-stream ## EXAMPLE diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index d9dcd60f9..37d052646 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -177,17 +177,9 @@ flag to pass the user's supplementary group access into the container. @@option disable-content-trust -#### **--dns**=*ipaddr* +@@option dns -Set custom DNS servers. Invalid if using **--dns** with **--network** that is set to **none** or **container:**_id_. - -This option can be used to override the DNS -configuration passed to the container. Typically this is necessary when the -host DNS configuration is invalid for the container (e.g., **127.0.0.1**). When this -is the case the **--dns** flag is necessary for every run. - -The special value **none** can be specified to disable creation of _/etc/resolv.conf_ in the container by Podman. -The _/etc/resolv.conf_ file in the image will be used without changes. +This option cannot be combined with **--network** that is set to **none** or **container:**_id_. @@option dns-opt.container @@ -245,9 +237,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 +356,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 @@ -450,11 +437,7 @@ Note: Labeling can be disabled for all containers by setting label=false in the Note: Labeling can be disabled for all containers by setting **label=false** in the **containers.conf**(5) file. -#### **--shm-size**=*number[unit]* - -Size of _/dev/shm_. A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes). -If you omit the unit, the system uses bytes. If you omit the size entirely, the default is **64m**. -When _size_ is **0**, there is no limit on the amount of memory used for IPC by the container. +@@option shm-size #### **--sig-proxy** @@ -478,15 +461,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 @@ -504,13 +479,7 @@ echo "asdf" | podman run --rm -i someimage /bin/cat @@option unsetenv-all -#### **--user**, **-u**=*user[:group]* - -Sets the username or UID used and, optionally, the groupname or GID for the specified command. Both *user* and *group* may be symbolic or numeric. - -Without this argument, the command will run as the user specified in the container image. Unless overridden by a `USER` command in the Containerfile or by a value passed to this option, this user generally defaults to root. - -When a user namespace is not in use, the UID and GID used within the container and on the host will match. When user namespaces are in use, however, the UID and GID in the container may correspond to another UID and GID on the host. In rootless containers, for example, a user namespace is always used, and root in the container will by default correspond to the UID and GID of the user invoking Podman. +@@option user @@option userns.container diff --git a/docs/source/markdown/podman-start.1.md b/docs/source/markdown/podman-start.1.md.in index fd24c6bf4..6fa41018b 100644 --- a/docs/source/markdown/podman-start.1.md +++ b/docs/source/markdown/podman-start.1.md.in @@ -53,9 +53,7 @@ Valid filters are listed below: | 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. +@@option interactive #### **--latest**, **-l** diff --git a/docs/source/markdown/podman-stats.1.md b/docs/source/markdown/podman-stats.1.md.in index a1a0f6a93..f06bd3fcc 100644 --- a/docs/source/markdown/podman-stats.1.md +++ b/docs/source/markdown/podman-stats.1.md.in @@ -53,13 +53,9 @@ Time in seconds between stats reports, defaults to 5 seconds. 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) -#### **--no-reset** +@@option no-reset -Do not clear the terminal/screen in between reporting intervals - -#### **--no-stream** - -Disable streaming stats and only pull the first result, default setting is false +@@option no-stream #### **--no-trunc** |