diff options
Diffstat (limited to 'docs/source/markdown')
26 files changed, 182 insertions, 126 deletions
diff --git a/docs/source/markdown/podman-auto-update.1.md b/docs/source/markdown/podman-auto-update.1.md index b6941362a..3ab097388 100644 --- a/docs/source/markdown/podman-auto-update.1.md +++ b/docs/source/markdown/podman-auto-update.1.md @@ -31,7 +31,7 @@ Systemd units that start and stop a container cannot run a new image. **--authfile**=*path* Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`. -If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. (Not available for remote commands) +If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE environment variable. `export REGISTRY_AUTH_FILE=path` diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md index 7d0aa5001..f1fddb2fc 100644 --- a/docs/source/markdown/podman-build.1.md +++ b/docs/source/markdown/podman-build.1.md @@ -46,7 +46,7 @@ Set the ARCH of the image to the provided value instead of the architecture of t **--authfile**=*path* Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`. -If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. (Not available for remote commands) +If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE environment variable. `export REGISTRY_AUTH_FILE=path` @@ -111,17 +111,27 @@ network namespaces can be found. **--cpu-period**=*limit* -Limit the CPU CFS (Completely Fair Scheduler) period +Set the CPU period for the Completely Fair Scheduler (CFS), which is a +duration in microseconds. Once the container's CPU quota is used up, it will +not be scheduled to run until the current period ends. Defaults to 100000 +microseconds. -Limit the container's CPU usage. This flag tell the kernel to restrict the container's CPU usage to the period you specify. +On some systems, changing the CPU limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error **--cpu-quota**=*limit* -Limit the CPU CFS (Completely Fair Scheduler) quota +Limit the CPU Completely Fair Scheduler (CFS) quota. Limit the container's CPU usage. By default, containers run with the full -CPU resource. This flag tell the kernel to restrict the container's CPU usage -to the quota you specify. +CPU resource. The limit is a number in microseconds. If you provide a number, +the container will be allowed to use that much CPU time until the CPU period +ends (controllable via **--cpu-period**). + +On some systems, changing the CPU limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error **--cpu-shares**, **-c**=*shares* @@ -470,7 +480,7 @@ When --timestamp is set, the created timestamp is always set to the time specifi **--tls-verify**=*true|false* -Require HTTPS and verify certificates when talking to container registries (defaults to true). (Not available for remote commands) +Require HTTPS and verify certificates when talking to container registries (defaults to true). **--ulimit**=*type*=*soft-limit*[:*hard-limit*] @@ -787,9 +797,9 @@ registries.conf is the configuration file which specifies which container regist ## Troubleshooting -If you are using a useradd command within a Containerfile with a large UID/GID, it will create a large sparse file `/var/log/lastlog`. This can cause the build to hang forever. Go language does not support sparse files correctly, which can lead to some huge files being created in your container image. +### lastlog sparse file -### Solution +If you are using a useradd command within a Containerfile with a large UID/GID, it will create a large sparse file `/var/log/lastlog`. This can cause the build to hang forever. Go language does not support sparse files correctly, which can lead to some huge files being created in your container image. If you are using `useradd` within your build script, you should pass the `--no-log-init or -l` option to the `useradd` command. This option tells useradd to stop creating the lastlog file. diff --git a/docs/source/markdown/podman-container-exists.1.md b/docs/source/markdown/podman-container-exists.1.md index d24df2fc8..d81a38515 100644 --- a/docs/source/markdown/podman-container-exists.1.md +++ b/docs/source/markdown/podman-container-exists.1.md @@ -4,7 +4,7 @@ podman-container-exists - Check if a container exists in local storage ## SYNOPSIS -**podman container exists** *container* +**podman container exists** [*options*] *container* ## DESCRIPTION **podman container exists** checks if a container exists in local storage. The **ID** or **Name** @@ -14,17 +14,19 @@ was an issue accessing the local storage. ## OPTIONS +**--external**=*true|false* +Check for external containers as well as Podman containers. These external containers are generally created via other container technology such as Buildah or CRI-O. + **-h**, **--help** Print usage statement -## Examples +## EXAMPLES Check if an container called `webclient` exists in local storage (the container does actually exist). ``` $ podman container exists webclient $ echo $? 0 -$ ``` Check if an container called `webbackend` exists in local storage (the container does not actually exist). @@ -32,7 +34,13 @@ Check if an container called `webbackend` exists in local storage (the container $ podman container exists webbackend $ echo $? 1 -$ +``` + +Check if an container called `ubi8-working-container` created via Buildah exists in local storage (the container does not actually exist). +``` +$ podman container exists --external ubi8-working-container +$ echo $? +1 ``` ## SEE ALSO diff --git a/docs/source/markdown/podman-container-prune.1.md b/docs/source/markdown/podman-container-prune.1.md index 8c05eeafe..d56a1e7f5 100644 --- a/docs/source/markdown/podman-container-prune.1.md +++ b/docs/source/markdown/podman-container-prune.1.md @@ -23,7 +23,7 @@ Do not provide an interactive prompt for container removal. Print usage statement -## Examples +## EXAMPLES Remove all stopped containers from local storage ``` diff --git a/docs/source/markdown/podman-container-runlabel.1.md b/docs/source/markdown/podman-container-runlabel.1.md index 2abbf0b7f..676ad12d0 100644 --- a/docs/source/markdown/podman-container-runlabel.1.md +++ b/docs/source/markdown/podman-container-runlabel.1.md @@ -40,11 +40,11 @@ is used. Any additional arguments will be appended to the command. -## OPTIONS: +## OPTIONS **--authfile**=*path* Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`. -If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. (Not available for remote commands) +If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE environment variable. `export REGISTRY_AUTH_FILE=path` @@ -85,9 +85,9 @@ created from this image. Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, -TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf (Not available for remote commands) +TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. -## Examples +## EXAMPLES Execute the run label of an image called foobar. ``` diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index 3303ae572..c7e00f594 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -47,7 +47,7 @@ each of stdin, stdout, and stderr. Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE -environment variable. `export REGISTRY_AUTH_FILE=path` (Not available for remote commands) +environment variable. `export REGISTRY_AUTH_FILE=path` **--blkio-weight**=*weight* @@ -103,17 +103,27 @@ Write the pid of the `conmon` process to a file. `conmon` runs in a separate pro **--cpu-period**=*limit* -Limit the CPU CFS (Completely Fair Scheduler) period +Set the CPU period for the Completely Fair Scheduler (CFS), which is a +duration in microseconds. Once the container's CPU quota is used up, it will +not be scheduled to run until the current period ends. Defaults to 100000 +microseconds. -Limit the container's CPU usage. This flag tell the kernel to restrict the container's CPU usage to the period you specify. +On some systems, changing the CPU limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error **--cpu-quota**=*limit* -Limit the CPU CFS (Completely Fair Scheduler) quota +Limit the CPU Completely Fair Scheduler (CFS) quota. Limit the container's CPU usage. By default, containers run with the full -CPU resource. This flag tell the kernel to restrict the container's CPU usage -to the quota you specify. +CPU resource. The limit is a number in microseconds. If you provide a number, +the container will be allowed to use that much CPU time until the CPU period +ends (controllable via **--cpu-period**). + +On some systems, changing the CPU limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error **--cpu-rt-period**=*microseconds* @@ -169,7 +179,13 @@ PID container CPU CPU share **--cpus**=*number* -Number of CPUs. The default is *0.0* which means no limit. +Number of CPUs. The default is *0.0* which means no limit. This is shorthand +for **--cpu-period** and **--cpu-quota**, so you may only set either +**--cpus** or **--cpu-period** and **--cpu-quota**. + +On some systems, changing the CPU limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error **--cpuset-cpus**=*cpus* @@ -183,23 +199,6 @@ If you have four memory nodes on your system (0-3), use `--cpuset-mems=0,1` then processes in your container will only use memory from the first two memory nodes. -**--detach**, **-d**=*true|false* - -Detached mode: run the container in the background and print the new container ID. The default is *false*. - -At any time you can run **podman ps** in -the other shell to view a list of the running containers. You can reattach to a -detached container with **podman attach**. - -When attached in the tty mode, you can detach from the container (and leave it -running) using a configurable key sequence. The default sequence is `ctrl-p,ctrl-q`. -Configure the keys sequence using the **--detach-keys** option, or specifying -it in the **containers.conf** file: see **containers.conf(5)** for more information. - -**--detach-keys**=*sequence* - -Specify the key sequence for detaching a container. Format is a single character `[a-Z]` or one or more `ctrl-<value>` characters where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. Specifying "" will disable this feature. The default is *ctrl-p,ctrl-q*. - **--device**=_host-device_[**:**_container-device_][**:**_permissions_] Add a host device to the container. Optional *permissions* parameter diff --git a/docs/source/markdown/podman-events.1.md b/docs/source/markdown/podman-events.1.md index 0d91cdf17..d0bc3cef8 100644 --- a/docs/source/markdown/podman-events.1.md +++ b/docs/source/markdown/podman-events.1.md @@ -86,6 +86,7 @@ filters are supported: * container=name_or_id * event=event_status (described above) * image=name_or_id + * label=key=value * pod=name_or_id * volume=name_or_id * type=event_type (described above) diff --git a/docs/source/markdown/podman-generate-kube.1.md b/docs/source/markdown/podman-generate-kube.1.md index f4b4cd482..47d6e0445 100644 --- a/docs/source/markdown/podman-generate-kube.1.md +++ b/docs/source/markdown/podman-generate-kube.1.md @@ -12,7 +12,7 @@ of a pod or container name or ID. Note that the generated Kubernetes YAML file can be used to re-run the deployment via podman-play-kube(1). -## OPTIONS: +## OPTIONS **--filename**, **-f**=**filename** @@ -23,7 +23,7 @@ Output to the given file, instead of STDOUT. If the file already exists, `genera Generate a Kubernetes service object in addition to the Pods. Used to generate a Service specification for the corresponding Pod output. In particular, if the object has portmap bindings, the service specification will include a NodePort declaration to expose the service. A random port is assigned by Podman in the specification. -## Examples +## EXAMPLES Create Kubernetes Pod YAML for a container called `some-mariadb` . ``` diff --git a/docs/source/markdown/podman-generate-systemd.1.md b/docs/source/markdown/podman-generate-systemd.1.md index af8ea3c39..f95c57399 100644 --- a/docs/source/markdown/podman-generate-systemd.1.md +++ b/docs/source/markdown/podman-generate-systemd.1.md @@ -12,7 +12,7 @@ By default, the command will print the content of the unit files to stdout. _Note: If you use this command with the remote client, you would still have to place the generated units on the remote system._ -## OPTIONS: +## OPTIONS **--files**, **-f** @@ -53,7 +53,7 @@ Set the systemd unit name prefix for pods. The default is *pod*. Set the systemd unit name separator between the name/id of a container/pod and the prefix. The default is *-*. -## Examples +## EXAMPLES ### Generate and print a systemd unit file for a container diff --git a/docs/source/markdown/podman-image-exists.1.md b/docs/source/markdown/podman-image-exists.1.md index 59f2145cc..877324cd1 100644 --- a/docs/source/markdown/podman-image-exists.1.md +++ b/docs/source/markdown/podman-image-exists.1.md @@ -18,7 +18,7 @@ was an issue accessing the local storage. Print usage statement -## Examples +## EXAMPLES Check if an image called `webclient` exists in local storage (the image does actually exist). ``` diff --git a/docs/source/markdown/podman-image-prune.1.md b/docs/source/markdown/podman-image-prune.1.md index cf9e50366..d4fbe45c3 100644 --- a/docs/source/markdown/podman-image-prune.1.md +++ b/docs/source/markdown/podman-image-prune.1.md @@ -30,7 +30,7 @@ Do not provide an interactive prompt for container removal. Print usage statement -## Examples ## +## EXAMPLES Remove all dangling images from local storage ``` diff --git a/docs/source/markdown/podman-inspect.1.md b/docs/source/markdown/podman-inspect.1.md index a1dcd1a0e..eb7cf74c6 100644 --- a/docs/source/markdown/podman-inspect.1.md +++ b/docs/source/markdown/podman-inspect.1.md @@ -1,7 +1,7 @@ % podman-inspect(1) ## NAME -podman\-inspect - Display a container or image's configuration +podman\-inspect - Display a container, image, volume, network, or pod's configuration ## SYNOPSIS **podman inspect** [*options*] *name* [...] @@ -9,8 +9,9 @@ podman\-inspect - Display a container or image's configuration ## DESCRIPTION This displays the low-level information on containers and images identified by name or ID. By default, this will render -all results in a JSON array. If the container and image have the same name, this will return container JSON for -unspecified type. If a format is specified, the given template will be executed for each result. +all results in a JSON array. If the inspect type is all, the order of inspection is: containers, images, volumes, network, pods. + So, if a container has the same name as an image, then the container JSON will be returned, and so on. + If a format is specified, the given template will be executed for each result. For more inspection options, see: @@ -25,7 +26,7 @@ For more inspection options, see: **--type**, **-t**=*type* -Return JSON for the specified type. Type can be 'container', 'image' or 'all' (default: all) +Return JSON for the specified type. Type can be 'container', 'image', 'volume', 'network', 'pod', or 'all' (default: all) (Only meaningful when invoked as *podman inspect*) **--format**, **-f**=*format* @@ -38,6 +39,8 @@ The keys of the returned JSON can be used as the values for the --format flag (s 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 can be used to inspect the latest pod created when used with --type pod + The latest option is not supported on the remote client or when invoked as *podman image inspect*. **--size**, **-s** @@ -148,6 +151,20 @@ podman container inspect --latest --format {{.EffectiveCaps}} [CAP_CHOWN CAP_DAC_OVERRIDE CAP_FSETID CAP_FOWNER CAP_MKNOD CAP_NET_RAW CAP_SETGID CAP_SETUID CAP_SETFCAP CAP_SETPCAP CAP_NET_BIND_SERVICE CAP_SYS_CHROOT CAP_KILL CAP_AUDIT_WRITE] ``` +``` +# podman inspect myPod --type pod --format "{{.Name}}" +myPod +``` +``` +# podman inspect myVolume --type volume --format "{{.Name}}" +myVolume +``` + +``` +# podman inspect nyNetwork --type network --format "{{.name}}" +myNetwork +``` + ## SEE ALSO podman(1) diff --git a/docs/source/markdown/podman-login.1.md b/docs/source/markdown/podman-login.1.md index 9b4ff74ed..7c09d99fe 100644 --- a/docs/source/markdown/podman-login.1.md +++ b/docs/source/markdown/podman-login.1.md @@ -42,7 +42,7 @@ Username for registry **--authfile**=*path* -Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json (Not available for remote commands) +Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json. Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE environment variable. `export REGISTRY_AUTH_FILE=path` @@ -60,7 +60,7 @@ Default certificates directory is _/etc/containers/certs.d_. (Not available for Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, -TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. (Not available for remote commands) +TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. **--help**, **-h** diff --git a/docs/source/markdown/podman-logout.1.md b/docs/source/markdown/podman-logout.1.md index 0ff954d43..25f6d97b1 100644 --- a/docs/source/markdown/podman-logout.1.md +++ b/docs/source/markdown/podman-logout.1.md @@ -23,7 +23,7 @@ All the cached credentials can be removed by setting the **all** flag. **--authfile**=*path* -Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json (Not available for remote commands) +Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json. Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE environment variable. `export REGISTRY_AUTH_FILE=path` diff --git a/docs/source/markdown/podman-manifest-add.1.md b/docs/source/markdown/podman-manifest-add.1.md index c4d4417c4..4c0bad2ae 100644 --- a/docs/source/markdown/podman-manifest-add.1.md +++ b/docs/source/markdown/podman-manifest-add.1.md @@ -36,7 +36,7 @@ retrieved from the image's configuration information. **--authfile**=*path* Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`. -If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. (Not available for remote commands) +If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE environment variable. `export REGISTRY_AUTH_FILE=path` @@ -71,7 +71,7 @@ image. This option is rarely used. **--tls-verify** -Require HTTPS and verify certificates when talking to container registries (defaults to true). (Not available for remote commands) +Require HTTPS and verify certificates when talking to container registries (defaults to true). **--variant** diff --git a/docs/source/markdown/podman-manifest-push.1.md b/docs/source/markdown/podman-manifest-push.1.md index 33b2a24c5..9cf0b159c 100644 --- a/docs/source/markdown/podman-manifest-push.1.md +++ b/docs/source/markdown/podman-manifest-push.1.md @@ -22,7 +22,7 @@ the list or index itself. **--authfile**=*path* Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`. -If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. (Not available for remote commands) +If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE environment variable. `export REGISTRY_AUTH_FILE=path` @@ -64,7 +64,7 @@ Sign the pushed images using the GPG key that matches the specified fingerprint. **--tls-verify** -Require HTTPS and verify certificates when talking to container registries (defaults to true) (Not available for remote commands) +Require HTTPS and verify certificates when talking to container registries. (defaults to true) ## EXAMPLE diff --git a/docs/source/markdown/podman-play-kube.1.md b/docs/source/markdown/podman-play-kube.1.md index 519b153f4..97b0dc09a 100644 --- a/docs/source/markdown/podman-play-kube.1.md +++ b/docs/source/markdown/podman-play-kube.1.md @@ -15,12 +15,12 @@ Ideally the input file would be one created by Podman (see podman-generate-kube( Note: HostPath volume types created by play kube will be given an SELinux private label (Z) -## OPTIONS: +## OPTIONS **--authfile**=*path* Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`. -If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. (Not available for remote commands) +If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE environment variable. `export REGISTRY_AUTH_FILE=path` @@ -58,13 +58,13 @@ Directory path for seccomp profiles (default: "/var/lib/kubelet/seccomp"). (Not Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, -TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. (Not available for remote commands) +TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. **--help**, **-h** Print usage statement -## Examples +## EXAMPLES Recreate the pod and containers as described in a file called `demo.yml` ``` diff --git a/docs/source/markdown/podman-pod-exists.1.md b/docs/source/markdown/podman-pod-exists.1.md index cf2852934..4c8714341 100644 --- a/docs/source/markdown/podman-pod-exists.1.md +++ b/docs/source/markdown/podman-pod-exists.1.md @@ -12,7 +12,7 @@ of the pod may be used as input. Podman will return an exit code of `0` when the pod is found. A `1` will be returned otherwise. An exit code of `125` indicates there was an issue accessing the local storage. -## Examples ## +## EXAMPLES Check if a pod called `web` exists in local storage (the pod does actually exist). ``` diff --git a/docs/source/markdown/podman-pod-top.1.md b/docs/source/markdown/podman-pod-top.1.md index 6a1fa8c42..1f2ffd662 100644 --- a/docs/source/markdown/podman-pod-top.1.md +++ b/docs/source/markdown/podman-pod-top.1.md @@ -7,7 +7,7 @@ podman\-pod\-top - Display the running processes of containers in a pod **podman pod top** [*options*] *pod* [*format-descriptors*] ## DESCRIPTION -Display the running processes of containers in a pod. The *format-descriptors* are ps (1) compatible AIX format descriptors but extended to print additional information, such as the seccomp mode or the effective capabilities of a given process. The descriptors can either be passed as separated arguments or as a single comma-separated argument. Note that you can also specify options and or flags of ps(1); in this case, Podman will fallback to executing ps with the specified arguments and flags in the container. +Display the running processes of containers in a pod. The *format-descriptors* are ps (1) compatible AIX format descriptors but extended to print additional information, such as the seccomp mode or the effective capabilities of a given process. The descriptors can either be passed as separated arguments or as a single comma-separated argument. Note that you can specify options and/or additionally options of ps(1); in this case, Podman will fallback to executing ps with the specified arguments and options in the container. ## OPTIONS diff --git a/docs/source/markdown/podman-ps.1.md b/docs/source/markdown/podman-ps.1.md index 58d3358e5..90f147222 100644 --- a/docs/source/markdown/podman-ps.1.md +++ b/docs/source/markdown/podman-ps.1.md @@ -34,23 +34,33 @@ all the containers information. By default it lists: Show all the containers created by Podman, default is only running containers. -Note: Podman shares containers storage with other tools such as Buildah and CRI-O. In some cases these `external` containers might also exist in the same storage. Use the `--storage` option to see these external containers. External containers show the 'storage' status. +Note: Podman shares containers storage with other tools such as Buildah and CRI-O. In some cases these `external` containers might also exist in the same storage. Use the `--external` option to see these external containers. External containers show the 'storage' status. -**--pod**, **-p** - -Display the pods the containers are associated with - -**--storage** +**--external** Display external containers that are not controlled by Podman but are stored in containers storage. These external containers are generally created via other container technology such as Buildah or CRI-O and may depend on the same container images that Podman is also using. External containers are denoted with either a 'buildah' or 'storage' in the COMMAND and STATUS column of the ps output. Only used with the --all option. -**--no-trunc** +**--filter**, **-f** -Display the extended information +Filter what containers are shown in the output. +Multiple filters can be given with multiple uses of the --filter flag. +If multiple filters are given, only containers which match all of the given filters will be shown. +Results will be drawn from all containers, regardless of whether --all was given. -**--quiet**, **-q** +Valid filters are listed below: -Print the numeric IDs of the containers only +| **Filter** | **Description** | +| --------------- | -------------------------------------------------------------------------------- | +| id | [ID] Container's ID | +| name | [Name] Container's name | +| label | [Key] or [Key=Value] Label assigned to a container | +| exited | [Int] Container's exit code | +| status | [Status] Container's status: 'created', 'exited', 'paused', 'running', 'unknown' | +| ancestor | [ImageName] Image or descendant used to create container | +| before | [ID] or [Name] Containers created before this container | +| since | [ID] or [Name] Containers created since this container | +| volume | [VolumeName] or [MountpointDestination] Volume mounted in container | +| health | [Status] healthy or unhealthy | **--format**=*format* @@ -74,15 +84,9 @@ Valid placeholders for the Go template are listed below: | .Labels | All the labels assigned to the container | | .Mounts | Volumes mounted in the container | -**--sort** - -Sort by command, created, id, image, names, runningfor, size, or status", -Note: Choosing size will sort by size of rootFs, not alphabetically like the rest of the options -Default: created - -**--size**, **-s** +**--help**, **-h** -Display the total file size +Print usage statement **--last**, **-n** @@ -98,31 +102,27 @@ The latest option is not supported on the remote client. Display namespace information -**--filter**, **-f** +**--no-trunc** -Filter what containers are shown in the output. -Multiple filters can be given with multiple uses of the --filter flag. -If multiple filters are given, only containers which match all of the given filters will be shown. -Results will be drawn from all containers, regardless of whether --all was given. +Display the extended information -Valid filters are listed below: +**--pod**, **-p** -| **Filter** | **Description** | -| --------------- | -------------------------------------------------------------------------------- | -| id | [ID] Container's ID | -| name | [Name] Container's name | -| label | [Key] or [Key=Value] Label assigned to a container | -| exited | [Int] Container's exit code | -| status | [Status] Container's status: 'created', 'exited', 'paused', 'running', 'unknown' | -| ancestor | [ImageName] Image or descendant used to create container | -| before | [ID] or [Name] Containers created before this container | -| since | [ID] or [Name] Containers created since this container | -| volume | [VolumeName] or [MountpointDestination] Volume mounted in container | -| health | [Status] healthy or unhealthy | +Display the pods the containers are associated with -**--help**, **-h** +**--quiet**, **-q** -Print usage statement +Print the numeric IDs of the containers only + +**--sort** + +Sort by command, created, id, image, names, runningfor, size, or status", +Note: Choosing size will sort by size of rootFs, not alphabetically like the rest of the options +Default: created + +**--size**, **-s** + +Display the total file size **--sync** @@ -181,7 +181,7 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS ``` ``` -$ podman ps --storage -a +$ podman ps --external -a CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 69ed779d8ef9f redis:alpine "redis-server" 25 hours ago Created 6379/tcp k8s_container1_podsandbox1_redhat.test.crio_redhat-test-crio_1 38a8a78596f9 docker.io/library/busybox:latest buildah 2 hours ago storage busybox-working-container diff --git a/docs/source/markdown/podman-pull.1.md b/docs/source/markdown/podman-pull.1.md index c75cb18b4..46beb4c42 100644 --- a/docs/source/markdown/podman-pull.1.md +++ b/docs/source/markdown/podman-pull.1.md @@ -57,7 +57,7 @@ Note: When using the all-tags flag, Podman will not iterate over the search regi **--authfile**=*path* Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`. -If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. (Not available for remote commands) +If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE environment variable. `export REGISTRY_AUTH_FILE=path` @@ -97,7 +97,7 @@ Suppress output information when pulling images Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, -TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. (Not available for remote commands) +TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. **--help**, **-h** diff --git a/docs/source/markdown/podman-push.1.md b/docs/source/markdown/podman-push.1.md index fffd76801..e9b63dc43 100644 --- a/docs/source/markdown/podman-push.1.md +++ b/docs/source/markdown/podman-push.1.md @@ -46,7 +46,7 @@ Images are pushed from those stored in local image storage. **--authfile**=*path* Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`. -If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. (Not available for remote commands) +If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE environment variable. `export REGISTRY_AUTH_FILE=path` @@ -98,7 +98,7 @@ Add a signature at the destination using the specified key Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, -TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. (Not available for remote commands) +TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. ## EXAMPLE diff --git a/docs/source/markdown/podman-restart.1.md b/docs/source/markdown/podman-restart.1.md index 87217f096..127aaa074 100644 --- a/docs/source/markdown/podman-restart.1.md +++ b/docs/source/markdown/podman-restart.1.md @@ -30,7 +30,7 @@ Restart all containers that are already in the *running* state. Timeout to wait before forcibly stopping the container. -## EXAMPLES ## +## EXAMPLES Restart the latest container ``` diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index d9bcc49ae..aad179957 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -57,7 +57,7 @@ each of **stdin**, **stdout**, and **stderr**. **--authfile**[=*path*] -Path to the authentication file. Default is *${XDG_RUNTIME_DIR}/containers/auth.json*. (Not available for remote commands) +Path to the authentication file. Default is *${XDG_RUNTIME_DIR}/containers/auth.json*. Note: You can also override the default path of the authentication file by setting the **REGISTRY_AUTH_FILE** environment variable. @@ -118,15 +118,27 @@ Write the pid of the **conmon** process to a file. As **conmon** runs in a separ **--cpu-period**=*limit* -Limit the container's CPU usage by setting CPU CFS (Completely Fair Scheduler) period. +Set the CPU period for the Completely Fair Scheduler (CFS), which is a +duration in microseconds. Once the container's CPU quota is used up, it will +not be scheduled to run until the current period ends. Defaults to 100000 +microseconds. + +On some systems, changing the CPU limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error **--cpu-quota**=*limit* -Limit the CPU CFS (Completely Fair Scheduler) quota. +Limit the CPU Completely Fair Scheduler (CFS) quota. Limit the container's CPU usage. By default, containers run with the full -CPU resource. This flag tell the kernel to restrict the container's CPU usage -to the quota you specify. +CPU resource. The limit is a number in microseconds. If you provide a number, +the container will be allowed to use that much CPU time until the CPU period +ends (controllable via **--cpu-period**). + +On some systems, changing the CPU limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error **--cpu-rt-period**=*microseconds* @@ -180,7 +192,13 @@ division of CPU shares: **--cpus**=*number* -Number of CPUs. The default is *0.0* which means no limit. +Number of CPUs. The default is *0.0* which means no limit. This is shorthand +for **--cpu-period** and **--cpu-quota**, so you may only set either +**--cpus** or **--cpu-period** and **--cpu-quota**. + +On some systems, changing the CPU limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error **--cpuset-cpus**=*number* @@ -197,20 +215,20 @@ to only use memory from the first two memory nodes. **--detach**, **-d**=**true**|**false** -Detached mode: run the container in the background and print the new container ID. The default is **false**. +Detached mode: run the container in the background and print the new container ID. The default is *false*. At any time you can run **podman ps** in the other shell to view a list of the running containers. You can reattach to a detached container with **podman attach**. When attached in the tty mode, you can detach from the container (and leave it -running) using a configurable key sequence. +running) using a configurable key sequence. The default sequence is `ctrl-p,ctrl-q`. +Configure the keys sequence using the **--detach-keys** option, or specifying +it in the **containers.conf** file: see **containers.conf(5)** for more information. -**--detach-keys**=_sequence_ +**--detach-keys**=*sequence* -Specify the key sequence for detaching a container; _sequence_ is a comma-delimited set -in which each item can be a single character from the [a-Z] range, -or **ctrl**-_value_, where _value_ is one of: **a-z** or **@^[,_**. +Specify the key sequence for detaching a container. Format is a single character `[a-Z]` or one or more `ctrl-<value>` characters where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. Specifying "" will disable this feature. The default is *ctrl-p,ctrl-q*. This option can also be set in **containers.conf**(5) file. @@ -1234,7 +1252,7 @@ you'd like to connect instead, as in: $ podman run -a stdin -a stdout -i -t fedora /bin/bash ``` -## Sharing IPC between containers +### Sharing IPC between containers Using **shm_server.c** available here: https://www.cs.cf.ac.uk/Dave/C/node27.html diff --git a/docs/source/markdown/podman-wait.1.md b/docs/source/markdown/podman-wait.1.md index 1d85e9af0..f0ccb1f9e 100644 --- a/docs/source/markdown/podman-wait.1.md +++ b/docs/source/markdown/podman-wait.1.md @@ -23,8 +23,8 @@ Condition to wait on (default "stopped") Print usage statement -**--interval**, **-i**=*microseconds* - Microseconds to wait before polling for completion +**--interval**, **-i**=*duration* + Time interval to wait before polling for completion. A duration string is a sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". Time unit defaults to "ms". **--latest**, **-l** @@ -42,6 +42,9 @@ $ podman wait mywebserver $ podman wait --latest 0 +$ podman wait --interval 2s +0 + $ podman wait 860a4b23 1 diff --git a/docs/source/markdown/podman.1.md b/docs/source/markdown/podman.1.md index 87337fa3c..2d5110ad9 100644 --- a/docs/source/markdown/podman.1.md +++ b/docs/source/markdown/podman.1.md @@ -220,7 +220,7 @@ the exit codes follow the `chroot` standard, see below: | [podman-import(1)](podman-import.1.md) | Import a tarball and save it as a filesystem image. | | [podman-info(1)](podman-info.1.md) | Displays Podman related system information. | | [podman-init(1)](podman-init.1.md) | Initialize one or more containers | -| [podman-inspect(1)](podman-inspect.1.md) | Display a container or image's configuration. | +| [podman-inspect(1)](podman-inspect.1.md) | Display a container, image, volume, network, or pod's configuration. | | [podman-kill(1)](podman-kill.1.md) | Kill the main process in one or more containers. | | [podman-load(1)](podman-load.1.md) | Load an image from a container image archive into container storage. | | [podman-login(1)](podman-login.1.md) | Login to a container registry. | |