diff options
Diffstat (limited to 'docs/source')
18 files changed, 219 insertions, 54 deletions
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/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in index e201806e5..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 @@ -564,6 +568,10 @@ as a seccomp filter 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 72f167a7e..742a32b5a 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -145,7 +145,7 @@ flag to pass the user's supplementary group access into the container. This option cannot be combined with **--network** that is set to **none** or **container:**_id_. -@@option dns-opt.container +@@option dns-option.container @@option dns-search.container @@ -265,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: 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-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-pod-create.1.md.in b/docs/source/markdown/podman-pod-create.1.md.in index 7700f5e62..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: 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.in b/docs/source/markdown/podman-pod-stats.1.md.in index 83a4b7a1e..4ecb30bdb 100644 --- a/docs/source/markdown/podman-pod-stats.1.md.in +++ 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. diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index 37d052646..2109a0e33 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -181,7 +181,7 @@ flag to pass the user's supplementary group access into the container. This option cannot be combined with **--network** that is set to **none** or **container:**_id_. -@@option dns-opt.container +@@option dns-option.container @@option dns-search.container @@ -286,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: 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-stats.1.md.in b/docs/source/markdown/podman-stats.1.md.in index f06bd3fcc..a14bd81e6 100644 --- a/docs/source/markdown/podman-stats.1.md.in +++ 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. 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-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 |