diff options
Diffstat (limited to 'docs')
38 files changed, 429 insertions, 198 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..57a64e1c1 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -1,3 +1,4 @@ +podman-attach.1.md podman-auto-update.1.md podman-build.1.md podman-container-clone.1.md @@ -20,12 +21,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-opt.container.md b/docs/source/markdown/options/dns-opt.container.md deleted file mode 100644 index ea26fd013..000000000 --- a/docs/source/markdown/options/dns-opt.container.md +++ /dev/null @@ -1,3 +0,0 @@ -#### **--dns-opt**=*option* - -Set custom DNS options. Invalid if using **--dns-opt** with **--network** that is set to **none** or **container:**_id_. diff --git a/docs/source/markdown/options/dns-option.container.md b/docs/source/markdown/options/dns-option.container.md new file mode 100644 index 000000000..cfbded5e6 --- /dev/null +++ b/docs/source/markdown/options/dns-option.container.md @@ -0,0 +1,3 @@ +#### **--dns-option**=*option* + +Set custom DNS options. Invalid if using **--dns-option** with **--network** that is set to **none** or **container:**_id_. 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/sig-proxy.md b/docs/source/markdown/options/sig-proxy.md new file mode 100644 index 000000000..bb940aed3 --- /dev/null +++ b/docs/source/markdown/options/sig-proxy.md @@ -0,0 +1,3 @@ +#### **--sig-proxy** + +Proxy received signals to the container process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied. 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-attach.1.md b/docs/source/markdown/podman-attach.1.md.in index c073fccf8..427f764dc 100644 --- a/docs/source/markdown/podman-attach.1.md +++ b/docs/source/markdown/podman-attach.1.md.in @@ -28,9 +28,8 @@ The default is **false**.\ Do not attach STDIN. The default is **false**. -#### **--sig-proxy** +@@option sig-proxy -Proxy received signals to the process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied.\ The default is **true**. ## EXAMPLES diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in index 2c636069f..e1ef13a0d 100644 --- a/docs/source/markdown/podman-build.1.md.in +++ b/docs/source/markdown/podman-build.1.md.in @@ -145,6 +145,10 @@ Limit the use of cached images to only consider images with created timestamps l For example if `--cache-ttl=1h` is specified, Buildah will only consider intermediate cache images which are created under the duration of one hour, and intermediate cache images outside this duration will be ignored. +Note: Setting `--cache-ttl=0` manually is equivalent to using `--no-cache` in the +implementation since this would effectively mean that user is not willing to use +cache at all. + #### **--cap-add**=*CAP\_xxx* When executing RUN instructions, run the command specified in the instruction @@ -223,18 +227,12 @@ specifying **--disable-compression=false**. @@option disable-content-trust -#### **--dns**=*dns* - -Set custom DNS servers to be used during the build. +@@option dns -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. +This option cannot be combined with **--network** that is set to **none**. -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,18 +562,16 @@ 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* Sign the image using a GPG key with the specified FINGERPRINT. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines,) +#### **--skip-unused-stages** + +Skip stages in multi-stage builds which don't affect the target stage. (Default: **true**). + #### **--squash** Squash all of the image's new layers into a single new layer; any preexisting diff --git a/docs/source/markdown/podman-container-inspect.1.md b/docs/source/markdown/podman-container-inspect.1.md index f92eea7bd..7157a3ec0 100644 --- a/docs/source/markdown/podman-container-inspect.1.md +++ b/docs/source/markdown/podman-container-inspect.1.md @@ -18,6 +18,50 @@ all results in a JSON array. If a format is specified, the given template will b Format the output using the given Go template. The keys of the returned JSON can be used as the values for the --format flag (see examples below). +Valid placeholders for the Go template are listed below: + +| **Placeholder** | **Description** | +| ----------------- | ------------------ | +| .AppArmorProfile | AppArmor profile (string) | +| .Args | Command-line arguments (array of strings) | +| .BoundingCaps | Bounding capability set (array of strings) | +| .Config ... | Structure with config info | +| .ConmonPidFile | Path to file containing conmon pid (string) | +| .Created | Container creation time (string, ISO3601) | +| .Dependencies | Dependencies (array of strings) | +| .Driver | Storage driver (string) | +| .EffectiveCaps | Effective capability set (array of strings) | +| .ExecIDs | Exec IDs (array of strings) | +| .GraphDriver ... | Further details of graph driver (struct) | +| .HostConfig ... | Host config details (struct) | +| .HostnamePath | Path to file containing hostname (string) | +| .HostsPath | Path to container /etc/hosts file (string) | +| .ID | Container ID (full 64-char hash) | +| .Image | Container image ID (64-char hash) | +| .ImageName | Container image name (string) | +| .IsInfra | Is this an infra container? (string: true/false) | +| .IsService | Is this a service container? (string: true/false) | +| .MountLabel | SELinux label of mount (string) | +| .Mounts | Mounts (array of strings) | +| .Name | Container name (string) | +| .Namespace | Container namespace (string) | +| .NetworkSettings ... | Network settings (struct) | +| .OCIConfigPath | Path to OCI config file (string) | +| .OCIRuntime | OCI runtime name (string) | +| .Path | Path to container command (string) | +| .PidFile | Path to file containing container PID (string) | +| .Pod | Parent pod (string) | +| .ProcessLabel | SELinux label of process (string) | +| .ResolvConfPath | Path to container's resolv.conf file (string) | +| .RestartCount | Number of times container has been restarted (int) | +| .Rootfs | Container rootfs (string) | +| .SizeRootFs | Size of rootfs, in bytes [1] | +| .SizeRw | Size of upper (R/W) container layer, in bytes [1] | +| .State ... | Container state info (struct) | +| .StaticDir | Path to container metadata dir (string) | + +[1] This format specifier requires the **--size** option + #### **--latest**, **-l** Instead of providing the container name or ID, use the last created container. If you use methods other than Podman diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index e407ff4d4..742a32b5a 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -141,19 +141,11 @@ 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 cannot be combined 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. - -@@option dns-opt.container +@@option dns-option.container @@option dns-search.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 @@ -275,7 +265,7 @@ This option is currently supported only by the **journald** log driver. #### **--network**=*mode*, **--net** -Set the network mode for the container. Invalid if using **--dns**, **--dns-opt**, or **--dns-search** with **--network** set to **none** or **container:**_id_. If used together with **--pod**, the container will not join the pod's network namespace. +Set the network mode for the container. Invalid if using **--dns**, **--dns-option**, or **--dns-search** with **--network** set to **none** or **container:**_id_. If used together with **--pod**, the container will not join the pod's network namespace. Valid _mode_ values are: @@ -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-events.1.md b/docs/source/markdown/podman-events.1.md index d0c95fe06..dd62ef5a2 100644 --- a/docs/source/markdown/podman-events.1.md +++ b/docs/source/markdown/podman-events.1.md @@ -95,6 +95,20 @@ In the case where an ID is used, the ID may be in its full or shortened form. Format the output to JSON Lines or using the given Go template. +| **Placeholder** | **Description** | +|--------------------|-----------------------------------------------| +| .Attributes | created_at, _by, labels, and more (map[]) | +| .ContainerExitCode | Exit code (int) | +| .Details ... | Internal structure, not actually useful | +| .HealthStatus | Health Status (string) | +| .ID | Container ID (full 64-bit SHA) | +| .Image | Name of image being run (string) | +| .Name | Container name (string) | +| .Network | Name of network being used (string) | +| .Status | Event status (e.g., create, start, died, ...) | +| .Time | Event timestamp (string) | +| .Type | Event type (e.g., image, container, pod, ...) | + #### **--help** Print usage statement. 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-generate-systemd.1.md b/docs/source/markdown/podman-generate-systemd.1.md index b733cff8d..190b21b71 100644 --- a/docs/source/markdown/podman-generate-systemd.1.md +++ b/docs/source/markdown/podman-generate-systemd.1.md @@ -141,7 +141,8 @@ RequiresMountsFor=/var/run/container/storage [Service] Restart=always ExecStart=/usr/bin/podman start de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6 -ExecStop=/usr/bin/podman stop -t 1 de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6 +ExecStop=/usr/bin/podman stop \ + -t 1 de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6 KillMode=none Type=forking PIDFile=/run/user/1000/overlay-containers/de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6/userdata/conmon.pid @@ -171,14 +172,19 @@ RequiresMountsFor=/var/run/container/storage Environment=PODMAN_SYSTEMD_UNIT=%n Restart=on-failure ExecStartPre=/bin/rm -f %t/%n-pid %t/%n-cid -ExecStart=/usr/local/bin/podman run - --conmon-pidfile %t/%n-pid - --cidfile %t/%n-cid - --cgroups=no-conmon - -d +ExecStart=/usr/local/bin/podman run \ + --conmon-pidfile %t/%n-pid \ + --cidfile %t/%n-cid \ + --cgroups=no-conmon \ + -d \ -dit alpine -ExecStop=/usr/local/bin/podman stop --ignore --cidfile %t/%n-cid -t 10 -ExecStopPost=/usr/local/bin/podman rm --ignore -f --cidfile %t/%n-cid +ExecStop=/usr/local/bin/podman stop \ + --ignore \ + --cidfile %t/%n-cid -t 10 +ExecStopPost=/usr/local/bin/podman rm \ + --ignore \ + -f \ + --cidfile %t/%n-cid PIDFile=%t/%n-pid KillMode=none Type=forking @@ -217,7 +223,8 @@ RequiresMountsFor=/var/run/container/storage [Service] Restart=on-failure ExecStart=/usr/bin/podman start 77a818221650-infra -ExecStop=/usr/bin/podman stop -t 10 77a818221650-infra +ExecStop=/usr/bin/podman stop \ + -t 10 77a818221650-infra KillMode=none Type=forking PIDFile=/run/user/1000/overlay-containers/ccfd5c71a088768774ca7bd05888d55cc287698dde06f475c8b02f696a25adcd/userdata/conmon.pid diff --git a/docs/source/markdown/podman-info.1.md b/docs/source/markdown/podman-info.1.md index b0e4d68c0..f892c2d7d 100644 --- a/docs/source/markdown/podman-info.1.md +++ b/docs/source/markdown/podman-info.1.md @@ -19,6 +19,16 @@ Displays information pertinent to the host, current storage stats, configured co Change output format to "json" or a Go template. +| **Placeholder** | **Info pertaining to ...** | +| ------------------- | --------------------------------------- | +| .Host ... | ...the host on which podman is running | +| .Plugins ... | ...external plugins | +| .Registries ... | ...configured registries | +| .Store ... | ...the storage driver and paths | +| .Version ... | ...podman version | + +Each of the above branch out into further subfields, more than can +reasonably be enumerated in this document. ## EXAMPLES diff --git a/docs/source/markdown/podman-machine-list.1.md b/docs/source/markdown/podman-machine-list.1.md index 351e8cf1b..0c929dcdc 100644 --- a/docs/source/markdown/podman-machine-list.1.md +++ b/docs/source/markdown/podman-machine-list.1.md @@ -1,4 +1,4 @@ -% podman-machine-ls 1 +% podman-machine-list 1 ## NAME podman\-machine\-list - List virtual machines 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..fdae1d249 100644 --- a/docs/source/markdown/podman-pod-create.1.md.in +++ b/docs/source/markdown/podman-pod-create.1.md.in @@ -60,7 +60,7 @@ Note: the pod implements devices by storing the initial configuration passed by Set custom DNS servers in the /etc/resolv.conf file that will be shared between all containers in the pod. A special option, "none" is allowed which disables creation of /etc/resolv.conf for the pod. -#### **--dns-opt**=*option* +#### **--dns-option**=*option* Set custom DNS options in the /etc/resolv.conf file that will be shared between all containers in the pod. @@ -119,7 +119,7 @@ Assign a name to the pod. #### **--network**=*mode*, **--net** -Set the network mode for the pod. Invalid if using **--dns**, **--dns-opt**, or **--dns-search** with **--network** that is set to **none** or **container:**_id_. +Set the network mode for the pod. Invalid if using **--dns**, **--dns-option**, or **--dns-search** with **--network** that is set to **none** or **container:**_id_. Valid _mode_ values are: @@ -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-inspect.1.md b/docs/source/markdown/podman-pod-inspect.1.md index e100256af..609cc47da 100644 --- a/docs/source/markdown/podman-pod-inspect.1.md +++ b/docs/source/markdown/podman-pod-inspect.1.md @@ -18,22 +18,42 @@ Change the default output format. This can be of a supported type like 'json' or a Go template. Valid placeholders for the Go template are listed below: -| **Placeholder** | **Description** | -| ----------------- | ----------------------------------------------------------------------------- | -| .ID | Pod ID | -| .Name | Pod name | -| .State | Pod state | -| .Hostname | Pod hostname | -| .Labels | Pod labels | -| .Created | Time when the pod was created | -| .CreateCgroup | Whether cgroup was created | -| .CgroupParent | Pod cgroup parent | -| .CgroupPath | Pod cgroup path | -| .CreateInfra | Whether infrastructure created | -| .InfraContainerID | Pod infrastructure ID | -| .SharedNamespaces | Pod shared namespaces | -| .NumContainers | Number of containers in the pod | -| .Containers | Pod containers | +| **Placeholder** | **Description** | +|----------------------|---------------------------------------------| +| .BlkioDeviceReadBps | Block I/O Device Read, in bytes/sec | +| .BlkioDeviceWriteBps | Block I/O Device Read, in bytes/sec | +| .BlkioWeight | Block I/O Weight | +| .BlkioWeightDevice | Block I/O Device Weight | +| .CgroupParent | Pod cgroup parent | +| .CgroupPath | Pod cgroup path | +| .Containers | Pod containers | +| .CPUPeriod | CPU period | +| .CPUQuota | CPU quota | +| .CPUSetCPUs | CPU Set CPUs | +| .CPUSetMems | CPU Set Mems | +| .CPUShares | CPU Shares | +| .CreateCgroup | Whether cgroup was created | +| .CreateCommand | Create command | +| .Created | Time when the pod was created | +| .CreateInfra | Whether infrastructure created | +| .Devices | Devices | +| .ExitPolicy | Exit policy | +| .Hostname | Pod hostname | +| .ID | Pod ID | +| .InfraConfig ... | Infra config (contains further fields) | +| .InfraContainerID | Pod infrastructure ID | +| .InspectPodData ... | Nested structure, for experts only | +| .Labels | Pod labels | +| .MemoryLimit | Memory limit, bytes | +| .MemorySwap | Memory swap limit, in bytes | +| .Mounts | Mounts | +| .Name | Pod name | +| .Namespace | Namespace | +| .NumContainers | Number of containers in the pod | +| .SecurityOpts | Security options | +| .SharedNamespaces | Pod shared namespaces | +| .State | Pod state | +| .VolumesFrom | Volumes from | #### **--latest**, **-l** diff --git a/docs/source/markdown/podman-pod-stats.1.md b/docs/source/markdown/podman-pod-stats.1.md.in index c71159f09..4ecb30bdb 100644 --- a/docs/source/markdown/podman-pod-stats.1.md +++ b/docs/source/markdown/podman-pod-stats.1.md.in @@ -23,16 +23,16 @@ Valid placeholders for the Go template are listed below: | **Placeholder** | **Description** | | --------------- | ------------------ | -| .Pod | Pod ID | +| .BlockIO | Block IO | | .CID | Container ID | -| .Name | Container Name | | .CPU | CPU percentage | +| .Mem | Memory percentage | | .MemUsage | Memory usage | | .MemUsageBytes | Memory usage (IEC) | -| .Mem | Memory percentage | +| .Name | Container Name | | .NetIO | Network IO | -| .BlockIO | Block IO | | .PIDS | Number of PIDs | +| .Pod | Pod ID | When using a GO template, you may precede the format with `table` to print headers. @@ -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** - -Do not clear the terminal/screen in between reporting intervals - -#### **--no-stream** +@@option no-reset -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..1259f0e37 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -177,19 +177,11 @@ 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 cannot be combined 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. - -@@option dns-opt.container +@@option dns-option.container @@option dns-search.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 @@ -296,7 +286,7 @@ This option is currently supported only by the **journald** log driver. #### **--network**=*mode*, **--net** -Set the network mode for the container. Invalid if using **--dns**, **--dns-opt**, or **--dns-search** with **--network** set to **none** or **container:**_id_. If used together with **--pod**, the container will not join the pod's network namespace. +Set the network mode for the container. Invalid if using **--dns**, **--dns-option**, or **--dns-search** with **--network** set to **none** or **container:**_id_. If used together with **--pod**, the container will not join the pod's network namespace. Valid _mode_ values are: @@ -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,15 +437,11 @@ 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** +@@option sig-proxy -Sets whether the signals sent to the **podman run** command are proxied to the container process. SIGCHLD, SIGSTOP, and SIGKILL are not proxied. The default is **true**. +The default is **true**. @@option stop-signal @@ -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-secret-create.1.md b/docs/source/markdown/podman-secret-create.1.md index 1aafc6c11..fc6d72efb 100644 --- a/docs/source/markdown/podman-secret-create.1.md +++ b/docs/source/markdown/podman-secret-create.1.md @@ -26,16 +26,20 @@ Specify the secret driver (default **file**, which is unencrypted). #### **--driver-opts**=*key1=val1,key2=val2* -Specify driver specific options +Specify driver specific options. #### **--env**=*false* -Read secret data from environment variable +Read secret data from environment variable. #### **--help** Print usage statement. +#### **--label**, **-l**=*key=val1,key2=val2* + +Add label to secret. These labels can be viewed in podman secrete inspect or ls. + ## EXAMPLES ``` diff --git a/docs/source/markdown/podman-secret-inspect.1.md b/docs/source/markdown/podman-secret-inspect.1.md index 0e0d16120..b5bcd2b92 100644 --- a/docs/source/markdown/podman-secret-inspect.1.md +++ b/docs/source/markdown/podman-secret-inspect.1.md @@ -19,10 +19,25 @@ Secrets can be queried individually by providing their full name or a unique par Format secret output using Go template. +| **Placeholder** | **Description** | +| ------------------------ | ----------------------------------------------------------------- | +| .CreatedAt | When secret was created (relative timestamp, human-readable) | +| .ID | ID of secret | +| .Spec | Details of secret | +| .Spec.Driver | Driver info | +| .Spec.Driver.Name | Driver name (string) | +| .Spec.Driver.Options ... | Driver options (map of driver-specific options) | +| .Spec.Name | Name of secret | +| .UpdatedAt | When secret was last updated (relative timestamp, human-readable) | + #### **--help** Print usage statement. +#### **--pretty** + +Print inspect output in human-readable format + ## EXAMPLES diff --git a/docs/source/markdown/podman-start.1.md b/docs/source/markdown/podman-start.1.md.in index fd24c6bf4..a1ccc4120 100644 --- a/docs/source/markdown/podman-start.1.md +++ b/docs/source/markdown/podman-start.1.md.in @@ -53,18 +53,16 @@ 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** 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** +@@option 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. +The default is **true** when attaching, **false** otherwise. ## EXAMPLE diff --git a/docs/source/markdown/podman-stats.1.md b/docs/source/markdown/podman-stats.1.md.in index a1a0f6a93..a14bd81e6 100644 --- a/docs/source/markdown/podman-stats.1.md +++ b/docs/source/markdown/podman-stats.1.md.in @@ -30,17 +30,37 @@ Pretty-print container statistics to JSON or using a Go template Valid placeholders for the Go template are listed below: -| **Placeholder** | **Description** | -| --------------- | ------------------ | -| .ID | Container ID | -| .Name | Container Name | -| .CPUPerc | CPU percentage | -| .MemUsage | Memory usage | -| .MemUsageBytes | Memory usage (IEC) | -| .MemPerc | Memory percentage | -| .NetIO | Network IO | -| .BlockIO | Block IO | -| .PIDS | Number of PIDs | +| **Placeholder** | **Description** | +|---------------------|--------------------------------------------------| +| .AvgCPU | Average CPU, full precision float | +| .AVGCPU | Average CPU, formatted as a percent | +| .BlockInput | Block Input | +| .BlockIO | Block IO | +| .BlockOutput | Block Output | +| .ContainerID | Container ID, full (untruncated) hash | +| .ContainerStats ... | Nested structure, for experts only | +| .CPU | Percent CPU, full precision float | +| .CPUNano | CPU Usage, total, in nanoseconds | +| .CPUPerc | CPU percentage | +| .CPUSystemNano | CPU Usage, kernel, in nanoseconds | +| .Duration | Same as CPUNano | +| .ID | Container ID, truncated | +| .MemLimit | Memory limit, in bytes | +| .MemPerc | Memory percentage | +| .MemUsage | Memory usage | +| .MemUsageBytes | Memory usage (IEC) | +| .Name | Container Name | +| .NetInput | Network Input | +| .NetIO | Network IO | +| .NetOutput | Network Output | +| .PerCPU | CPU time consumed by all tasks [1] | +| .PIDs | Number of PIDs | +| .PIDS | Number of PIDs (yes, we know it's a dup) | +| .SystemNano | Current system datetime, nanoseconds since epoch | +| .Up | Duration (CPUNano), in human-readable form | +| .UpTime | Same as UpTime | + +[1] Cgroups V1 only When using a GO template, you may precede the format with `table` to print headers. @@ -53,13 +73,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** diff --git a/docs/source/markdown/podman-system-connection-list.1.md b/docs/source/markdown/podman-system-connection-list.1.md index 325c78a5c..99804f77f 100644 --- a/docs/source/markdown/podman-system-connection-list.1.md +++ b/docs/source/markdown/podman-system-connection-list.1.md @@ -13,7 +13,7 @@ List ssh destination(s) for podman service(s). ## OPTIONS -#### **--format**=*format* +#### **--format**, **-f**=*format* Change the default output format. This can be of a supported type like 'json' or a Go template. Valid placeholders for the Go template listed below: @@ -25,6 +25,10 @@ Valid placeholders for the Go template listed below: | .URI | URI to podman service. Valid schemes are ssh://[user@]*host*[:port]*Unix domain socket*[?secure=True], unix://*Unix domain socket*, and tcp://localhost[:*port*] | | .Default | Indicates whether connection is the default | +#### **--quiet**, **-q** + +Only show connection names + ## EXAMPLE ``` $ podman system connection list diff --git a/docs/source/markdown/podman-system-service.1.md b/docs/source/markdown/podman-system-service.1.md index 2ec48aeb4..2293dea0a 100644 --- a/docs/source/markdown/podman-system-service.1.md +++ b/docs/source/markdown/podman-system-service.1.md @@ -1,4 +1,4 @@ -% podman-service 1 +% podman-system-service 1 ## NAME podman\-system\-service - Run an API service diff --git a/docs/source/markdown/podman-version.1.md b/docs/source/markdown/podman-version.1.md index 3062d10ab..93d4d54d5 100644 --- a/docs/source/markdown/podman-version.1.md +++ b/docs/source/markdown/podman-version.1.md @@ -16,6 +16,14 @@ OS, and Architecture. Change output format to "json" or a Go template. +| **Placeholder** | **Description** | +| ------------------- | ------------------------ | +| .Client ... | Version of local podman | +| .Server ... | Version of remote podman | + +Each of the above fields branch deeper into further subfields +such as .Version, .APIVersion, .GoVersion, and more. + ## Example A sample output of the `version` command: diff --git a/docs/source/markdown/podman-volume-create.1.md b/docs/source/markdown/podman-volume-create.1.md index 934488111..1e99df55a 100644 --- a/docs/source/markdown/podman-volume-create.1.md +++ b/docs/source/markdown/podman-volume-create.1.md @@ -17,7 +17,13 @@ driver options can be set using the **--opt** flag. #### **--driver**=*driver* -Specify the volume driver name (default **local**). Setting this to a value other than **local** Podman attempts to create the volume using a volume plugin with the given name. Such plugins must be defined in the **volume_plugins** section of the **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)** configuration file. +Specify the volume driver name (default **local**). +There are two drivers supported by Podman itself: **local** and **image**. +The **local** driver uses a directory on disk as the backend by default, but can also use the **mount(8)** command to mount a filesystem as the volume if **--opt** is specified. +The **image** driver uses an image as the backing store of for the volume. +An overlay filesystem will be created, which allows changes to the volume to be committed as a new layer on top of the image. +Using a value other than **local or **image**, Podman will attempt to create the volume using a volume plugin with the given name. +Such plugins must be defined in the **volume_plugins** section of the **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)** configuration file. #### **--help** @@ -43,7 +49,10 @@ The `o` option sets options for the mount, and is equivalent to the `-o` flag to - The `o` option supports using volume options other than the UID/GID options with the **local** driver and requires root privileges. - The `o` options supports the `timeout` option which allows users to set a driver specific timeout in seconds before volume creation fails. For example, **--opts=o=timeout=10** sets a driver timeout of 10 seconds. -When not using the **local** driver, the given options are passed directly to the volume plugin. In this case, supported options are dictated by the plugin in question, not Podman. +For the **image** driver, the only supported option is `image`, which specifies the image the volume is based on. +This option is mandatory when using the **image** driver. + +When not using the **local** and **image** drivers, the given options are passed directly to the volume plugin. In this case, supported options are dictated by the plugin in question, not Podman. ## EXAMPLES @@ -57,6 +66,8 @@ $ podman volume create --label foo=bar myvol # podman volume create --opt device=tmpfs --opt type=tmpfs --opt o=nodev,noexec myvol # podman volume create --opt device=tmpfs --opt type=tmpfs --opt o=uid=1000,gid=1000 testvol + +# podman volume create --driver image --opt image=fedora:latest fedoraVol ``` ## QUOTAS diff --git a/docs/tutorials/podman-for-windows.md b/docs/tutorials/podman-for-windows.md index bb37f4a48..da1e0c059 100644 --- a/docs/tutorials/podman-for-windows.md +++ b/docs/tutorials/podman-for-windows.md @@ -415,3 +415,8 @@ your WSL system state and perform a manual WSL installation using the `wsl wsl --install ``` 5. Continue with podman machine init + +Install Certificate Authority +============================= + +Instructions for installing a CA certificate can be found [here](podman-install-certificate-authority.md). diff --git a/docs/tutorials/podman-install-certificate-authority.md b/docs/tutorials/podman-install-certificate-authority.md new file mode 100644 index 000000000..bcd3056ba --- /dev/null +++ b/docs/tutorials/podman-install-certificate-authority.md @@ -0,0 +1,102 @@ + + +Install Certificate Authority +============================= + +Organizations may create their own local certificate authority (CA) or acquire one from a third party. This may mean more than one certificate, such as one or more intermediate certificates and a root certificate, for example. In any case, it is necessary to add the certificate authority (CA) certificate(s) so that it can be employed for various use cases. + +### Method one + +Certificates may be either individual or concatenated (bundles). The following steps are one method to add such certificates to Podman. It is assumed that Podman is running and the certificate(s) to be installed are available on an accessible server via curl. If such access is not possible, an alternative method follows. + +First, assuming a running Podman machine, ssh into the machine: +``` +podman machine ssh +``` + +If Podman is running in the default rootless mode, an additional command is required to get to a root shell: + +``` +[core@localhost ~]$ sudo su - +``` + +After issuing the above command, the prompt should change to indicate the "root" instead of the "core" user. + +Next, while in the machine, change to the directory where the certificate(s) should be installed: +``` +[root@localhost ~]# cd /etc/pki/ca-trust/source/anchors +``` + +Then use curl to download the certificate. Notes: +* The -k is only necessary if connecting securely to a server for which the certificate is not yet trusted +* The MY-SERVER.COM/SOME-CERTIFICATE.pem should be replaced as appropriate +``` +[root@localhost anchors]# curl -k -o some-certificate.pem https://MY-SERVER.COM/SOME-CERTIFICATE.pem +``` + +Repeat as necessary for multiple certificates. + +Once all of the certificates have been downloaded, run the command to add the certificates to the list of trusted CAs: +``` +[root@localhost anchors]# update-ca-trust +``` + +Exit the machine: +``` +[root@localhost anchors]# exit +``` + +If the "sudo su -" command was used to switch to a root shell as described above, an additional exit command is needed to exit the machine: + +``` +[core@localhost ~]$ exit +``` + +### Alternative Method + +If the above method is for some reason not practical or desirable, the certificate may be created using vi. + +As above, assuming a running Podman machine, ssh into the machine: + +``` +podman machine ssh +``` + +If the prompt starts with "core" instead of "root", switch to a root shell: + +``` +[core@localhost ~]$ sudo su - +``` + +Next, change to the directory where the certificate(s) should be installed: +``` +[root@localhost ~]# cd /etc/pki/ca-trust/source/anchors +``` + +Then use vi to create the certificate. +``` +[root@localhost ~]# vi SOME-CERTIFICATE.pem +``` +After vi opens, copy the certificate to the clipboard, then in insert mode, paste the clipboard contents to vi. Lastly, save the file and close vi. + +Repeat as necessary for multiple certificates. + +Once all of the certificates have been created, run the command to add the certificates to the list of trusted CAs: +``` +[root@localhost anchors]# update-ca-trust +``` + +Exit the machine: +``` +[root@localhost anchors]# exit +``` + +If the "sudo su -" command described above was used, an additional exit command is needed: + +``` +[core@localhost ~]$ exit +``` + +### Final Notes + +The certificate installation will persist during machine restarts. There is no need to stop and start the machine to begin using the certificate. |