diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/source/markdown/podman-container-clone.1.md | 180 | ||||
| -rw-r--r-- | docs/source/markdown/podman-container.1.md | 1 | ||||
| -rw-r--r-- | docs/source/markdown/podman-image-trust.1.md | 114 | ||||
| -rw-r--r-- | docs/tutorials/basic_networking.md | 53 |
4 files changed, 309 insertions, 39 deletions
diff --git a/docs/source/markdown/podman-container-clone.1.md b/docs/source/markdown/podman-container-clone.1.md new file mode 100644 index 000000000..52fa023f3 --- /dev/null +++ b/docs/source/markdown/podman-container-clone.1.md @@ -0,0 +1,180 @@ +% podman-container-clone(1) + +## NAME +podman\-container\-clone - Creates a copy of an existing container + +## SYNOPSIS +**podman container clone** [*options*] *container* *name* *image* + +## DESCRIPTION +**podman container clone** creates a copy of a container, recreating the original with an identical configuration. This command takes three arguments: the first being the container id or name ot clone, the second argument in this command can change the name of the clone from the default of $ORIGINAL_NAME-clone, and the third is a new image to use in the cloned container. + +## OPTIONS + +#### **--name** + +Set a custom name for the cloned container. The default if not specified is of the syntax: **<ORIGINAL_NAME>-clone** + +#### **--destroy** + +Remove the original container that we are cloning once used to mimic the configuration. + +#### **--cpus** + +Set a number of CPUs for the container that overrides the original containers CPU limits. If none are specified, the original container's Nano CPUs are used. + +This is shorthand +for **--cpu-period** and **--cpu-quota**, so only **--cpus** or either both the **--cpu-period** and **--cpu-quota** options can be set. + +#### **--cpuset-cpus** + +CPUs in which to allow execution (0-3, 0,1). If none are specified, the original container's CPUset is used. + +#### **--cpu-period**=*limit* + +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 + +If none is specified, the original container's cpu period is used + +#### **--cpu-shares**=*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** +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 +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 a fourth container is added 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. +container **{C0}** is started 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 + +If none are specified, the original container's CPU shares are 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. + +If none are specified, the original container's CPU memory nodes are used. + +#### **--cpu-quota**=*limit* + +Limit the CPU Completely Fair Scheduler (CFS) quota. + +Limit the container's CPU usage. By default, containers run with the full +CPU resource. The limit is a number in microseconds. If a number is provided, +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 + +If none is specified, the original container's CPU quota are used. + +#### **--cpu-rt-period**=*microseconds* + +Limit the CPU real-time period in microseconds + +Limit the container's Real Time CPU usage. This option tells the kernel to restrict the container's Real Time CPU usage to the period specified. + +This option is not supported on cgroups V2 systems. + +If none is specified, the original container's CPU runtime period is used. + + +#### **--cpu-rt-runtime**=*microseconds* + +Limit the CPU real-time runtime in microseconds. + +Limit the containers Real Time CPU usage. This option tells the kernel to limit the amount of time in a given CPU period Real Time tasks may consume. Ex: +Period of 1,000,000us and Runtime of 950,000us means that this container could consume 95% of available CPU and leave the remaining 5% to normal priority tasks. + +The sum of all runtimes across containers cannot exceed the amount allotted to the parent cgroup. + +This option is not supported on cgroup V2 systems. + +#### **--memory**, **-m**=*limit* + +Memory limit (format: `<number>[<unit>]`, where unit = b (bytes), k (kilobytes), m (megabytes), or g (gigabytes)) + +Allows the memory available to a container to be constrained. If the host +supports swap memory, then the **-m** memory setting can be larger than physical +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). + +If no memory limits are specified, the original container's will be used. + +#### **--run** + +When set to true, this flag runs the newly created container after the +clone process has completed, this specifies a detached running mode. + +## EXAMPLES +``` +# podman container clone d0cf1f782e2ed67e8c0050ff92df865a039186237a4df24d7acba5b1fa8cc6e7 +6b2c73ff8a1982828c9ae2092954bcd59836a131960f7e05221af9df5939c584 +``` + +``` +# podman container clone --name=clone d0cf1f782e2ed67e8c0050ff92df865a039186237a4df24d7acba5b1fa8cc6e7 +6b2c73ff8a1982828c9ae2092954bcd59836a131960f7e05221af9df5939c584 +``` + +``` +# podman container clone --destroy --cpus=5 d0cf1f782e2ed67e8c0050ff92df865a039186237a4df24d7acba5b1fa8cc6e7 +6b2c73ff8a1982828c9ae2092954bcd59836a131960f7e05221af9df5939c584 +``` + +``` +# podman container clone 2d4d4fca7219b4437e0d74fcdc272c4f031426a6eacd207372691207079551de new_name fedora +Resolved "fedora" as an alias (/etc/containers/registries.conf.d/shortnames.conf) +Trying to pull registry.fedoraproject.org/fedora:latest... +Getting image source signatures +Copying blob c6183d119aa8 done +Copying config e417cd49a8 done +Writing manifest to image destination +Storing signatures +5a9b7851013d326aa4ac4565726765901b3ecc01fcbc0f237bc7fd95588a24f9 +``` +## SEE ALSO +**[podman-create(1)](podman-create.1.md)**, **[cgroups(7)](https://man7.org/linux/man-pages/man7/cgroups.7.html)** + +## HISTORY +January 2022, Originally written by Charlie Doern <cdoern@redhat.com> diff --git a/docs/source/markdown/podman-container.1.md b/docs/source/markdown/podman-container.1.md index 540ebc723..36623c718 100644 --- a/docs/source/markdown/podman-container.1.md +++ b/docs/source/markdown/podman-container.1.md @@ -16,6 +16,7 @@ The container command allows you to manage containers | attach | [podman-attach(1)](podman-attach.1.md) | Attach to a running container. | | checkpoint | [podman-container-checkpoint(1)](podman-container-checkpoint.1.md) | Checkpoints one or more running containers. | | cleanup | [podman-container-cleanup(1)](podman-container-cleanup.1.md) | Cleanup the container's network and mountpoints. | +| clone | [podman-container-clone(1)](podman-container-clone.1.md) | Creates a copy of an existing container. | | commit | [podman-commit(1)](podman-commit.1.md) | Create new image based on the changed container. | | cp | [podman-cp(1)](podman-cp.1.md) | Copy files/folders between a container and the local filesystem. | | create | [podman-create(1)](podman-create.1.md) | Create a new container. | diff --git a/docs/source/markdown/podman-image-trust.1.md b/docs/source/markdown/podman-image-trust.1.md index ba8d7fc2f..66d492922 100644 --- a/docs/source/markdown/podman-image-trust.1.md +++ b/docs/source/markdown/podman-image-trust.1.md @@ -40,6 +40,8 @@ Trust may be updated using the command **podman image trust set** for an existin #### **--help**, **-h** Print usage statement. +### set OPTIONS + #### **--pubkeysfile**=*KEY1*, **-f** A path to an exported public key on the local system. Key paths will be referenced in policy.json. Any path to a file may be used but locating the file in **/etc/pki/containers** is recommended. Options may be used multiple times to @@ -54,14 +56,17 @@ Trust may be updated using the command **podman image trust set** for an existin registry scope **reject**: do not accept images for this registry scope -## show OPTIONS - -#### **--raw** - Output trust policy file as raw JSON +### show OPTIONS #### **--json**, **-j** Output trust as JSON for machine parsing +#### **--noheading**, **-n** + Omit the table headings from the trust listings + +#### **--raw** + Output trust policy file as raw JSON + ## EXAMPLES Accept all unsigned images from a registry @@ -74,15 +79,110 @@ Modify default trust policy Display system trust policy - sudo podman image trust show + podman image trust show +``` +TRANSPORT NAME TYPE ID STORE +all default reject +repository docker.io/library accept +repository registry.access.redhat.com signed security@redhat.com https://access.redhat.com/webassets/docker/content/sigstore +repository registry.redhat.io signed security@redhat.com https://registry.redhat.io/containers/sigstore +repository docker.io reject +docker-daemon accept +``` Display trust policy file - sudo podman image trust show --raw + podman image trust show --raw +``` +{ + "default": [ + { + "type": "reject" + } + ], + "transports": { + "docker": { + "docker.io": [ + { + "type": "reject" + } + ], + "docker.io/library": [ + { + "type": "insecureAcceptAnything" + } + ], + "registry.access.redhat.com": [ + { + "type": "signedBy", + "keyType": "GPGKeys", + "keyPath": "/etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release" + } + ], + "registry.redhat.io": [ + { + "type": "signedBy", + "keyType": "GPGKeys", + "keyPath": "/etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release" + } + ] + }, + "docker-daemon": { + "": [ + { + "type": "insecureAcceptAnything" + } + ] + } + } +} +``` Display trust as JSON - sudo podman image trust show --json + podman image trust show --json +``` +[ + { + "transport": "all", + "name": "* (default)", + "repo_name": "default", + "type": "reject" + }, + { + "transport": "repository", + "name": "docker.io", + "repo_name": "docker.io", + "type": "reject" + }, + { + "transport": "repository", + "name": "docker.io/library", + "repo_name": "docker.io/library", + "type": "accept" + }, + { + "transport": "repository", + "name": "registry.access.redhat.com", + "repo_name": "registry.access.redhat.com", + "sigstore": "https://access.redhat.com/webassets/docker/content/sigstore", + "type": "signed", + "gpg_id": "security@redhat.com" + }, + { + "transport": "repository", + "name": "registry.redhat.io", + "repo_name": "registry.redhat.io", + "sigstore": "https://registry.redhat.io/containers/sigstore", + "type": "signed", + "gpg_id": "security@redhat.com" + }, + { + "transport": "docker-daemon", + "type": "accept" + } +] +``` ## SEE ALSO **[containers-policy.json(5)](https://github.com/containers/image/blob/main/docs/containers-policy.json.5.md)** diff --git a/docs/tutorials/basic_networking.md b/docs/tutorials/basic_networking.md index e1f2f1346..e341df531 100644 --- a/docs/tutorials/basic_networking.md +++ b/docs/tutorials/basic_networking.md @@ -5,7 +5,7 @@ It seems once people master the basics of containers, networking is one of the first -aspects they begin experimenting with. And in regards to networking, it takes very +aspects they begin experimenting with. And regarding networking, it takes very little experimentation before ending up on the deep end of the pool. The following guide shows the most common network setups for Podman rootfull and rootless containers. Each setup is supported with an example. @@ -16,10 +16,10 @@ Each setup is supported with an example. One of the guiding factors on networking for containers with Podman is going to be whether or not the container is run by a root user or not. This is because unprivileged users cannot create networking interfaces on the host. Therefore, with rootfull -containers, the default networking mode is to use the Container Network Interface -(CNI) plugins and specifically the bridge plugin. For rootless, the default network +containers, the default networking mode is to use netavark. +For rootless, the default network mode is slirp4netns. Because of the limited privileges, slirp4netns lacks some of -the features of CNI networking; for example, slirp4netns cannot give containers a +the features of networking; for example, slirp4netns cannot give containers a routable IP address. ## Firewalls @@ -32,7 +32,7 @@ ports being opened automatically due to running a container with a port mapping 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 -network connectivity for rootful containers. Podman v3 provides the podman +network connectivity for rootfull containers. Podman v3 provides the podman network reload command to restore this without having to restart the container. ## Basic Network Setups @@ -51,9 +51,9 @@ traffic. ### Bridge -CNI defines a bridge network as where an internal network is created where both the +A bridge network is defined as an internal network is created where both the container and host are attached. Then this network is capable of allowing the containers -to communicate outside of the host. +to communicate outside the host.  @@ -73,39 +73,32 @@ port be forwarded. Bridge networking is the default for Podman containers created as root. Podman provides a default bridge network, but you can create others using the `podman network create` -command. Containers can be joined to a CNI network when they are created with the +command. Containers can be joined to a network when they are created with the `--network` flag, or after they are created via the `podman network connect` and `podman network disconnect` commands. As mentioned earlier, slirp4netns is the default network configuration for rootless -users. But as of Podman version 3.0, rootless users can also use CNI networking. -The user experience of rootless CNI is very akin to a rootfull CNI, except that +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 rootfull 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. +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. +This will delete all of your images, containers, and custom networks. ``` $ podman network create ``` -When rootless containers are run with a CNI networking configuration, CNI operations +When rootless containers are run, network operations will be executed inside an extra network namespace. To join this namespace, use -`podman unshare --rootless-cni`. Podman version 3.1 and earlier use a special “side-car” -container called rootless-cni-infra. Do not remove this container while your rootless -containers are running. If you remove this container (e.g. by accident), all attached -containers lose network connectivity. In order to restore the network connectivity, all -containers with networks must be restarted. This will automatically recreate the "side-car" -container. When you are using version 3.2 or newer the “side-car” container can be -safely removed. Therefore, it is no longer used. -For rootfull containers, there is no extra namespace or “side-car” container -as rootfull users have the permissions to create and modify network interfaces on -the host. +`podman unshare --rootless-netns`. #### Example -By default, rootfull containers use the CNI bridge plugin for its default configuration. +By default, rootfull containers use the netavark for its default network if +you have not migrated from Podman v3. In this case, no network name must be passed to Podman. However, you can create -additional bridged networks with the podman create command. In that case, you will -have to set the network name. +additional bridged networks with the podman create command. The following example shows how to set up a web server and expose it to the network outside the host as both rootfull and rootless. It will also show how an outside @@ -116,12 +109,6 @@ client can connect to the container. 00f3440c7576aae2d5b193c40513c29c7964e96bf797cf0cc352c2b68ccbe66a ``` -As mentioned earlier, for rootless containers using CNI, a network must first be -created. -``` -$ podman network create -/home/baude/.config/cni/net.d/cni-podman1.conflist -``` Now run the container. ``` $ podman run -dt --name webserver --net cni-podman1 -p 8081:80 quay.io/libpod/banner @@ -168,7 +155,9 @@ to be made for proper access. The following example demonstrates how to set up a web container on a macvlan and how to access that container from outside the host. First, create the macvlan network. You need to know the network interface on the host that connects to the routable -network. In the example case, it is eth0. +network. In the example case, it is eth0. In Podman v4.0 if you need to use a leasable +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 |