diff options
Diffstat (limited to 'docs')
27 files changed, 152 insertions, 110 deletions
diff --git a/docs/source/markdown/podman-attach.1.md b/docs/source/markdown/podman-attach.1.md index b86b981d2..6340a9360 100644 --- a/docs/source/markdown/podman-attach.1.md +++ b/docs/source/markdown/podman-attach.1.md @@ -10,7 +10,7 @@ podman\-attach - Attach to a running container ## DESCRIPTION **podman attach** attaches to a running *container* using the *container's name* or *ID*, to either view its ongoing output or to control it interactively.\ -The *container* can detached from (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)](https://github.com/containers/common/blob/master/docs/containers.conf.5.md)** for more information. +The *container* can be detached from (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)](https://github.com/containers/common/blob/master/docs/containers.conf.5.md)** for more information. ## OPTIONS #### **--detach-keys**=**sequence** diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md index 474597938..9d03174c7 100644 --- a/docs/source/markdown/podman-build.1.md +++ b/docs/source/markdown/podman-build.1.md @@ -29,7 +29,7 @@ still be used by other tools when manually preprocessing them via `cpp -E`. When the URL is an archive, the contents of the URL is downloaded to a temporary location and extracted before execution. -When the URL is an Containerfile, the Containerfile is downloaded to a temporary +When the URL is a Containerfile, the Containerfile is downloaded to a temporary location. When a Git repository is set as the URL, the repository is cloned locally and @@ -173,7 +173,7 @@ proportion can be modified by changing the container's CPU share weighting relative to the weighting of all other running containers. To modify the proportion from the default of 1024, use the **--cpu-shares** -flag to set the weighting to 2 or higher. +option to set the weighting to 2 or higher. The proportion will only apply when CPU-intensive processes are running. When tasks in one container are idle, other containers can use the @@ -256,7 +256,7 @@ specifying **--disable-compression=false**. #### **--disable-content-trust** This is a Docker specific option to disable image verification to a container -registry and is not supported by Podman. This flag is a NOOP and provided +registry and is not supported by Podman. This option is a NOOP and provided solely for scripting compatibility. (This option is not available with the remote Podman client) #### **--dns**=*dns* @@ -266,7 +266,7 @@ Set custom DNS servers to be used during the build. 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. +option is necessary for every run. The special value **none** can be specified to disable creation of /etc/resolv.conf in the container by Podman. The /etc/resolv.conf file in the @@ -343,7 +343,7 @@ another process. Controls what type of isolation is used for running processes as part of `RUN` instructions. Recognized types include *oci* (OCI-compatible runtime, the default), *rootless* (OCI-compatible runtime invoked using a modified -configuration and its --rootless flag enabled, with *--no-new-keyring +configuration and its --rootless option enabled, with *--no-new-keyring --no-pivot* added to its *create* invocation, with network and UTS namespaces disabled, and IPC, PID, and user namespaces enabled; the default for unprivileged users), and *chroot* (an internal wrapper that leans more toward @@ -364,7 +364,7 @@ Add an image *label* (e.g. label=*value*) to the image metadata. Can be used multiple times. Users can set a special LABEL **io.containers.capabilities=CAP1,CAP2,CAP3** in -a Containerfile that specified the list of Linux capabilities required for the +a Containerfile that specifies the list of Linux capabilities required for the container to run properly. This label specified in a container image tells Podman to run the container with just these capabilities. Podman launches the container with just the specified capabilities, as long as this list of @@ -405,7 +405,7 @@ trillions). #### **--memory-swap**=*LIMIT* A limit value equal to memory plus swap. Must be used with the **-m** -(**--memory**) flag. The swap `LIMIT` should always be larger than **-m** +(**--memory**) option. The swap `LIMIT` should always be larger than **-m** (**--memory**) value. By default, the swap `LIMIT` will be set to double the value of --memory. @@ -424,7 +424,8 @@ Valid _mode_ values are: container full access to local system services such as D-bus and is therefore considered insecure. - **ns:**_path_: path to a network namespace to join. -- **private**: create a new namespace for the container (default). +- **private**: create a new namespace for the container (default) +- **\<network name|ID\>**: Join the network with the given name or ID, e.g. use `--network mynet` to join the network with the name mynet. Only supported for rootful users. #### **--no-cache** @@ -454,7 +455,7 @@ architecture of the host (for example `linux/arm`). If `--platform` is set, then the values of the `--arch`, `--os`, and `--variant` options will be overridden. -The `--platform` flag can be specified more than once, or given a +The `--platform` option can be specified more than once, or given a comma-separated list of values as its argument. When more than one platform is specified, the `--manifest` option should be used instead of the `--tag` option. @@ -471,23 +472,21 @@ the help of emulation provided by packages like `qemu-user-static`. #### **--pull** -When the option is specified or set to "true", pull the image. Raise an error -if the image could not be pulled, even if the image is present locally. +When the option is enabled or set explicitly to `true` (with *--pull=true*) +pull the image from the first registry it is found in as listed in registries.conf. +Raise an error if the image could not be pulled, even if the image is present locally. -If the option is disabled (with *--pull=false*) or not specified, pull the -image from the registry only if the image is not present locally. Raise an -error if the image is not found in the registries and is not present locally. +If the option is disabled (with *--pull=false*), pull the image from the +registry only if the image is not present locally. Raise an error if the image is not +in the registries and not present locally. -#### **--pull-always** +If the pull option is set to `always` (with *--pull=always*), +pull the image from the first registry it is found in as listed in registries.conf. +Raise an error if not found in the registries, even if the image is present locally. -Pull the image from the first registry it is found in as listed in -registries.conf. Raise an error if not found in the registries, even if the -image is present locally. - -#### **--pull-never** - -Do not pull the image from the registry, use only the local version. Raise an -error if the image is not present locally. +If the pull option is set to `never` (with *--pull=never*), +Do not pull the image from the registry, use only the local version. Raise an error +if the image is not present locally. #### **--quiet**, **-q** @@ -513,7 +512,7 @@ Pass secret information to be used in the Containerfile for building images in a safe way that will not end up stored in the final image, or be seen in other stages. The secret will be mounted in the container at the default location of `/run/secrets/id`. -To later use the secret, use the --mount flag in a `RUN` instruction within a `Containerfile`: +To later use the secret, use the --mount option in a `RUN` instruction within a `Containerfile`: `RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret` @@ -564,7 +563,7 @@ image) into a single new layer. SSH agent socket or keys to expose to the build. The socket path can be left empty to use the value of `default=$SSH_AUTH_SOCK` -To later use the ssh agent, use the --mount flag in a `RUN` instruction within a `Containerfile`: +To later use the ssh agent, use the --mount option in a `RUN` instruction within a `Containerfile`: `RUN --mount=type=ssh,id=id mycmd` @@ -711,7 +710,7 @@ than being relative to the host as it would be when run rootfull. #### **--uts**=*how* -Sets the configuration for UTS namespaces when the handling `RUN` instructions. +Sets the configuration for UTS namespaces when handling `RUN` instructions. The configured value can be "" (the empty string) or "container" to indicate that a new UTS namespace should be created, or it can be "host" to indicate that the UTS namespace in which `podman` itself is being run should be reused, @@ -889,6 +888,8 @@ $ podman build --no-cache -t imageName . $ podman build --layers --force-rm -t imageName . $ podman build --no-cache --rm=false -t imageName . + +$ podman build --network mynet . ``` ### Building a multi-architecture image using the --manifest option (requires emulation software) @@ -954,7 +955,7 @@ $ podman build -f dev/Containerfile https://10.10.10.1/podman/context.tar.gz ### .containerignore/.dockerignore If the file *.containerignore* or *.dockerignore* exists in the context directory, -`podman build` reads its contents. Use the `--ignorefile` flag to override the +`podman build` reads its contents. Use the `--ignorefile` option to override the .containerignore path location. Podman uses the content to exclude files and directories from the context directory, when executing COPY and ADD directives in the diff --git a/docs/source/markdown/podman-container-exists.1.md b/docs/source/markdown/podman-container-exists.1.md index d059276d7..cc5defe6b 100644 --- a/docs/source/markdown/podman-container-exists.1.md +++ b/docs/source/markdown/podman-container-exists.1.md @@ -23,21 +23,21 @@ The default is **false**. ## EXAMPLES -Check if an container called "webclient" exists in local storage. Here, the container does exist. +Check if a container called "webclient" exists in local storage. Here, the container does exist. ``` $ podman container exists webclient $ echo $? 0 ``` -Check if an container called "webbackend" exists in local storage. Here, the container does not exist. +Check if a container called "webbackend" exists in local storage. Here, the container does not exist. ``` $ podman container exists webbackend $ echo $? 1 ``` -Check if an container called "ubi8-working-container" created via Buildah exists in local storage. Here, the container does not exist. +Check if a container called "ubi8-working-container" created via Buildah exists in local storage. Here, the container does not exist. ``` $ podman container exists --external ubi8-working-container $ echo $? diff --git a/docs/source/markdown/podman-container-prune.1.md b/docs/source/markdown/podman-container-prune.1.md index 6e4aa35ff..b20936c15 100644 --- a/docs/source/markdown/podman-container-prune.1.md +++ b/docs/source/markdown/podman-container-prune.1.md @@ -20,13 +20,13 @@ Supported filters: | Filter | Description | | :----------------: | --------------------------------------------------------------------------- | -| *until* | Only remove containers created before given timestamp. | | *label* | Only remove containers, with (or without, in the case of label!=[...] is used) the specified labels. | - -The `until` *filter* can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. 10m, 1h30m) computed relative to the machine’s time. +| *until* | Only remove containers created before given timestamp. | The `label` *filter* accepts two formats. One is the `label`=*key* or `label`=*key*=*value*, which removes containers with the specified labels. The other format is the `label!`=*key* or `label!`=*key*=*value*, which removes containers without the specified labels. +The `until` *filter* can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. 10m, 1h30m) computed relative to the machine’s time. + #### **--force**, **-f** Do not provide an interactive prompt for container removal.\ diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index 6d69b2628..16b358745 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -127,7 +127,7 @@ If the host uses cgroups v1, the default is set to **host**. On cgroups v2 the d #### **--cgroups**=*mode* Determines whether the container will create CGroups. -Valid values are *enabled*, *disabled*, *no-conmon*, *split*, which the default being *enabled*. +Valid values are *enabled*, *disabled*, *no-conmon*, *split*, with the default being *enabled*. The *enabled* option will create a new cgroup under the cgroup-parent. The *disabled* option will force the container to not create CGroups, and thus conflicts with CGroup options (**--cgroupns** and **--cgroup-parent**). @@ -308,7 +308,7 @@ Set custom DNS servers. Invalid if using **--dns** and **--network** that is set 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** flags is necessary for every run. +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. @@ -369,7 +369,7 @@ Note: the **--gidmap** flag cannot be called in conjunction with the **--pod** f #### **--group-add**=*group|keep-groups* -Add additional groups to assign to primary user running within the container process. +Assign additional groups to the primary user running within the container process. - `keep-groups` is a special flag that tells Podman to keep the supplementary group access. @@ -695,7 +695,7 @@ Valid _mode_ values are: - **alias=name**: Add network-scoped alias for the container. - **ip=IPv4**: Specify a static ipv4 address for this container. - **ip=IPv6**: Specify a static ipv6 address for this container. - - **mac=MAC**: Specify a static mac address address for this container. + - **mac=MAC**: Specify a static mac address for this container. - **interface_name**: Specify a name for the created network interface inside the container. For example to set a static ipv4 address and a static mac address, use `--network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99`. @@ -715,7 +715,7 @@ Valid _mode_ values are: - **outbound_addr6=INTERFACE**: Specify the outbound interface slirp should bind to (ipv6 traffic only). - **outbound_addr6=IPv6**: Specify the outbound ipv6 address slirp should bind to. - **port_handler=rootlesskit**: Use rootlesskit for port forwarding. Default. - Note: Rootlesskit changes the source IP address of incoming packets to a IP address in the container network namespace, usually `10.0.2.100`. If your application requires the real source IP address, e.g. web server logs, use the slirp4netns port handler. The rootlesskit port handler is also used for rootless containers when connected to user-defined networks. + Note: Rootlesskit changes the source IP address of incoming packets to an IP address in the container network namespace, usually `10.0.2.100`. If your application requires the real source IP address, e.g. web server logs, use the slirp4netns port handler. The rootlesskit port handler is also used for rootless containers when connected to user-defined networks. - **port_handler=slirp4netns**: Use the slirp4netns port forwarding, it is slower than rootlesskit but preserves the correct source IP address. This port handler cannot be used for user-defined networks. #### **--network-alias**=*alias* @@ -739,6 +739,8 @@ This option conflicts with **--add-host**. Whether to disable OOM Killer for the container or not. +This flag is not supported on cgroups V2 systems. + #### **--oom-score-adj**=*num* Tune the host's OOM preferences for containers (accepts -1000 to 1000) @@ -1028,7 +1030,7 @@ Podman will setup tmpfs mount points in the following directories: It will also set the default stop signal to SIGRTMIN+3. -This allow systemd to run in a confined container without any modifications. +This allows systemd to run in a confined container without any modifications. Note: On `SELinux` systems, systemd attempts to write to the cgroup file system. Containers writing to the cgroup file system are denied by default. @@ -1307,7 +1309,7 @@ Only the current container can use a private volume. Note: Do not relabel system files and directories. Relabeling system content might cause other confined services on your machine to fail. For these types -of containers we recommend that disable SELinux separation. The option +of containers we recommend disabling SELinux separation. The option `--security-opt label=disable` disables SELinux separation for containers used in the build. For example if a user wanted to volume mount their entire home directory into a container, they need to disable SELinux separation. @@ -1372,7 +1374,7 @@ the volume will not be able to change their privilege. By default volumes are mounted with `nosuid`. Mounting the volume with the noexec option means that no executables on the -volume will be able to executed within the container. +volume will be able to be executed within the container. Mounting the volume with the nodev option means that no devices on the volume will be able to be used by processes within the container. By default volumes @@ -1540,7 +1542,7 @@ $ podman create --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 alpine ### Rootless Containers -Podman runs as a non root user on most systems. This feature requires that a new enough version of shadow-utils +Podman runs as a non-root user on most systems. This feature requires that a new enough version of shadow-utils be installed. The shadow-utils package must include the newuidmap and newgidmap executables. Note: RHEL7 and Centos 7 will not have this feature until RHEL7.7 is released. diff --git a/docs/source/markdown/podman-generate-kube.1.md b/docs/source/markdown/podman-generate-kube.1.md index 3586341a9..8cd35140e 100644 --- a/docs/source/markdown/podman-generate-kube.1.md +++ b/docs/source/markdown/podman-generate-kube.1.md @@ -6,7 +6,7 @@ podman-generate-kube - Generate Kubernetes YAML based on containers, pods or vol **podman generate kube** [*options*] *container...* | *pod...* | *volume...* ## DESCRIPTION -**podman generate kube** will generate Kubernetes YAML (v1 specification) from Podman containers, pods or volumes. Whether +**podman generate kube** will generate Kubernetes YAML (v1 specification) from Podman containers, pods or volumes. Regardless of whether the input is for containers or pods, Podman will always generate the specification as a Pod. The input may be in the form of one or more containers, pods or volumes names or IDs. diff --git a/docs/source/markdown/podman-image-prune.1.md b/docs/source/markdown/podman-image-prune.1.md index 66edad207..db17f97fb 100644 --- a/docs/source/markdown/podman-image-prune.1.md +++ b/docs/source/markdown/podman-image-prune.1.md @@ -31,13 +31,14 @@ Supported filters: | Filter | Description | | :----------------: | --------------------------------------------------------------------------- | -| *until* | Only remove images created before given timestamp. | | *label* | Only remove images, with (or without, in the case of label!=[...] is used) the specified labels. | +| *until* | Only remove images created before given timestamp. | -The `until` *filter* can be Unix timestamps, date formatted timestamps or Go duration strings (e.g. 10m, 1h30m) computed relative to the machine’s time. The `label` *filter* accepts two formats. One is the `label`=*key* or `label`=*key*=*value*, which removes containers with the specified labels. The other format is the `label!`=*key* or `label!`=*key*=*value*, which removes containers without the specified labels. +The `until` *filter* can be Unix timestamps, date formatted timestamps or Go duration strings (e.g. 10m, 1h30m) computed relative to the machine’s time. + #### **--force**, **-f** Do not provide an interactive prompt for container removal. diff --git a/docs/source/markdown/podman-image-sign.1.md b/docs/source/markdown/podman-image-sign.1.md index 8758b8861..42ddd7eb2 100644 --- a/docs/source/markdown/podman-image-sign.1.md +++ b/docs/source/markdown/podman-image-sign.1.md @@ -56,7 +56,7 @@ The write (and read) location for signatures is defined in YAML-based configuration files in /etc/containers/registries.d/ for root, or $HOME/.config/containers/registries.d for non-root users. When you sign an image, Podman will use those configuration files to determine -where to write the signature based on the the name of the originating +where to write the signature based on the name of the originating registry or a default storage value unless overridden with the --directory option. For example, consider the following configuration file. diff --git a/docs/source/markdown/podman-images.1.md b/docs/source/markdown/podman-images.1.md index 8db291fb4..f1d9d4816 100644 --- a/docs/source/markdown/podman-images.1.md +++ b/docs/source/markdown/podman-images.1.md @@ -25,27 +25,32 @@ Show image digests #### **--filter**=*filter*, **-f** -Filter output based on conditions provided +Provide filter values. - Filters: +The *filters* argument format is of `key=value`. If there is more than one *filter*, then pass multiple OPTIONS: **--filter** *foo=bar* **--filter** *bif=baz*. - **since=IMAGE** - Filter on images created after the given IMAGE (name or tag). +Supported filters: - **before=IMAGE** - Filter on images created before the given IMAGE (name or tag). +| Filter | Description | +| :----------------: | --------------------------------------------------------------------------------------------- | +| *before* | Filter by images created before the given IMAGE (name or tag). | +| *dangling* | Filter by dangling (unused) images. | +| *label* | Filter by images with (or without, in the case of label!=[...] is used) the specified labels. | +| *readonly* | Filter by read-only or read/write images. | +| *reference* | Filter by image name. | +| *since* | Filter by images created after the given IMAGE (name or tag). | - **dangling - Show dangling images. Dangling images are a file system layer that was used in a previous build of an image and is no longer referenced by any image. They are denoted with the `<none>` tag, consume disk space and serve no active purpose. +The `before` *filter* accepts formats: `<image-name>[:<tag>]`, `<image id>` or `<image@digest>`. - **label** - Filter by images labels key and/or value. +The `dangling` *filter* shows images that are taking up disk space and serve no purpose. Dangling image is a file system layer that was used in a previous build of an image and is no longer referenced by any image. They are denoted with the `<none>` tag, consume disk space and serve no active purpose. - **readonly - Show only read only images or Read/Write images. The default is to show both. Read/Only images can be configured by modifying the "additionalimagestores" in the /etc/containers/storage.conf file. +The `label` *filter* accepts two formats. One is the `label`=*key* or `label`=*key*=*value*, which shows images with the specified labels. The other format is the `label!`=*key* or `label!`=*key*=*value*, which shows images without the specified labels. - **reference=** - Filter by image name, specified as regular expressions. +The `readonly` *filter* shows, as a default, both read-only and read/write images. Read-only images can be configured by modifying the `additionalimagestores` in the `/etc/containers/storage.conf` file. + +The `reference` *filter* accepts the pattern of an image reference `<image-name>[:<tag>]`. + +The `since` *filter* accepts formats: `<image-name>[:<tag>]`, `<image id>` or `<image@digest>`. #### **--format**=*format* diff --git a/docs/source/markdown/podman-logs.1.md b/docs/source/markdown/podman-logs.1.md index 888279990..b8b0b44ba 100644 --- a/docs/source/markdown/podman-logs.1.md +++ b/docs/source/markdown/podman-logs.1.md @@ -20,7 +20,7 @@ any logs at the time you execute podman logs). Follow log output. Default is false. Note: If you are following a container which is removed `podman container rm` -or removed on exit `podman run --rm ...`, then there is a chance the the log +or removed on exit `podman run --rm ...`, then there is a chance that the log file will be removed before `podman logs` reads the final content. #### **--latest**, **-l** diff --git a/docs/source/markdown/podman-machine-list.1.md b/docs/source/markdown/podman-machine-list.1.md index b448f890a..d1333f1e2 100644 --- a/docs/source/markdown/podman-machine-list.1.md +++ b/docs/source/markdown/podman-machine-list.1.md @@ -39,7 +39,7 @@ Valid placeholders for the Go template are listed below: | .VMType | VM type | | .Port | SSH Port to use to connect to VM| | .RemoteUsername | VM Username for rootless Podman | -| .IdentityPath | Path to ssh identify file | +| .IdentityPath | Path to ssh identity file | #### **--help** diff --git a/docs/source/markdown/podman-manifest-push.1.md b/docs/source/markdown/podman-manifest-push.1.md index 38201555e..3a68f6228 100644 --- a/docs/source/markdown/podman-manifest-push.1.md +++ b/docs/source/markdown/podman-manifest-push.1.md @@ -78,22 +78,22 @@ Require HTTPS and verify certificates when talking to container registries. (def **dir:**_path_ An existing local directory _path_ storing the manifest, layer tarballs and signatures as individual files. This is a non-standardized format, primarily useful for debugging or noninvasive container inspection. - $ podman manfiest push mylist:v1.11 dir:/tmp/mylist + $ podman manifest push mylist:v1.11 dir:/tmp/mylist **docker://**_docker-reference_ An image in a registry implementing the "Docker Registry HTTP API V2". By default, uses the authorization state in `$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)`. - $ podman manfiest push mylist:v1.11 docker://registry.example.org/mylist:v1.11 + $ podman manifest push mylist:v1.11 docker://registry.example.org/mylist:v1.11 **docker-archive:**_path_[**:**_docker-reference_] An image is stored in the `docker save` formatted file. _docker-reference_ is only used when creating such a file, and it must not contain a digest. - $ podman manfiest push mylist:v1.11 docker-archive:/tmp/mylist + $ podman manifest push mylist:v1.11 docker-archive:/tmp/mylist **docker-daemon:**_docker-reference_ An image in _docker-reference_ format stored in the docker daemon internal storage. _docker-reference_ must contain a tag. - $ podman manfiest push mylist:v1.11 docker-daemon:registry.example.org/mylist:v1.11 + $ podman manifest push mylist:v1.11 docker-daemon:registry.example.org/mylist:v1.11 **oci-archive:**_path_**:**_tag_ An image _tag_ in a directory compliant with "Open Container Image Layout Specification" at _path_. diff --git a/docs/source/markdown/podman-mount.1.md b/docs/source/markdown/podman-mount.1.md index a4ce25bce..33524029c 100644 --- a/docs/source/markdown/podman-mount.1.md +++ b/docs/source/markdown/podman-mount.1.md @@ -14,7 +14,7 @@ accessed from the host, and returns its location. If you execute the command without any arguments, Podman will list all of the currently mounted containers, including external containers. External containers are -containers in container/storage by tools other then Podman. For example Buildah and +containers in container/storage by tools other than Podman. For example Buildah and CRI-O. Rootless mode only supports mounting VFS driver, unless you enter the user namespace diff --git a/docs/source/markdown/podman-network-create.1.md b/docs/source/markdown/podman-network-create.1.md index d48509581..5be0c2595 100644 --- a/docs/source/markdown/podman-network-create.1.md +++ b/docs/source/markdown/podman-network-create.1.md @@ -39,14 +39,15 @@ Additionally the `bridge` driver supports the following option: The `macvlan` and `ipvlan` driver support the following options: - `parent`: The host device which should be used for the macvlan interface. Defaults to the default route interface. -- `mode`: This options sets the specified ip/macvlan mode on the interface. +- `mode`: This option sets the specified ip/macvlan mode on the interface. - Supported values for `macvlan` are `bridge`, `private`, `vepa`, `passthru`. Defaults to `bridge`. - Supported values for `ipvlan` are `l2`, `l3`, `l3s`. Defaults to `l2`. #### **--gateway** Define a gateway for the subnet. If you want to provide a gateway address, you must also provide a -*subnet* option. +*subnet* option. Can be specified multiple times. +The argument order of the **--subnet**, **--gateway** and **--ip-range** options must match. #### **--internal** @@ -56,7 +57,8 @@ automatically disabled. #### **--ip-range** Allocate container IP from a range. The range must be a complete subnet and in CIDR notation. The *ip-range* option -must be used with a *subnet* option. +must be used with a *subnet* option. Can be specified multiple times. +The argument order of the **--subnet**, **--gateway** and **--ip-range** options must match. #### **--label** @@ -64,11 +66,13 @@ Set metadata for a network (e.g., --label mykey=value). #### **--subnet** -The subnet in CIDR notation. +The subnet in CIDR notation. Can be specified multiple times to allocate more than one subnet for this network. +The argument order of the **--subnet**, **--gateway** and **--ip-range** options must match. +This is useful to set a static ipv4 and ipv6 subnet. #### **--ipv6** -Enable IPv6 (Dual Stack) networking. +Enable IPv6 (Dual Stack) networking. If not subnets are given it will allocate a ipv4 and ipv6 subnet. ## EXAMPLE @@ -102,6 +106,12 @@ $ podman network create --subnet 192.168.55.0/24 --ip-range 192.168.55.128/25 cni-podman5 ``` +Create a network with a static ipv4 and ipv6 subnet and set a gateway. +``` +$ podman network create --subnet 192.168.55.0/24 --gateway 192.168.55.3 --subnet fd52:2a5a:747e:3acd::/64 --gateway fd52:2a5a:747e:3acd::10 +podman4 +``` + Create a Macvlan based network using the host interface eth0. Macvlan networks can only be used as root. ``` # podman network create -d macvlan -o parent=eth0 newnet diff --git a/docs/source/markdown/podman-network-exists.1.md b/docs/source/markdown/podman-network-exists.1.md index ee62a830e..44c145cd9 100644 --- a/docs/source/markdown/podman-network-exists.1.md +++ b/docs/source/markdown/podman-network-exists.1.md @@ -29,7 +29,7 @@ $ echo $? $ ``` -Check if an network called `webbackend` exists (the network does not actually exist). +Check if a network called `webbackend` exists (the network does not actually exist). ``` $ podman network exists webbackend $ echo $? diff --git a/docs/source/markdown/podman-network-prune.1.md b/docs/source/markdown/podman-network-prune.1.md index d35decb1b..a1dc5d85c 100644 --- a/docs/source/markdown/podman-network-prune.1.md +++ b/docs/source/markdown/podman-network-prune.1.md @@ -18,17 +18,20 @@ Do not prompt for confirmation #### **--filter** -Filter output based on conditions given. -Multiple filters can be given with multiple uses of the --filter option. -Filters with the same key work inclusive with the only exception being -`label` which is exclusive. Filters with different keys always work exclusive. +Provide filter values. -Valid filters are listed below: +The *filters* argument format is of `key=value`. If there is more than one *filter*, then pass multiple OPTIONS: **--filter** *foo=bar* **--filter** *bif=baz*. -| **Filter** | **Description** | -| ---------- | ------------------------------------------------------------------------------------- | -| label | [Key] or [Key=Value] Label assigned to a network | -| until | only remove networks created before given timestamp | +Supported filters: + +| Filter | Description | +| :----------------: | --------------------------------------------------------------------------- | +| *label* | Only remove networks, with (or without, in the case of label!=[...] is used) the specified labels. | +| *until* | Only remove networks created before given timestamp. | + +The `label` *filter* accepts two formats. One is the `label`=*key* or `label`=*key*=*value*, which removes networks with the specified labels. The other format is the `label!`=*key* or `label!`=*key*=*value*, which removes networks without the specified labels. + +The `until` *filter* can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. 10m, 1h30m) computed relative to the machine’s time. ## EXAMPLE Prune networks diff --git a/docs/source/markdown/podman-play-kube.1.md b/docs/source/markdown/podman-play-kube.1.md index 390058b4a..a056640e7 100644 --- a/docs/source/markdown/podman-play-kube.1.md +++ b/docs/source/markdown/podman-play-kube.1.md @@ -179,7 +179,7 @@ Valid _mode_ values are: - **alias=name**: Add network-scoped alias for the container. - **ip=IPv4**: Specify a static ipv4 address for this container. - **ip=IPv6**: Specify a static ipv6 address for this container. - - **mac=MAC**: Specify a static mac address address for this container. + - **mac=MAC**: Specify a static mac address for this container. - **interface_name**: Specify a name for the created network interface inside the container. For example to set a static ipv4 address and a static mac address, use `--network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99`. @@ -198,7 +198,7 @@ Valid _mode_ values are: - **outbound_addr6=INTERFACE**: Specify the outbound interface slirp should bind to (ipv6 traffic only). - **outbound_addr6=IPv6**: Specify the outbound ipv6 address slirp should bind to. - **port_handler=rootlesskit**: Use rootlesskit for port forwarding. Default. - Note: Rootlesskit changes the source IP address of incoming packets to a IP address in the container network namespace, usually `10.0.2.100`. If your application requires the real source IP address, e.g. web server logs, use the slirp4netns port handler. The rootlesskit port handler is also used for rootless containers when connected to user-defined networks. + Note: Rootlesskit changes the source IP address of incoming packets to an IP address in the container network namespace, usually `10.0.2.100`. If your application requires the real source IP address, e.g. web server logs, use the slirp4netns port handler. The rootlesskit port handler is also used for rootless containers when connected to user-defined networks. - **port_handler=slirp4netns**: Use the slirp4netns port forwarding, it is slower than rootlesskit but preserves the correct source IP address. This port handler cannot be used for user-defined networks. #### **--no-hosts** diff --git a/docs/source/markdown/podman-pod-create.1.md b/docs/source/markdown/podman-pod-create.1.md index c9255d37f..e7eae2aa2 100644 --- a/docs/source/markdown/podman-pod-create.1.md +++ b/docs/source/markdown/podman-pod-create.1.md @@ -171,7 +171,7 @@ Valid _mode_ values are: - **alias=name**: Add network-scoped alias for the container. - **ip=IPv4**: Specify a static ipv4 address for this container. - **ip=IPv6**: Specify a static ipv6 address for this container. - - **mac=MAC**: Specify a static mac address address for this container. + - **mac=MAC**: Specify a static mac address for this container. - **interface_name**: Specify a name for the created network interface inside the container. For example to set a static ipv4 address and a static mac address, use `--network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99`. @@ -191,7 +191,7 @@ Valid _mode_ values are: - **outbound_addr6=INTERFACE**: Specify the outbound interface slirp should bind to (ipv6 traffic only). - **outbound_addr6=IPv6**: Specify the outbound ipv6 address slirp should bind to. - **port_handler=rootlesskit**: Use rootlesskit for port forwarding. Default. - Note: Rootlesskit changes the source IP address of incoming packets to a IP address in the container network namespace, usually `10.0.2.100`. If your application requires the real source IP address, e.g. web server logs, use the slirp4netns port handler. The rootlesskit port handler is also used for rootless containers when connected to user-defined networks. + Note: Rootlesskit changes the source IP address of incoming packets to an IP address in the container network namespace, usually `10.0.2.100`. If your application requires the real source IP address, e.g. web server logs, use the slirp4netns port handler. The rootlesskit port handler is also used for rootless containers when connected to user-defined networks. - **port_handler=slirp4netns**: Use the slirp4netns port forwarding, it is slower than rootlesskit but preserves the correct source IP address. This port handler cannot be used for user-defined networks. #### **--network-alias**=*alias* diff --git a/docs/source/markdown/podman-pod-logs.1.md b/docs/source/markdown/podman-pod-logs.1.md index 5adcd9df5..bc38c33fd 100644 --- a/docs/source/markdown/podman-pod-logs.1.md +++ b/docs/source/markdown/podman-pod-logs.1.md @@ -22,7 +22,7 @@ By default `podman pod logs` retrieves logs for all the containers available wit Follow log output. Default is false. Note: If you are following a pod which is removed `podman pod rm`, then there is a -chance the the log file will be removed before `podman pod logs` reads the final content. +chance that the log file will be removed before `podman pod logs` reads the final content. #### **--latest**, **-l** diff --git a/docs/source/markdown/podman-pull.1.md b/docs/source/markdown/podman-pull.1.md index 6a1240269..fe4af44d3 100644 --- a/docs/source/markdown/podman-pull.1.md +++ b/docs/source/markdown/podman-pull.1.md @@ -17,7 +17,7 @@ podman pull copies an image from a registry onto the local machine. The command *IMPORTANT: Images are stored in local image storage.* ## SOURCE -SOURCE is the location from the container image is pulled from. It supports all transports from **[containers-transports(5)](https://github.com/containers/image/blob/main/docs/containers-transports.5.md)**. If no transport is specified, the input is subject to short-name resolution and the `docker` (i.e., container registry) transport is used. For remote clients, `docker` is the only supported transport. +SOURCE is the location from which the container image is pulled from. It supports all transports from **[containers-transports(5)](https://github.com/containers/image/blob/main/docs/containers-transports.5.md)**. If no transport is specified, the input is subject to short-name resolution and the `docker` (i.e., container registry) transport is used. For remote clients, `docker` is the only supported transport. ``` # Pull from a container registry diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index b96abeaa2..014b50c6c 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -341,7 +341,7 @@ Set custom DNS servers. Invalid if using **--dns** with **--network** that is se 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** flags is necessary for every run. +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. @@ -411,7 +411,7 @@ Note: the **--gidmap** flag cannot be called in conjunction with the **--pod** f #### **--group-add**=*group|keep-groups* -Add additional groups to assign to primary user running within the container process. +Assign additional groups to the primary user running within the container process. - `keep-groups` is a special flag that tells Podman to keep the supplementary group access. @@ -722,7 +722,7 @@ Valid _mode_ values are: - **alias=name**: Add network-scoped alias for the container. - **ip=IPv4**: Specify a static ipv4 address for this container. - **ip=IPv6**: Specify a static ipv6 address for this container. - - **mac=MAC**: Specify a static mac address address for this container. + - **mac=MAC**: Specify a static mac address for this container. - **interface_name**: Specify a name for the created network interface inside the container. For example to set a static ipv4 address and a static mac address, use `--network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99`. @@ -742,7 +742,7 @@ Valid _mode_ values are: - **outbound_addr6=INTERFACE**: Specify the outbound interface slirp should bind to (ipv6 traffic only). - **outbound_addr6=IPv6**: Specify the outbound ipv6 address slirp should bind to. - **port_handler=rootlesskit**: Use rootlesskit for port forwarding. Default. - Note: Rootlesskit changes the source IP address of incoming packets to a IP address in the container network namespace, usually `10.0.2.100`. If your application requires the real source IP address, e.g. web server logs, use the slirp4netns port handler. The rootlesskit port handler is also used for rootless containers when connected to user-defined networks. + Note: Rootlesskit changes the source IP address of incoming packets to an IP address in the container network namespace, usually `10.0.2.100`. If your application requires the real source IP address, e.g. web server logs, use the slirp4netns port handler. The rootlesskit port handler is also used for rootless containers when connected to user-defined networks. - **port_handler=slirp4netns**: Use the slirp4netns port forwarding, it is slower than rootlesskit but preserves the correct source IP address. This port handler cannot be used for user-defined networks. #### **--network-alias**=*alias* @@ -767,6 +767,8 @@ This option conflicts with **--add-host**. Whether to disable OOM Killer for the container or not. +This flag is not supported on cgroups V2 systems. + #### **--oom-score-adj**=*num* Tune the host's OOM preferences for containers (accepts values from **-1000** to **1000**). @@ -1377,7 +1379,7 @@ The **Z** option tells Podman to label the content with a private unshared label Note: Do not relabel system files and directories. Relabeling system content might cause other confined services on your machine to fail. For these types -of containers we recommend that disable SELinux separation. The option +of containers we recommend disabling SELinux separation. The option `--security-opt label=disable` disables SELinux separation for the container. For example if a user wanted to volume mount their entire home directory into a container, they need to disable SELinux separation. @@ -1394,6 +1396,10 @@ directory will be the lower, and the container storage directory will be the upper. Modifications to the mount point are destroyed when the container finishes executing, similar to a tmpfs mount point being unmounted. + For advanced users overlay option also supports custom non-volatile `upperdir` and `workdir` +for the overlay mount. Custom `upperdir` and `workdir` can be fully managed by the users themselves +and `podman` will not remove it on lifecycle completion. Example `:O,upperdir=/some/upper,workdir=/some/work` + Subsequent executions of the container will see the original source directory content, any changes from previous container executions no longer exist. @@ -1444,7 +1450,7 @@ the volume will not be able to change their privilege. By default volumes are mounted with **nosuid**. Mounting the volume with the **noexec** option means that no executables on the -volume will be able to executed within the container. +volume will be able to be executed within the container. Mounting the volume with the **nodev** option means that no devices on the volume will be able to be used by processes within the container. By default volumes @@ -1920,7 +1926,7 @@ $ podman run --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 alpine ip ### Rootless Containers -Podman runs as a non root user on most systems. This feature requires that a new enough version of **shadow-utils** +Podman runs as a non-root user on most systems. This feature requires that a new enough version of **shadow-utils** be installed. The **shadow-utils** package must include the **newuidmap**(1) and **newgidmap**(1) executables. Note: RHEL7 and Centos 7 will not have this feature until RHEL7.7 is released. diff --git a/docs/source/markdown/podman-stats.1.md b/docs/source/markdown/podman-stats.1.md index bbb4bcb06..e3ffc74ca 100644 --- a/docs/source/markdown/podman-stats.1.md +++ b/docs/source/markdown/podman-stats.1.md @@ -98,6 +98,10 @@ ID NAME MEM USAGE / LIMIT 6eae9e25a564 clever_bassi 3.031MB / 16.7GB ``` +Note: When using a slirp4netns network, the traffic send via the port forwarding will be accounted +to the `lo` device. Traffic accounted to `lo` is not accounted in the stats output. + + ## SEE ALSO **[podman(1)](podman.1.md)** diff --git a/docs/source/markdown/podman-system-prune.1.md b/docs/source/markdown/podman-system-prune.1.md index d8b218db2..fb9ed44d6 100644 --- a/docs/source/markdown/podman-system-prune.1.md +++ b/docs/source/markdown/podman-system-prune.1.md @@ -22,16 +22,18 @@ Recursively remove all unused pod, container, image and volume data (Maximum 50 Provide filter values. -The --filter flag format is of “key=value”. If there is more than one filter, then pass multiple flags (e.g., --filter "foo=bar" --filter "bif=baz") +The *filters* argument format is of `key=value`. If there is more than one *filter*, then pass multiple OPTIONS: **--filter** *foo=bar* **--filter** *bif=baz*. Supported filters: -- `until` (_timestamp_) - only remove containers and images created before given timestamp -- `label` (label=_key_, label=_key=value_, label!=_key_, or label!=_key=value_) - only remove containers and images, with (or without, in case label!=... is used) the specified labels. +| Filter | Description | +| :----------------: | --------------------------------------------------------------------------- | +| *label* | Only remove containers and images, with (or without, in the case of label!=[...] is used) the specified labels. | +| *until* | Only remove containers and images created before given timestamp. | -The until filter can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. 10m, 1h30m) computed relative to the machine’s time. +The `label` *filter* accepts two formats. One is the `label`=*key* or `label`=*key*=*value*, which removes containers and images with the specified labels. The other format is the `label!`=*key* or `label!`=*key*=*value*, which removes containers and images without the specified labels. -The label filter accepts two formats. One is the label=... (label=_key_ or label=_key=value_), which removes containers and images with the specified labels. The other format is the label!=... (label!=_key_ or label!=_key=value_), which removes containers and images without the specified labels. +The `until` *filter* can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. 10m, 1h30m) computed relative to the machine’s time. #### **--force**, **-f** diff --git a/docs/source/markdown/podman-untag.1.md b/docs/source/markdown/podman-untag.1.md index 8314e5f9b..0dd882a92 100644 --- a/docs/source/markdown/podman-untag.1.md +++ b/docs/source/markdown/podman-untag.1.md @@ -9,7 +9,7 @@ podman\-untag - Removes one or more names from a locally-stored image **podman image untag** *image* [*name*[:*tag*]...] ## DESCRIPTION -Remove one or more names from an image in the local storage. The image can be referred to by ID or reference. If a no name is specified, all names are removed the image. If a specified name is a short name and does not include a registry `localhost/` will be prefixed (e.g., `fedora` -> `localhost/fedora`). If a specified name does not include a tag `:latest` will be appended (e.g., `localhost/fedora` -> `localhost/fedora:latest`). +Remove one or more names from an image in the local storage. The image can be referred to by ID or reference. If no name is specified, all names are removed from the image. If a specified name is a short name and does not include a registry, `localhost/` will be prefixed (e.g., `fedora` -> `localhost/fedora`). If a specified name does not include a tag, `:latest` will be appended (e.g., `localhost/fedora` -> `localhost/fedora:latest`). ## OPTIONS diff --git a/docs/source/markdown/podman-volume-exists.1.md b/docs/source/markdown/podman-volume-exists.1.md index dbdf0985c..28d42e987 100644 --- a/docs/source/markdown/podman-volume-exists.1.md +++ b/docs/source/markdown/podman-volume-exists.1.md @@ -28,7 +28,7 @@ $ echo $? $ ``` -Check if an volume called `mysql` exists (the volume does not actually exist). +Check if a volume called `mysql` exists (the volume does not actually exist). ``` $ podman volume exists mysql $ echo $? diff --git a/docs/source/markdown/podman-volume-prune.1.md b/docs/source/markdown/podman-volume-prune.1.md index 012567957..2028e42f2 100644 --- a/docs/source/markdown/podman-volume-prune.1.md +++ b/docs/source/markdown/podman-volume-prune.1.md @@ -21,12 +21,20 @@ Do not prompt for confirmation. #### **--filter** -Filter volumes to be pruned. Volumes can be filtered by the following attributes: +Provide filter values. -| **Filter** | **Description** | -| ---------- | ------------------------------------------------------------------------------------- | -| label | [Key] or [Key=Value] Label assigned to a volume | -| until | Only remove volumes created before given timestamp | +The *filters* argument format is of `key=value`. If there is more than one *filter*, then pass multiple OPTIONS: **--filter** *foo=bar* **--filter** *bif=baz*. + +Supported filters: + +| Filter | Description | +| :----------------: | --------------------------------------------------------------------------- | +| *label* | Only remove volumes, with (or without, in the case of label!=[...] is used) the specified labels. | +| *until* | Only remove volumes created before given timestamp. | + +The `label` *filter* accepts two formats. One is the `label`=*key* or `label`=*key*=*value*, which removes volumes with the specified labels. The other format is the `label!`=*key* or `label!`=*key*=*value*, which removes volumes without the specified labels. + +The `until` *filter* can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. 10m, 1h30m) computed relative to the machine’s time. #### **--help** diff --git a/docs/source/markdown/podman.1.md b/docs/source/markdown/podman.1.md index bb8f889f5..0fe30bf0f 100644 --- a/docs/source/markdown/podman.1.md +++ b/docs/source/markdown/podman.1.md @@ -217,7 +217,7 @@ Set default `--storage-opts` value. #### **TMPDIR** -Set the the temporary storage location of downloaded container images. Podman defaults to use `/var/tmp`. +Set the temporary storage location of downloaded container images. Podman defaults to use `/var/tmp`. #### **XDG_CONFIG_HOME** @@ -373,7 +373,7 @@ The storage configuration file specifies all of the available container storage When Podman runs in rootless mode, the file `$HOME/.config/containers/storage.conf` is used instead of the system defaults. -If the **CONTAINERS_STORAGE_CONF** environment variable is set, the its value is used for the storage.conf file rather than the default. +If the **CONTAINERS_STORAGE_CONF** environment variable is set, then its value is used for the storage.conf file rather than the default. ## Rootless mode Podman can also be used as non-root user. When podman runs in rootless mode, a user namespace is automatically created for the user, defined in /etc/subuid and /etc/subgid. |