diff options
Diffstat (limited to 'docs')
19 files changed, 325 insertions, 55 deletions
diff --git a/docs/remote-docs.sh b/docs/remote-docs.sh index 4c2602f80..f281c19ff 100755 --- a/docs/remote-docs.sh +++ b/docs/remote-docs.sh @@ -6,7 +6,9 @@ PLATFORM=$1 ## linux, windows or darwin TARGET=${2} ## where to output files SOURCES=${@:3} ## directories to find markdown files -# Overridden for testing. Native podman-remote binary expected filepaths +# This is a *native* binary, one we can run on this host. (This script can be +# invoked in a cross-compilation environment, so even if PLATFORM=windows +# we need an actual executable that we can invoke). if [[ -z "$PODMAN" ]]; then case $(env -i HOME=$HOME PATH=$PATH go env GOOS) in windows) diff --git a/docs/source/markdown/podman-container-clone.1.md b/docs/source/markdown/podman-container-clone.1.md index 3b9d79862..9baedfd36 100644 --- a/docs/source/markdown/podman-container-clone.1.md +++ b/docs/source/markdown/podman-container-clone.1.md @@ -11,6 +11,14 @@ podman\-container\-clone - Creates a copy of an existing container ## OPTIONS +#### **--blkio-weight**=*weight* + +Block IO weight (relative weight) accepts a weight value between 10 and 1000. + +#### **--blkio-weight-device**=*weight* + +Block IO weight (relative device weight, format: `DEVICE_NAME:WEIGHT`). + #### **--cpu-period**=*limit* Set the CPU period for the Completely Fair Scheduler (CFS), which is a @@ -126,6 +134,14 @@ If none are specified, the original container's CPU memory nodes are used. Remove the original container that we are cloning once used to mimic the configuration. +#### **--device-read-bps**=*path* + +Limit read rate (bytes per second) from a device (e.g. --device-read-bps=/dev/sda:1mb). + +#### **--device-write-bps**=*path* + +Limit write rate (bytes per second) to a device (e.g. --device-write-bps=/dev/sda:1mb) + #### **--force**, **-f** Force removal of the original container that we are cloning. Can only be used in conjunction with **--destroy**. diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index 67bb573e2..b3e707e45 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -738,9 +738,12 @@ Valid _mode_ values are: #### **--network-alias**=*alias* -Add a network-scoped alias for the container, setting the alias for all networks that the container joins. To set a name only for a specific network, use the alias option as described under the **--network** option. -Network aliases work only with the bridge networking mode. This option can be specified multiple times. -NOTE: A container will only have access to aliases on the first network that it joins. This is a limitation that will be removed in a later release. +Add a network-scoped alias for the container, setting the alias for all networks that the container joins. To set a +name only for a specific network, use the alias option as described under the **--network** option. +If the network has DNS enabled (`podman network inspect -f {{.DNSEnabled}} <name>`), +these aliases can be used for name resolution on the given network. This option can be specified multiple times. +NOTE: When using CNI a container will only have access to aliases on the first network that it joins. This limitation does +not exist with netavark/aardvark-dns. #### **--no-healthcheck** @@ -1568,7 +1571,7 @@ $ podman create -v /var/lib/design:/var/lib/design --group-add keep-groups ubi8 ### Configure execution domain for containers using personality flag ``` -$ podman create --name container1 --personaity=LINUX32 fedora bash +$ podman create --name container1 --personality=LINUX32 fedora bash ``` ### Create a container with external rootfs mounted as an overlay diff --git a/docs/source/markdown/podman-generate-systemd.1.md b/docs/source/markdown/podman-generate-systemd.1.md index 50881a509..fc2ce171e 100644 --- a/docs/source/markdown/podman-generate-systemd.1.md +++ b/docs/source/markdown/podman-generate-systemd.1.md @@ -14,6 +14,13 @@ Generating unit files for a pod requires the pod to be created with an infra con _Note: If you use this command with the remote client, including Mac and Windows (excluding WSL2) machines, you would still have to place the generated units on the remote system. Moreover, please make sure that the XDG_RUNTIME_DIR environment variable is set. If unset, you may set it via `export XDG_RUNTIME_DIR=/run/user/$(id -u)`._ +_Note: The generated `podman run` command contains an `--sdnotify` option with the value taken from the container. +If the container does not have any explicitly set value or the value is set to __ignore__, the value __conmon__ is used. +The reason for overriding the default value __container__ is that almost no container workloads send notify messages. +Systemd would wait for a ready message that never comes, if the value __container__ is used for a container +that does not send notify messages. The use of the default value might have been unintentional by the user, +therefore the overridden default value._ + ### Kubernetes Integration A Kubernetes YAML can be executed in systemd via the `podman-kube@.service` systemd template. The template's argument is the path to the YAML file. Given a `workload.yaml` file in the home directory, it can be executed as follows: diff --git a/docs/source/markdown/podman-import.1.md b/docs/source/markdown/podman-import.1.md index 4002f5255..8d482b961 100644 --- a/docs/source/markdown/podman-import.1.md +++ b/docs/source/markdown/podman-import.1.md @@ -50,10 +50,6 @@ Shows progress on the import Set variant of the imported image. -**--verbose** - -Print additional debugging information - ## EXAMPLES ``` diff --git a/docs/source/markdown/podman-kube-play.1.md b/docs/source/markdown/podman-kube-play.1.md index f52989623..25248ce99 100644 --- a/docs/source/markdown/podman-kube-play.1.md +++ b/docs/source/markdown/podman-kube-play.1.md @@ -322,7 +322,7 @@ $ podman kube play demo.yml --network net1:ip=10.89.1.5 --network net2:ip=10.89. 52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 ``` -Please take into account that CNI networks must be created first using podman-network-create(1). +Please take into account that networks must be created first using podman-network-create(1). ## SEE ALSO **[podman(1)](podman.1.md)**, **[podman-kube(1)](podman-kube.1.md)**, **[podman-network-create(1)](podman-network-create.1.md)**, **[podman-generate-kube(1)](podman-generate-kube.1.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)** diff --git a/docs/source/markdown/podman-network-connect.1.md b/docs/source/markdown/podman-network-connect.1.md index c3eef4038..d1718b812 100644 --- a/docs/source/markdown/podman-network-connect.1.md +++ b/docs/source/markdown/podman-network-connect.1.md @@ -12,10 +12,10 @@ Once connected, the container can communicate with other containers in the same ## OPTIONS #### **--alias**=*name* -Add network-scoped alias for the container. If the network is using the `dnsname` CNI plugin, these aliases -can be used for name resolution on the given network. Multiple *--alias* options may be specified as input. -NOTE: A container will only have access to aliases on the first network that it joins. This is a limitation -that will be removed in a later release. +Add network-scoped alias for the container. If the network has DNS enabled (`podman network inspect -f {{.DNSEnabled}} <NAME>`), +these aliases can be used for name resolution on the given network. Multiple *--alias* options may be specified as input. +NOTE: When using CNI a container will only have access to aliases on the first network that it joins. This limitation does +not exist with netavark/aardvark-dns. #### **--ip**=*address* Set a static ipv4 address for this container on this network. @@ -44,7 +44,7 @@ podman network connect --ip 10.89.1.13 test web ``` ## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-network(1)](podman-network.1.md)**, **[podman-network-disconnect(1)](podman-network-disconnect.1.md)** +**[podman(1)](podman.1.md)**, **[podman-network(1)](podman-network.1.md)**, **[podman-network-inspect(1)](podman-network-inspect.1.md)**, **[podman-network-disconnect(1)](podman-network-disconnect.1.md)** ## HISTORY November 2020, Originally compiled by Brent Baude <bbaude@redhat.com> diff --git a/docs/source/markdown/podman-network-create.1.md b/docs/source/markdown/podman-network-create.1.md index 0ccc540f8..3836ea05c 100644 --- a/docs/source/markdown/podman-network-create.1.md +++ b/docs/source/markdown/podman-network-create.1.md @@ -7,11 +7,9 @@ podman\-network-create - Create a Podman network **podman network create** [*options*] [*name*] ## DESCRIPTION -Create a CNI-network configuration for use with Podman. By default, Podman creates a bridge connection. +Create a network configuration for use with Podman. By default, Podman creates a bridge connection. A *Macvlan* connection can be created with the *-d macvlan* option. A parent device for macvlan can -be designated with the *-o parent=`<device>`* option. In the case of *Macvlan* connections, the -CNI *dhcp* plugin needs to be activated or the container image must have a DHCP client to interact -with the host network's DHCP server. +be designated with the *-o parent=`<device>`* option. If no options are provided, Podman will assign a free subnet and name for your network. @@ -54,7 +52,7 @@ The argument order of the **--subnet**, **--gateway** and **--ip-range** options Set the ipam driver (IP Address Management Driver) for the network. When unset podman will choose an ipam driver automatically based on the network driver. Valid values are: - `host-local`: IP addresses are assigned locally. - - `dhcp`: IP addresses are assigned from a dhcp server on your network. This driver is not yet supported with netavark. + - `dhcp`: IP addresses are assigned from a dhcp server on your network. This driver is not yet supported with netavark. For CNI the *dhcp* plugin needs to be activated before. - `none`: No ip addresses are assigned to the interfaces. You can see the driver in the **podman network inspect** output under the `ipam_options` field. @@ -94,7 +92,7 @@ This is useful to set a static ipv4 and ipv6 subnet. Create a network with no options. ``` $ podman network create -cni-podman2 +podman2 ``` Create a network named *newnet* that uses *192.5.0.0/16* for its subnet. @@ -118,7 +116,7 @@ newnet Create a network that uses a *192.168.55.0/24** subnet and has an IP address range of *192.168.55.129 - 192.168.55.254*. ``` $ podman network create --subnet 192.168.55.0/24 --ip-range 192.168.55.128/25 -cni-podman5 +podman5 ``` Create a network with a static ipv4 and ipv6 subnet and set a gateway. diff --git a/docs/source/markdown/podman-network-inspect.1.md b/docs/source/markdown/podman-network-inspect.1.md index ba9cc94d5..2ba4a63cb 100644 --- a/docs/source/markdown/podman-network-inspect.1.md +++ b/docs/source/markdown/podman-network-inspect.1.md @@ -1,13 +1,13 @@ % podman-network-inspect(1) ## NAME -podman\-network\-inspect - Displays the raw network configuration for one or more networks +podman\-network\-inspect - Displays the network configuration for one or more networks ## SYNOPSIS **podman network inspect** [*options*] *network* [*network* ...] ## DESCRIPTION -Display the raw (JSON format) network configuration. +Display the (JSON format) network configuration. ## OPTIONS #### **--format**, **-f**=*format* @@ -40,7 +40,7 @@ $ podman network inspect podman "name": "podman", "id": "2f259bab93aaaaa2542ba43ef33eb990d0999ee1b9924b557b7be53c0b7a1bb9", "driver": "bridge", - "network_interface": "cni-podman0", + "network_interface": "podman0", "created": "2021-06-03T12:04:33.088567413+02:00", "subnets": [ { diff --git a/docs/source/markdown/podman-network-ls.1.md b/docs/source/markdown/podman-network-ls.1.md index 3c696d404..c7ea24b9b 100644 --- a/docs/source/markdown/podman-network-ls.1.md +++ b/docs/source/markdown/podman-network-ls.1.md @@ -77,8 +77,8 @@ Display networks $ podman network ls NETWORK ID NAME DRIVER 88a7120ee19d podman bridge -6dd508dbf8cd cni-podman6 bridge -8e35c2cd3bf6 cni-podman5 macvlan +6dd508dbf8cd podman6 bridge +8e35c2cd3bf6 podman5 macvlan ``` Display only network names @@ -101,7 +101,7 @@ List networks with their subnets ``` $ podman network ls --format "{{.Name}}: {{range .Subnets}}{{.Subnet}} {{end}}" podman: 10.88.0.0/16 -cni-podman3: 10.89.30.0/24 fde4:f86f:4aab:e68f::/64 +podman3: 10.89.30.0/24 fde4:f86f:4aab:e68f::/64 macvlan: ``` diff --git a/docs/source/markdown/podman-network-rm.1.md b/docs/source/markdown/podman-network-rm.1.md index c6e33c571..880f1d0c7 100644 --- a/docs/source/markdown/podman-network-rm.1.md +++ b/docs/source/markdown/podman-network-rm.1.md @@ -21,11 +21,11 @@ Seconds to wait before forcibly stopping the running containers that are using t ## EXAMPLE -Delete the `cni-podman9` network +Delete the `podman9` network ``` -# podman network rm cni-podman9 -Deleted: cni-podman9 +# podman network rm podman9 +Deleted: podman9 ``` Delete the `fred` network and all containers associated with the network. diff --git a/docs/source/markdown/podman-network.1.md b/docs/source/markdown/podman-network.1.md index bc75cce3b..f58bd5d5c 100644 --- a/docs/source/markdown/podman-network.1.md +++ b/docs/source/markdown/podman-network.1.md @@ -27,7 +27,7 @@ so networks have to be created again after a backend change. | create | [podman-network-create(1)](podman-network-create.1.md) | Create a Podman network | | disconnect | [podman-network-disconnect(1)](podman-network-disconnect.1.md) | Disconnect a container from a network | | exists | [podman-network-exists(1)](podman-network-exists.1.md) | Check if the given network exists | -| inspect | [podman-network-inspect(1)](podman-network-inspect.1.md) | Displays the raw network configuration for one or more networks | +| inspect | [podman-network-inspect(1)](podman-network-inspect.1.md) | Displays the network configuration for one or more networks | | ls | [podman-network-ls(1)](podman-network-ls.1.md) | Display a summary of networks | | prune | [podman-network-prune(1)](podman-network-prune.1.md) | Remove all unused networks | | reload | [podman-network-reload(1)](podman-network-reload.1.md) | Reload network configuration for containers | diff --git a/docs/source/markdown/podman-pause.1.md b/docs/source/markdown/podman-pause.1.md index 863be9ed4..f374d96f3 100644 --- a/docs/source/markdown/podman-pause.1.md +++ b/docs/source/markdown/podman-pause.1.md @@ -17,21 +17,65 @@ Pauses all the processes in one or more containers. You may use container IDs o Pause all running containers. +#### **--cidfile** + +Read container ID from the specified file and pause the container. Can be specified multiple times. + +#### **--filter**, **-f**=*filter* + +Filter what containers pause. +Multiple filters can be given with multiple uses of the --filter flag. +Filters with the same key work inclusive with the only exception being +`label` which is exclusive. Filters with different keys always work exclusive. + +Valid filters are listed below: + +| **Filter** | **Description** | +| --------------- | -------------------------------------------------------------------------------- | +| id | [ID] Container's ID (accepts regex) | +| name | [Name] Container's name (accepts regex) | +| 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 | +| pod | [Pod] name or full or partial ID of pod | +| network | [Network] name or full ID of network | + +#### **--latest**, **-l** + +Instead of providing the container name or ID, use the last created container. If you use methods other than Podman +to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + ## EXAMPLE -Pause a container named 'mywebserver' +Pause container named 'mywebserver' ``` podman pause mywebserver ``` -Pause a container by partial container ID. +Pause container by partial container ID. ``` podman pause 860a4b23 ``` Pause all **running** containers. ``` -podman pause -a +podman pause --all +``` + +Pause container using ID specified in a given files. +``` +podman pause --cidfile /home/user/cidfile-1 +podman pause --cidfile /home/user/cidfile-1 --cidfile ./cidfile-2 +``` + +Pause the latest container created by Podman. +``` +podman pause --latest ``` ## SEE ALSO diff --git a/docs/source/markdown/podman-pod-clone.1.md b/docs/source/markdown/podman-pod-clone.1.md index 49084386c..5473407b0 100644 --- a/docs/source/markdown/podman-pod-clone.1.md +++ b/docs/source/markdown/podman-pod-clone.1.md @@ -11,10 +11,55 @@ podman\-pod\-clone - Creates a copy of an existing pod ## OPTIONS +#### **--blkio-weight**=*weight* + +Block IO weight (relative weight) accepts a weight value between 10 and 1000. + +#### **--blkio-weight-device**=*weight* + +Block IO weight (relative device weight, format: `DEVICE_NAME:WEIGHT`). + #### **--cgroup-parent**=*path* Path to cgroups under which the cgroup for the pod will be created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist. +#### **--cpu-shares**, **-c**=*shares* + +CPU shares (relative weight) + +By default, all containers get the same proportion of CPU cycles. This 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. + +The proportion will only apply when CPU-intensive processes are running. +When tasks in one container are idle, other containers can use the +left-over CPU time. The actual amount of CPU time will vary depending on +the number of containers running on the system. + +For example, consider three containers, one has a cpu-share of 1024 and +two others have a cpu-share setting of 512. When processes in all three +containers attempt to use 100% of CPU, the first container would receive +50% of the total CPU time. If you add a fourth container with a cpu-share +of 1024, the first container only gets 33% of the CPU. The remaining containers +receive 16.5%, 16.5% and 33% of the CPU. + +On a multi-core system, the shares of CPU time are distributed over all CPU +cores. Even if a container is limited to less than 100% of CPU time, it can +use 100% of each individual CPU core. + +For example, consider a system with more than three cores. If you start one +container **{C0}** with **-c=512** running one process, and another container +**{C1}** with **-c=1024** running two processes, this can result in the following +division of CPU shares: + +PID container CPU CPU share +100 {C0} 0 100% of CPU0 +101 {C1} 1 100% of CPU1 +102 {C1} 2 100% of CPU2 + #### **--cpus** Set a number of CPUs for the pod that overrides the original pods CPU limits. If none are specified, the original pod's Nano CPUs are used. @@ -23,6 +68,15 @@ Set a number of CPUs for the pod that overrides the original pods CPU limits. If CPUs in which to allow execution (0-3, 0,1). If none are specified, the original pod's CPUset is used. + +#### **--cpuset-mems**=*nodes* + +Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. + +If there are four memory nodes on the system (0-3), use `--cpuset-mems=0,1` +then processes in the container will only use memory from the first +two memory nodes. + #### **--destroy** Remove the original pod that we are cloning once used to mimic the configuration. @@ -48,6 +102,10 @@ device. The devices that Podman will load modules for when necessary are: Limit read rate (bytes per second) from a device (e.g. --device-read-bps=/dev/sda:1mb). +#### **--device-write-bps**=*path* + +Limit write rate (bytes per second) to a device (e.g. --device-write-bps=/dev/sda:1mb) + #### **--gidmap**=*pod_gid:host_gid:amount* GID map for the user namespace. Using this flag will run all containers in the pod with user namespace enabled. It conflicts with the `--userns` and `--subgidname` flags. @@ -90,6 +148,17 @@ RAM. If a limit of 0 is specified (not using **-m**), the container's memory is not limited. The actual limit may be rounded up to a multiple of the operating system's page size (the value would be very large, that's millions of 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**) value. By default, the swap `LIMIT` will be set to double +the value of --memory. + +The format of `LIMIT` is `<number>[<unit>]`. Unit can be `b` (bytes), +`k` (kibibytes), `m` (mebibytes), or `g` (gibibytes). If you don't specify a +unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap. + #### **--name**, **-n** Set a custom name for the cloned pod. The default if not specified is of the syntax: **<ORIGINAL_NAME>-clone** diff --git a/docs/source/markdown/podman-pod-create.1.md b/docs/source/markdown/podman-pod-create.1.md index de9a34bfa..7b63ac51d 100644 --- a/docs/source/markdown/podman-pod-create.1.md +++ b/docs/source/markdown/podman-pod-create.1.md @@ -23,6 +23,9 @@ podman generates a UUID for each pod, and if a name is not assigned to the container with **--name** then a random string name will be generated for it. The name is useful any place you need to identify a pod. +Note: resource limit related flags work by setting the limits explicitly in the pod's cgroup +which by default, is the cgroup parent for all containers joining the pod. Containers are still delegated the ability to set their own resource limits when joining a pod meaning that if you run **podman pod create --cpus=5** you can also run **podman container create --pod=`<pod_id|pod_name>` --cpus=4** and the container will only see the smaller limit. containers do NOT get the pod level cgroup resources if they specify their own cgroup when joining a pod such as **--cgroupns=host** + ## OPTIONS #### **--add-host**=*host:ip* @@ -33,10 +36,55 @@ Add a line to /etc/hosts. The format is hostname:ip. The **--add-host** option can be set multiple times. The /etc/hosts file is shared between all containers in the pod. +#### **--blkio-weight**=*weight* + +Block IO weight (relative weight) accepts a weight value between 10 and 1000. + +#### **--blkio-weight-device**=*weight* + +Block IO weight (relative device weight, format: `DEVICE_NAME:WEIGHT`). + #### **--cgroup-parent**=*path* Path to cgroups under which the cgroup for the pod will be created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist. +#### **--cpu-shares**, **-c**=*shares* + +CPU shares (relative weight) + +By default, all containers get the same proportion of CPU cycles. This 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. + +The proportion will only apply when CPU-intensive processes are running. +When tasks in one container are idle, other containers can use the +left-over CPU time. The actual amount of CPU time will vary depending on +the number of containers running on the system. + +For example, consider three containers, one has a cpu-share of 1024 and +two others have a cpu-share setting of 512. When processes in all three +containers attempt to use 100% of CPU, the first container would receive +50% of the total CPU time. If you add a fourth container with a cpu-share +of 1024, the first container only gets 33% of the CPU. The remaining containers +receive 16.5%, 16.5% and 33% of the CPU. + +On a multi-core system, the shares of CPU time are distributed over all CPU +cores. Even if a container is limited to less than 100% of CPU time, it can +use 100% of each individual CPU core. + +For example, consider a system with more than three cores. If you start one +container **{C0}** with **-c=512** running one process, and another container +**{C1}** with **-c=1024** running two processes, this can result in the following +division of CPU shares: + +PID container CPU CPU share +100 {C0} 0 100% of CPU0 +101 {C1} 1 100% of CPU1 +102 {C1} 2 100% of CPU2 + #### **--cpus**=*amount* Set the total number of CPUs delegated to the pod. Default is 0.000 which indicates that there is no limit on computation power. @@ -52,7 +100,15 @@ Examples of the List Format: 0-4,9 # bits 0, 1, 2, 3, 4, and 9 set 0-2,7,12-14 # bits 0, 1, 2, 7, 12, 13, and 14 set -#### **--device**=*host-device[:container-device][:permissions]* +#### **--cpuset-mems**=*nodes* + +Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. + +If there are four memory nodes on the system (0-3), use `--cpuset-mems=0,1` +then processes in the container will only use memory from the first +two memory nodes. + +#### **--device**=_host-device_[**:**_container-device_][**:**_permissions_] Add a host device to the pod. Optional *permissions* parameter can be used to specify device permissions. It is a combination of @@ -73,6 +129,10 @@ device. The devices that Podman will load modules for when necessary are: Limit read rate (bytes per second) from a device (e.g. --device-read-bps=/dev/sda:1mb) +#### **--device-write-bps**=*path* + +Limit write rate (bytes per second) to a device (e.g. --device-write-bps=/dev/sda:1mb) + #### **--dns**=*ipaddr* Set custom DNS servers in the /etc/resolv.conf file that will be shared between all containers in the pod. A special option, "none" is allowed which disables creation of /etc/resolv.conf for the pod. @@ -174,6 +234,16 @@ RAM. If a limit of 0 is specified (not using **-m**), the container's memory is not limited. The actual limit may be rounded up to a multiple of the operating system's page size (the value would be very large, that's millions of 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**) value. By default, the swap `LIMIT` will be set to double +the value of --memory. + +The format of `LIMIT` is `<number>[<unit>]`. Unit can be `b` (bytes), +`k` (kibibytes), `m` (mebibytes), or `g` (gibibytes). If you don't specify a +unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap. #### **--name**, **-n**=*name* @@ -214,9 +284,12 @@ Valid _mode_ values are: #### **--network-alias**=*alias* -Add a network-scoped alias for the pod, setting the alias for all networks that the pod joins. To set a name only for a specific network, use the alias option as described under the **--network** option. -Network aliases work only with the bridge networking mode. This option can be specified multiple times. -NOTE: A container will only have access to aliases on the first network that it joins. This is a limitation that will be removed in a later release. +Add a network-scoped alias for the pod, setting the alias for all networks that the container joins. To set a +name only for a specific network, use the alias option as described under the **--network** option. +If the network has DNS enabled (`podman network inspect -f {{.DNSEnabled}} <name>`), +these aliases can be used for name resolution on the given network. This option can be specified multiple times. +NOTE: When using CNI a pod will only have access to aliases on the first network that it joins. This limitation does +not exist with netavark/aardvark-dns. #### **--no-hosts** @@ -300,7 +373,7 @@ Note: Labeling can be disabled for all containers by setting label=false in the #### **--share**=*namespace* -A comma-separated list of kernel namespaces to share. If none or "" is specified, no namespaces will be shared. The namespaces to choose from are cgroup, ipc, net, pid, uts. If the option is prefixed with a "+" then the namespace is appended to the default list, otherwise it replaces the default list. Defaults matches Kubernetes default (ipc, net, uts) +A comma-separated list of kernel namespaces to share. If none or "" is specified, no namespaces will be shared and the infra container will not be created unless expiclity specified via **--infra=true**. The namespaces to choose from are cgroup, ipc, net, pid, uts. If the option is prefixed with a "+" then the namespace is appended to the default list, otherwise it replaces the default list. Defaults matches Kubernetes default (ipc, net, uts) #### **--share-parent** @@ -603,7 +676,7 @@ $ podman pod create --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 ``` ## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-kube-play(1)](podman-kube-play.1.md)**, **containers.conf(1)** +**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-kube-play(1)](podman-kube-play.1.md)**, **containers.conf(1)**, **[cgroups(7)](https://man7.org/linux/man-pages/man7/cgroups.7.html)** ## HISTORY diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index 4566a73d0..8c889f0a5 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -755,9 +755,12 @@ Valid _mode_ values are: #### **--network-alias**=*alias* -Add a network-scoped alias for the container, setting the alias for all networks that the container joins. To set a name only for a specific network, use the alias option as described under the **--network** option. -Network aliases work only with the bridge networking mode. This option can be specified multiple times. -NOTE: A container will only have access to aliases on the first network that it joins. This is a limitation that will be removed in a later release. +Add a network-scoped alias for the container, setting the alias for all networks that the container joins. To set a +name only for a specific network, use the alias option as described under the **--network** option. +If the network has DNS enabled (`podman network inspect -f {{.DNSEnabled}} <name>`), +these aliases can be used for name resolution on the given network. This option can be specified multiple times. +NOTE: When using CNI a container will only have access to aliases on the first network that it joins. This limitation does +not exist with netavark/aardvark-dns. #### **--no-healthcheck** @@ -1921,7 +1924,7 @@ $ podman run -v /var/lib/design:/var/lib/design --group-add keep-groups ubi8 ### Configure execution domain for containers using personality flag ``` -$ podman run --name container1 --personaity=LINUX32 fedora bash +$ podman run --name container1 --personality=LINUX32 fedora bash ``` ### Run a container with external rootfs mounted as an overlay diff --git a/docs/source/markdown/podman-unpause.1.md b/docs/source/markdown/podman-unpause.1.md index 4f66bf393..b94ace89e 100644 --- a/docs/source/markdown/podman-unpause.1.md +++ b/docs/source/markdown/podman-unpause.1.md @@ -17,21 +17,65 @@ Unpauses the processes in one or more containers. You may use container IDs or Unpause all paused containers. +#### **--cidfile** + +Read container ID from the specified file and unpause the container. Can be specified multiple times. + +#### **--filter**, **-f**=*filter* + +Filter what containers unpause. +Multiple filters can be given with multiple uses of the --filter flag. +Filters with the same key work inclusive with the only exception being +`label` which is exclusive. Filters with different keys always work exclusive. + +Valid filters are listed below: + +| **Filter** | **Description** | +| --------------- | -------------------------------------------------------------------------------- | +| id | [ID] Container's ID (accepts regex) | +| name | [Name] Container's name (accepts regex) | +| 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 | +| pod | [Pod] name or full or partial ID of pod | +| network | [Network] name or full ID of network | + +#### **--latest**, **-l** + +Instead of providing the container name or ID, use the last created container. If you use methods other than Podman +to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + ## EXAMPLE -Unpause a container called 'mywebserver' +Unpause container called 'mywebserver' ``` podman unpause mywebserver ``` -Unpause a container by a partial container ID. +Unpause container by a partial container ID. ``` podman unpause 860a4b23 ``` Unpause all **paused** containers. ``` -podman unpause -a +podman unpause --all +``` + +Unpause container using ID specified in a given files. +``` +podman unpause --cidfile /home/user/cidfile-1 +podman unpause --cidfile /home/user/cidfile-1 --cidfile ./cidfile-2 +``` + +Unpause the latest container created by Podman. +``` +podman unpause --latest ``` ## SEE ALSO diff --git a/docs/tutorials/basic_networking.md b/docs/tutorials/basic_networking.md index 0a6034e7a..05c3a731e 100644 --- a/docs/tutorials/basic_networking.md +++ b/docs/tutorials/basic_networking.md @@ -32,7 +32,7 @@ port mapping. Depending on the firewall implementation, we have observed firewa ports being opened automatically due to running a container with a port mapping (for example). If container traffic does not seem to work properly, check the firewall and allow traffic on ports the container is using. A common problem is that -reloading the firewall deletes the cni iptables rules resulting in a loss of +reloading the firewall deletes the cni/netavark iptables rules resulting in a loss of network connectivity for rootful containers. Podman v3 provides the podman network reload command to restore this without having to restart the container. @@ -83,7 +83,7 @@ users. But as of Podman version 4.0, rootless users can also use netavark. The user experience of rootless netavark is very akin to a rootful netavark, except that there is no default network configuration provided. You simply need to create a network, and the one will be created as a bridge network. If you would like to switch from -CNI networking to netvaark, you must issue the `podman system reset --force` command. +CNI networking to netavark, you must issue the `podman system reset --force` command. This will delete all of your images, containers, and custom networks. ``` @@ -177,7 +177,7 @@ address, you should continue to use CNI instead of netavark. ``` $ sudo podman network create -d macvlan -o parent=eth0 webnetwork -/etc/cni/net.d/webnetwork.conflist +webnetwork ``` The next step is to ensure that the DHCP CNI plugin is running. This plugin facilitates the DHCP lease from the network. diff --git a/docs/tutorials/socket_activation.md b/docs/tutorials/socket_activation.md index 9b4b02b81..f4ad5aefd 100644 --- a/docs/tutorials/socket_activation.md +++ b/docs/tutorials/socket_activation.md @@ -19,7 +19,7 @@ The architecture looks like this ``` mermaid stateDiagram-v2 - [*] --> systemd: client connects + [*] --> systemd: first client connects systemd --> podman: socket inherited via fork/exec ``` @@ -55,6 +55,9 @@ $ export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock $ docker-compose up ``` +When __docker-compose__ or any other client connects to the UNIX socket `$XDG_RUNTIME_DIR/podman/podman.sock`, +the service _podman.service_ is started. See its definition in the file _/usr/lib/systemd/user/podman.service_. + ## Socket activation of containers Since version 3.4.0 Podman supports socket activation of containers, i.e., passing @@ -65,7 +68,7 @@ as can be seen in the following diagram: ``` mermaid stateDiagram-v2 - [*] --> systemd: client connects + [*] --> systemd: first client connects systemd --> podman: socket inherited via fork/exec state "OCI runtime" as s2 podman --> conmon: socket inherited via double fork/exec @@ -207,6 +210,18 @@ container then runs with less privileges. When using rootless Podman, network traffic is normally passed through slirp4netns. This comes with a performance penalty. Fortunately, communication over the socket-activated socket does not pass through slirp4netns so it has the same performance characteristics as the normal network on the host. -Note, there is a delay when the first connection is made because the container needs to + +### Starting a socket-activated service + +There is a delay when the first connection is made because the container needs to start up. To minimize this delay, consider passing __--pull=never__ to `podman run` and instead -pull the container image beforehand. +pull the container image beforehand. Instead of waiting for the start of the service to be triggered by the +first client connecting to it, the service can also be explicitly started (`systemctl --user start echo.service`). + +### Stopping a socket-activated service + +Some services run a command (configured by the systemd directive __ExecStart__) that exits after some time of inactivity. +Depending on the restart configuration for the service +(systemd directive [__Restart__](https://www.freedesktop.org/software/systemd/man/systemd.service.html#Restart=)), +it may then be stopped. An example of this is _podman.service_ that stops after some time of inactivity. +The service will be started again when the next client connects to the socket. |