From 6859a9e512d621fd5f4e1e16a0fed650a7a998f5 Mon Sep 17 00:00:00 2001 From: Lokesh Mandvekar Date: Thu, 25 Dec 2025 16:18:17 -0500 Subject: [PATCH] Remove slirp4netns from documentation Update all documentation files to remove slirp4netns references and update to pasta as the only rootless networking backend. Signed-off-by: Lokesh Mandvekar --- README.md | 2 +- docs/source/markdown/options/network.image.md | 23 +++----- docs/source/markdown/options/network.md | 30 +++-------- docs/source/markdown/options/publish.md | 2 +- .../markdown/podman-container-inspect.1.md.in | 2 +- docs/source/markdown/podman-create.1.md.in | 8 +-- .../source/markdown/podman-generate-spec.1.md | 4 +- docs/source/markdown/podman-info.1.md | 14 ----- docs/source/markdown/podman-network.1.md | 5 +- .../source/markdown/podman-pod-create.1.md.in | 5 -- docs/source/markdown/podman-run.1.md.in | 8 +-- docs/source/markdown/podman-stats.1.md.in | 2 +- docs/source/markdown/podman.1.md | 4 +- docs/tutorials/basic_networking.md | 52 ++++++++----------- docs/tutorials/performance.md | 3 +- docs/tutorials/podman_tutorial.md | 2 +- docs/tutorials/podman_tutorial_cn.md | 2 +- docs/tutorials/rootless_tutorial.md | 10 +--- docs/tutorials/socket_activation.md | 4 +- rootless.md | 2 +- 20 files changed, 60 insertions(+), 124 deletions(-) diff --git a/README.md b/README.md index e92d5e1fca..ec82e6971d 100644 --- a/README.md +++ b/README.md @@ -92,7 +92,7 @@ Podman uses OCI projects and best of breed libraries for different aspects: - Runtime: We use the [OCI runtime tools](https://github.com/opencontainers/runtime-tools) to generate OCI runtime configurations that can be used with any OCI-compliant runtime, like [crun](https://github.com/containers/crun/) and [runc](https://github.com/opencontainers/runc/). - Images: Image management uses the [containers/image](https://github.com/containers/image) library. - Storage: Container and image storage is managed by [containers/storage](https://github.com/containers/storage). -- Networking: Networking support through use of [Netavark](https://github.com/containers/netavark) and [Aardvark](https://github.com/containers/aardvark-dns). Rootless networking is handled via [pasta](https://passt.top/passt) or [slirp4netns](https://github.com/rootless-containers/slirp4netns). +- Networking: Networking support through use of [Netavark](https://github.com/containers/netavark) and [Aardvark](https://github.com/containers/aardvark-dns). Rootless networking is handled via [pasta](https://passt.top/passt). - Builds: Builds are supported via [Buildah](https://github.com/containers/buildah). - Conmon: [Conmon](https://github.com/containers/conmon) is a tool for monitoring OCI runtimes, used by both Podman and CRI-O. - Seccomp: A unified [Seccomp](https://github.com/containers/container-libs/blob/main/common/pkg/seccomp/seccomp.json) policy for Podman, Buildah, and CRI-O. diff --git a/docs/source/markdown/options/network.image.md b/docs/source/markdown/options/network.image.md index f03a38d9ca..046fc1d26d 100644 --- a/docs/source/markdown/options/network.image.md +++ b/docs/source/markdown/options/network.image.md @@ -15,15 +15,6 @@ considered insecure. - **ns:**_path_: path to a network namespace to join. - **private**: create a new namespace for the container (default) - **\**: 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. -- **slirp4netns[:OPTIONS,...]**: use **slirp4netns**(1) to create a user network stack. It is possible to specify these additional options, they can also be set with `network_cmd_options` in containers.conf: - - **allow_host_loopback=true|false**: Allow slirp4netns to reach the host loopback IP (default is 10.0.2.2 or the second IP from slirp4netns cidr subnet when changed, see the cidr option below). The default is false. - - **mtu=MTU**: Specify the MTU to use for this network. (Default is `65520`). - - **cidr=CIDR**: Specify ip range to use for this network. (Default is `10.0.2.0/24`). - - **enable_ipv6=true|false**: Enable IPv6. Default is true. (Required for `outbound_addr6`). - - **outbound_addr=INTERFACE**: Specify the outbound interface slirp binds to (ipv4 traffic only). - - **outbound_addr=IPv4**: Specify the outbound ipv4 address slirp binds to. - - **outbound_addr6=INTERFACE**: Specify the outbound interface slirp binds to (ipv6 traffic only). - - **outbound_addr6=IPv6**: Specify the outbound ipv6 address slirp binds to. - **pasta[:OPTIONS,...]**: use **pasta**(1) to create a user-mode networking stack. \ This is the default for rootless containers and only supported in rootless mode. \ @@ -48,14 +39,12 @@ considered insecure. gateway address. - **pasta:--mtu,1500**: Specify a 1500 bytes MTU for the _tap_ interface in the container. - - **pasta:--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-forward,10.0.2.3,-m,1500,--no-ndp,--no-dhcpv6,--no-dhcp**, - equivalent to default slirp4netns(1) options: disable IPv6, assign - `10.0.2.0/24` to the `tap0` interface in the container, with gateway - `10.0.2.3`, enable DNS forwarder reachable at `10.0.2.3`, set MTU to 1500 - bytes, disable NDP, DHCPv6 and DHCP support. - - **pasta:-I,tap0,--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-forward,10.0.2.3,--no-ndp,--no-dhcpv6,--no-dhcp**, - equivalent to default slirp4netns(1) options with Podman overrides: same as - above, but leave the MTU to 65520 bytes + - **pasta:--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-forward,10.0.2.3,-m,1500,--no-ndp,--no-dhcpv6,--no-dhcp**: + disable IPv6, assign `10.0.2.0/24` to the `tap0` interface in the container, + with gateway `10.0.2.3`, enable DNS forwarder reachable at `10.0.2.3`, + set MTU to 1500 bytes, disable NDP, DHCPv6 and DHCP support. + - **pasta:-I,tap0,--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-forward,10.0.2.3,--no-ndp,--no-dhcpv6,--no-dhcp**: + same as above, but leave the MTU to 65520 bytes - **pasta:-t,auto,-u,auto,-T,auto,-U,auto**: enable automatic port forwarding based on observed bound ports from both host and container sides - **pasta:-T,5201**: enable forwarding of TCP port 5201 from container to diff --git a/docs/source/markdown/options/network.md b/docs/source/markdown/options/network.md index 2bcc0bc128..b93d483df1 100644 --- a/docs/source/markdown/options/network.md +++ b/docs/source/markdown/options/network.md @@ -31,21 +31,7 @@ Valid _mode_ values are: - **ns:**_path_: Path to a network namespace to join. -- **private**: Create a new namespace for the container. This uses the **bridge** mode for rootful containers and **slirp4netns** for rootless ones. - -- **slirp4netns[:OPTIONS,...]**: use **slirp4netns**(1) to create a user network stack. It is possible to specify these additional options, they can also be set with `network_cmd_options` in containers.conf: - - - **allow_host_loopback=true|false**: Allow slirp4netns to reach the host loopback IP (default is 10.0.2.2 or the second IP from slirp4netns cidr subnet when changed, see the cidr option below). The default is false. - - **mtu=**_MTU_: Specify the MTU to use for this network. (Default is `65520`). - - **cidr=**_CIDR_: Specify ip range to use for this network. (Default is `10.0.2.0/24`). - - **enable_ipv6=true|false**: Enable IPv6. Default is true. (Required for `outbound_addr6`). - - **outbound_addr=**_INTERFACE_: Specify the outbound interface slirp binds to (ipv4 traffic only). - - **outbound_addr=**_IPv4_: Specify the outbound ipv4 address slirp binds to. - - **outbound_addr6=**_INTERFACE_: Specify the outbound interface slirp binds to (ipv6 traffic only). - - **outbound_addr6=**_IPv6_: Specify the outbound ipv6 address slirp binds to. - - **port_handler=rootlesskit**: Use rootlesskit for port forwarding. Default. \ - 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 the 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. +- **private**: Create a new namespace for the container. This uses the **bridge** mode for rootful containers and **pasta** for rootless ones. - **pasta[:OPTIONS,...]**: use **pasta**(1) to create a user-mode networking stack. \ @@ -79,14 +65,12 @@ Valid _mode_ values are: gateway address. - **pasta:--mtu,1500**: Specify a 1500 bytes MTU for the _tap_ interface in the container. - - **pasta:--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-forward,10.0.2.3,-m,1500,--no-ndp,--no-dhcpv6,--no-dhcp**, - equivalent to default slirp4netns(1) options: disable IPv6, assign - `10.0.2.0/24` to the `tap0` interface in the container, with gateway - `10.0.2.3`, enable DNS forwarder reachable at `10.0.2.3`, set MTU to 1500 - bytes, disable NDP, DHCPv6 and DHCP support. - - **pasta:-I,tap0,--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-forward,10.0.2.3,--no-ndp,--no-dhcpv6,--no-dhcp**, - equivalent to default slirp4netns(1) options with Podman overrides: same as - above, but leave the MTU to 65520 bytes + - **pasta:--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-forward,10.0.2.3,-m,1500,--no-ndp,--no-dhcpv6,--no-dhcp**: + disable IPv6, assign `10.0.2.0/24` to the `tap0` interface in the container, + with gateway `10.0.2.3`, enable DNS forwarder reachable at `10.0.2.3`, + set MTU to 1500 bytes, disable NDP, DHCPv6 and DHCP support. + - **pasta:-I,tap0,--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-forward,10.0.2.3,--no-ndp,--no-dhcpv6,--no-dhcp**: + same as above, but leave the MTU to 65520 bytes - **pasta:-t,auto,-u,auto,-T,auto,-U,auto**: enable automatic port forwarding based on observed bound ports from both host and container sides - **pasta:-T,5201**: enable forwarding of TCP port 5201 from container to diff --git a/docs/source/markdown/options/publish.md b/docs/source/markdown/options/publish.md index 05ec22f197..c861a5a994 100644 --- a/docs/source/markdown/options/publish.md +++ b/docs/source/markdown/options/publish.md @@ -23,4 +23,4 @@ If it is not, the container port is randomly assigned a port on the host. Use **podman port** to see the actual mapping: `podman port $CONTAINER $CONTAINERPORT`. Port publishing is only supported for containers utilizing their own network namespace -through `bridge` networks, or the `pasta` and `slirp4netns` network modes. +through `bridge` networks, or the `pasta` network mode. diff --git a/docs/source/markdown/podman-container-inspect.1.md.in b/docs/source/markdown/podman-container-inspect.1.md.in index c150705782..b6cd589a44 100644 --- a/docs/source/markdown/podman-container-inspect.1.md.in +++ b/docs/source/markdown/podman-container-inspect.1.md.in @@ -239,7 +239,7 @@ $ podman container inspect foobar "Tag": "", "Size": "0B" }, - "NetworkMode": "slirp4netns", + "NetworkMode": "pasta", "PortBindings": {}, "RestartPolicy": { "Name": "", diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 67e9d5ef01..b8a439ee72 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -499,13 +499,13 @@ be installed. The shadow-utils package must include the newuidmap and newgidmap In order for users to run rootless, there must be an entry for their username in /etc/subuid and /etc/subgid which lists the UIDs for their user namespace. -Rootless Podman works better if the fuse-overlayfs and slirp4netns packages are installed. +Rootless Podman works better if the fuse-overlayfs package is installed. The fuse-overlayfs package provides a userspace overlay storage driver, otherwise users need to use the vfs storage driver, which can be disk space expensive and less performant than other drivers. -To enable VPN on the container, slirp4netns or pasta needs to be specified; -without either, containers need to be run with the --network=host flag. +To enable VPN on the container, pasta networking is used by default; +otherwise, containers need to be run with the --network=host flag. ## ENVIRONMENT @@ -554,7 +554,7 @@ page. NOTE: Use the environment variable `TMPDIR` to change the temporary storage location of downloaded container images. Podman defaults to use `/var/tmp`. ## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-save(1)](podman-save.1.md)**, **[podman-ps(1)](podman-ps.1.md)**, **[podman-attach(1)](podman-attach.1.md)**, **[podman-pod-create(1)](podman-pod-create.1.md)**, **[podman-port(1)](podman-port.1.md)**, **[podman-start(1)](podman-start.1.md)**, **[podman-kill(1)](podman-kill.1.md)**, **[podman-stop(1)](podman-stop.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-rm(1)](podman-rm.1.md)**, **[subgid(5)](https://www.unix.com/man-page/linux/5/subgid)**, **[subuid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[containers.conf(5)](https://github.com/containers/container-libs/blob/main/common/docs/containers.conf.5.md)**, **[podman-systemd.unit(5)](podman-systemd.unit.5.md)**, **[setsebool(8)](https://man7.org/linux/man-pages/man8/setsebool.8.html)**, **[slirp4netns(1)](https://github.com/rootless-containers/slirp4netns/blob/master/slirp4netns.1.md)**, **[pasta(1)](https://passt.top/builds/latest/web/passt.1.html)**, **[fuse-overlayfs(1)](https://github.com/containers/fuse-overlayfs/blob/main/fuse-overlayfs.1.md)**, **proc(5)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**, **personality(2)** +**[podman(1)](podman.1.md)**, **[podman-save(1)](podman-save.1.md)**, **[podman-ps(1)](podman-ps.1.md)**, **[podman-attach(1)](podman-attach.1.md)**, **[podman-pod-create(1)](podman-pod-create.1.md)**, **[podman-port(1)](podman-port.1.md)**, **[podman-start(1)](podman-start.1.md)**, **[podman-kill(1)](podman-kill.1.md)**, **[podman-stop(1)](podman-stop.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-rm(1)](podman-rm.1.md)**, **[subgid(5)](https://www.unix.com/man-page/linux/5/subgid)**, **[subuid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[containers.conf(5)](https://github.com/containers/container-libs/blob/main/common/docs/containers.conf.5.md)**, **[podman-systemd.unit(5)](podman-systemd.unit.5.md)**, **[setsebool(8)](https://man7.org/linux/man-pages/man8/setsebool.8.html)**, **[pasta(1)](https://passt.top/builds/latest/web/passt.1.html)**, **[fuse-overlayfs(1)](https://github.com/containers/fuse-overlayfs/blob/main/fuse-overlayfs.1.md)**, **proc(5)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**, **personality(2)** ### Troubleshooting diff --git a/docs/source/markdown/podman-generate-spec.1.md b/docs/source/markdown/podman-generate-spec.1.md index 27c4d2187a..7d602fb917 100644 --- a/docs/source/markdown/podman-generate-spec.1.md +++ b/docs/source/markdown/podman-generate-spec.1.md @@ -86,7 +86,7 @@ $ podman generate spec container1 "nsmode": "default" }, "netns": { - "nsmode": "slirp4netns" + "nsmode": "pasta" }, "Networks": null, "use_image_hosts": false, @@ -161,7 +161,7 @@ $ cat output.json "nsmode": "default" }, "netns": { - "nsmode": "slirp4netns" + "nsmode": "pasta" }, "Networks": null, "use_image_hosts": false, diff --git a/docs/source/markdown/podman-info.1.md b/docs/source/markdown/podman-info.1.md index 9892a6e8e2..f9a784b2c6 100644 --- a/docs/source/markdown/podman-info.1.md +++ b/docs/source/markdown/podman-info.1.md @@ -115,15 +115,6 @@ host: seccompProfilePath: /usr/share/containers/seccomp.json selinuxEnabled: true serviceIsRemote: false - slirp4netns: - executable: /bin/slirp4netns - package: slirp4netns-1.1.12-2.fc34.x86_64 - version: |- - slirp4netns version 1.1.12 - commit: 7a104a101aa3278a2152351a082a6df71f57c9a3 - libslirp: 4.4.0 - SLIRP_CONFIG_VERSION_MAX: 3 - libseccomp: 2.5.0 swapFree: 15687475200 swapTotal: 16886259712 uptime: 47h 15m 9.91s (Approximately 1.96 days) @@ -258,11 +249,6 @@ $ podman info --format json "seccompProfilePath": "/usr/share/containers/seccomp.json", "selinuxEnabled": true }, - "slirp4netns": { - "executable": "/bin/slirp4netns", - "package": "slirp4netns-1.1.12-2.fc34.x86_64", - "version": "slirp4netns version 1.1.12\ncommit: 7a104a101aa3278a2152351a082a6df71f57c9a3\nlibslirp: 4.4.0\nSLIRP_CONFIG_VERSION_MAX: 3\nlibseccomp: 2.5.0" - }, "pasta": { "executable": "/usr/bin/passt", "package": "passt-0^20221116.gace074c-1.fc34.x86_64", diff --git a/docs/source/markdown/podman-network.1.md b/docs/source/markdown/podman-network.1.md index 974e764631..26296c0c16 100644 --- a/docs/source/markdown/podman-network.1.md +++ b/docs/source/markdown/podman-network.1.md @@ -35,10 +35,7 @@ The default bridge network (called `podman`) uses 10.88.0.0/16 as a subnet. When ### Pasta Pasta by default performs no Network Address Translation (NAT) and copies the IPs from your main interface into the container namespace. If pasta cannot find an interface with the default route, it will select an interface if there is only one interface with a valid route. If you do not have a default route and several interfaces have defined routes, pasta will be unable to figure out the correct interface and it will fail to start. To specify the interface, use `-i` option to pasta. A default set of pasta options can be set in **[containers.conf(5)](https://github.com/containers/container-libs/blob/main/common/docs/containers.conf.5.md)** under the `[network]` section with the `pasta_options` key. -The default rootless networking tool can be selected in **[containers.conf(5)](https://github.com/containers/container-libs/blob/main/common/docs/containers.conf.5.md)** under the `[network]` section with `default_rootless_network_cmd`, which can be set to `pasta` (default) or `slirp4netns`. - -### Slirp4netns -Slirp4netns uses 10.0.2.0/24 for its default network. This can also be changed in **[containers.conf(5)](https://github.com/containers/container-libs/blob/main/common/docs/containers.conf.5.md)** but under the `[engine]` section. Use the `network_cmd_options` key and add `["cidr=X.X.X.X/24"]` as a value. Note that slirp4netns needs a network prefix size between 1 and 25. This option accepts an array, so more options can be added in a comma-separated string as described on the **[podman-network-create(1)](podman-network-create.1.md)** man page. To change the CIDR for just one container, specify it on the cli using the `--network` option like this: `--network slirp4netns:cidr=192.168.1.0/24`. +Pasta is the default rootless networking tool. This can be configured in **[containers.conf(5)](https://github.com/containers/container-libs/blob/main/common/docs/containers.conf.5.md)** under the `[network]` section with `default_rootless_network_cmd`. ### Podman network create When a new network is created with a `podman network create` command, and no subnet is given with the --subnet option, Podman starts picking a free subnet from 10.89.0.0/24 to 10.255.255.0/24. Use the `default_subnet_pools` option under the `[network]` section in **[containers.conf(5)](https://github.com/containers/container-libs/blob/main/common/docs/containers.conf.5.md)** to change the range and/or size that is assigned by default. diff --git a/docs/source/markdown/podman-pod-create.1.md.in b/docs/source/markdown/podman-pod-create.1.md.in index 54e0a7d9aa..0812149133 100644 --- a/docs/source/markdown/podman-pod-create.1.md.in +++ b/docs/source/markdown/podman-pod-create.1.md.in @@ -212,11 +212,6 @@ Create a pod with published ports on the host. $ podman pod create --publish 8443:443 ``` -Create a pod with the specified network configuration. -``` -$ podman pod create --network slirp4netns:outbound_addr=127.0.0.1,allow_host_loopback=true -``` - Create a pod with the specified network. ``` $ podman pod create --network pasta diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index 2e83bb056e..16c63c341e 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -948,13 +948,13 @@ be installed. The **shadow-utils** package must include the **newuidmap**(1) and In order for users to run rootless, there must be an entry for their username in _/etc/subuid_ and _/etc/subgid_ which lists the UIDs for their user namespace. -Rootless Podman works better if the fuse-overlayfs and slirp4netns packages are installed. +Rootless Podman works better if the fuse-overlayfs package is installed. The **fuse-overlayfs** package provides a userspace overlay storage driver, otherwise users need to use the **vfs** storage driver, which can be disk space expensive and less performant than other drivers. -To enable VPN on the container, slirp4netns or pasta needs to be specified; -without either, containers need to be run with the --network=host flag. +To enable VPN on the container, pasta networking is used by default; +otherwise, containers need to be run with the --network=host flag. ## ENVIRONMENT @@ -1001,7 +1001,7 @@ page. NOTE: Use the environment variable `TMPDIR` to change the temporary storage location of downloaded container images. Podman defaults to use `/var/tmp`. ## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-save(1)](podman-save.1.md)**, **[podman-ps(1)](podman-ps.1.md)**, **[podman-attach(1)](podman-attach.1.md)**, **[podman-pod-create(1)](podman-pod-create.1.md)**, **[podman-port(1)](podman-port.1.md)**, **[podman-start(1)](podman-start.1.md)**, **[podman-kill(1)](podman-kill.1.md)**, **[podman-stop(1)](podman-stop.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-rm(1)](podman-rm.1.md)**, **[subgid(5)](https://www.unix.com/man-page/linux/5/subgid)**, **[subuid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[containers.conf(5)](https://github.com/containers/container-libs/blob/main/common/docs/containers.conf.5.md)**, **[podman-systemd.unit(5)](podman-systemd.unit.5.md)**, **[setsebool(8)](https://man7.org/linux/man-pages/man8/setsebool.8.html)**, **[slirp4netns(1)](https://github.com/rootless-containers/slirp4netns/blob/master/slirp4netns.1.md)**, **[pasta(1)](https://passt.top/builds/latest/web/passt.1.html)**, **[fuse-overlayfs(1)](https://github.com/containers/fuse-overlayfs/blob/main/fuse-overlayfs.1.md)**, **proc(5)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**, **personality(2)** +**[podman(1)](podman.1.md)**, **[podman-save(1)](podman-save.1.md)**, **[podman-ps(1)](podman-ps.1.md)**, **[podman-attach(1)](podman-attach.1.md)**, **[podman-pod-create(1)](podman-pod-create.1.md)**, **[podman-port(1)](podman-port.1.md)**, **[podman-start(1)](podman-start.1.md)**, **[podman-kill(1)](podman-kill.1.md)**, **[podman-stop(1)](podman-stop.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-rm(1)](podman-rm.1.md)**, **[subgid(5)](https://www.unix.com/man-page/linux/5/subgid)**, **[subuid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[containers.conf(5)](https://github.com/containers/container-libs/blob/main/common/docs/containers.conf.5.md)**, **[podman-systemd.unit(5)](podman-systemd.unit.5.md)**, **[setsebool(8)](https://man7.org/linux/man-pages/man8/setsebool.8.html)**, **[pasta(1)](https://passt.top/builds/latest/web/passt.1.html)**, **[fuse-overlayfs(1)](https://github.com/containers/fuse-overlayfs/blob/main/fuse-overlayfs.1.md)**, **proc(5)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**, **personality(2)** ### Troubleshooting diff --git a/docs/source/markdown/podman-stats.1.md.in b/docs/source/markdown/podman-stats.1.md.in index 13dc48f3f4..6c410d1784 100644 --- a/docs/source/markdown/podman-stats.1.md.in +++ b/docs/source/markdown/podman-stats.1.md.in @@ -118,7 +118,7 @@ ID NAME MEM USAGE / LIMIT 6eae9e25a564 clever_bassi 3.031MB / 16.7GB ``` -Note: When using a slirp4netns network with the rootlesskit port +Note: When using rootless networking with the rootlesskit port handler, the traffic sent via the port forwarding is accounted to the `lo` device. Traffic accounted to `lo` is not accounted in the stats output. diff --git a/docs/source/markdown/podman.1.md b/docs/source/markdown/podman.1.md index b65e773ac5..4c98e9855e 100644 --- a/docs/source/markdown/podman.1.md +++ b/docs/source/markdown/podman.1.md @@ -483,7 +483,7 @@ Note: whitespace in any row of `/etc/subuid` or `/etc/subgid`, including trailin Images are pulled under `XDG_DATA_HOME` when specified, otherwise in the home directory of the user under `.local/share/containers/storage`. -Currently slirp4netns or pasta is required to be installed to create a network +Currently pasta is required to be installed to create a network device, otherwise rootless containers need to run in the network namespace of the host. @@ -496,7 +496,7 @@ The Overlay file system (OverlayFS) is not supported with kernels prior to 5.12. The Network File System (NFS) and other distributed file systems (for example: Lustre, Spectrum Scale, the General Parallel File System (GPFS)) are not supported when running in rootless mode as these file systems do not understand user namespace. However, rootless Podman can make use of an NFS Homedir by modifying the `$HOME/.config/containers/storage.conf` to have the `graphroot` option point to a directory stored on local (Non NFS) storage. ## SEE ALSO -**[containers-mounts.conf(5)](https://github.com/containers/container-libs/blob/main/common/docs/containers-mounts.conf.5.md)**, **[containers.conf(5)](https://github.com/containers/container-libs/blob/main/common/docs/containers.conf.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)**, **[containers-storage.conf(5)](https://github.com/containers/storage/blob/main/docs/containers-storage.conf.5.md)**, **[buildah(1)](https://github.com/containers/buildah/blob/main/docs/buildah.1.md)**, **[oci-hooks(5)](https://github.com/containers/container-libs/blob/main/common/pkg/hooks/docs/oci-hooks.5.md)**, **[containers-policy.json(5)](https://github.com/containers/image/blob/main/docs/containers-policy.json.5.md)**, **[crun(1)](https://github.com/containers/crun/blob/main/crun.1.md)**, **[runc(8)](https://github.com/opencontainers/runc/blob/main/man/runc.8.md)**, **[subuid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[subgid(5)](https://www.unix.com/man-page/linux/5/subgid)**, **[slirp4netns(1)](https://github.com/rootless-containers/slirp4netns/blob/master/slirp4netns.1.md)**, **[pasta(1)](https://passt.top/builds/latest/web/passt.1.html)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**, **[podman-quadlet(1)](podman-quadlet.1.md)**, **[podman-systemd.unit(5)](podman-systemd.unit.5.md)** +**[containers-mounts.conf(5)](https://github.com/containers/container-libs/blob/main/common/docs/containers-mounts.conf.5.md)**, **[containers.conf(5)](https://github.com/containers/container-libs/blob/main/common/docs/containers.conf.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)**, **[containers-storage.conf(5)](https://github.com/containers/storage/blob/main/docs/containers-storage.conf.5.md)**, **[buildah(1)](https://github.com/containers/buildah/blob/main/docs/buildah.1.md)**, **[oci-hooks(5)](https://github.com/containers/container-libs/blob/main/common/pkg/hooks/docs/oci-hooks.5.md)**, **[containers-policy.json(5)](https://github.com/containers/image/blob/main/docs/containers-policy.json.5.md)**, **[crun(1)](https://github.com/containers/crun/blob/main/crun.1.md)**, **[runc(8)](https://github.com/opencontainers/runc/blob/main/man/runc.8.md)**, **[subuid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[subgid(5)](https://www.unix.com/man-page/linux/5/subgid)**, **[pasta(1)](https://passt.top/builds/latest/web/passt.1.html)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**, **[podman-quadlet(1)](podman-quadlet.1.md)**, **[podman-systemd.unit(5)](podman-systemd.unit.5.md)** ### Troubleshooting diff --git a/docs/tutorials/basic_networking.md b/docs/tutorials/basic_networking.md index a434357e77..151e2db184 100644 --- a/docs/tutorials/basic_networking.md +++ b/docs/tutorials/basic_networking.md @@ -16,14 +16,9 @@ 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, -for rootless containers, the default network mode is `pasta` (default since -Podman 5.0; `slirp4netns` was the previous default). Because of the limited -privileges, these rootless network modes lack some of the features of -networking compared to rootful Podman's networking; for example, they do not -give containers their own independently routable IP on the host's network. -For more details on rootless networking and its limitations, see [Shortcomings of Rootless Podman](https://github.com/containers/podman/blob/main/rootless.md). -The default networking mode for rootful containers on the other side is netavark, -which allows a container to have a routable IP address. +for rootless containers, the default network mode is pasta. The default +networking mode for rootful containers is netavark, which allows a container +to have a routable IP address. ## Firewalls @@ -47,11 +42,9 @@ the container on an internal bridge network, which is then connected to the inte via Network Address Translation(NAT). We also see users wanting to use `macvlan` for networking as well. The `macvlan` plugin forwards an entire network interface from the host into the container, allowing it access to the network the host is connected -to. And finally, rootless containers typically use user-mode networking via -`pasta` (current default) or `slirp4netns`. These network modes have limited -capabilities but can be run by users without root privileges. `slirp4netns`, -for example, creates a tunnel from the host into the container to forward -traffic. +to. And finally, the default network configuration for rootless containers is pasta. +The pasta network mode can be run on users without root privileges and provides +user-mode networking for containers. ### Bridge @@ -81,11 +74,10 @@ 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, rootless users use user-mode networking (`pasta` by -default since Podman 5.0, with `slirp4netns` still available as an option). -But as of Podman version 4.0, rootless users can also use netavark. +As mentioned earlier, pasta is the default network configuration for rootless +users. Rootless users can also use netavark for bridge networking. 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 +there is no default network configuration provided. You simply need to create a network, and the one will be created as a bridge network. ``` @@ -224,25 +216,25 @@ managed by firewalld, no change to the firewall is needed. -### Slirp4netns +### Pasta -Slirp4netns was the original default network setup for rootless containers and -pods and is still available as a configurable option. It was invented because -unprivileged users are not allowed to make network interfaces on the host. -Slirp4netns creates a TAP device in the container’s network namespace and -connects to the usermode TCP/IP stack. Consider the following illustration. +Pasta is the default network setup for rootless containers and pods. It was +designed to provide user-mode networking for unprivileged users who are not +allowed to make network interfaces on the host. Pasta creates a TAP device in +the container’s network namespace and provides a user-mode TCP/IP stack. +Consider the following illustration. -![slirp_network](podman_rootless_default.png) +![pasta_network](podman_rootless_default.png) The unprivileged user on this laptop has created two containers: a DB container and -a web container. Both of these containers have the ability to access content on -networks outside the laptop. And outside clients can access the containers if the -container is bound to a host port and the laptop firewall allows it. Remember, unprivileged +a web container. Both of these containers have the ability to access content on +networks outside the laptop. And outside clients can access the containers if the +container is bound to a host port and the laptop firewall allows it. Remember, unprivileged users must use ports 1024 through 65535 as lower ports require root privileges. (CAP_NET_BIND_SERVICE) Note: this can be adjusted using the `sysctl net.ipv4.ip_unprivileged_port_start` -One of the drawbacks of slirp4netns is that the containers are completely isolated -from each other. Unlike the bridge approach, there is no virtual network. For containers +One of the drawbacks of pasta networking is that containers are isolated from each +other by default. Unlike the bridge approach, there is no virtual network. For containers to communicate with each other, they can use the port mappings with the host system, or they can be put into a Pod where they share the same network namespace. See [Communicating between containers and pods](#Communicating-between-containers-and-pods) for more information. @@ -305,7 +297,7 @@ By definition, all containers in a Podman pod share the same network namespace. fact means that they will have the same IP address, MAC addresses, and port mappings. You can conveniently communicate between containers in a pod by using localhost. -![slirp_network](podman_pod.png) +![pod_network](podman_pod.png) The above illustration describes a Pod on a bridged network. As depicted, the Pod has two containers “inside” it: a DB and a Web container. Because they share the diff --git a/docs/tutorials/performance.md b/docs/tutorials/performance.md index 92e07d12ac..f2c1730310 100644 --- a/docs/tutorials/performance.md +++ b/docs/tutorials/performance.md @@ -171,8 +171,7 @@ You can avoid using _pasta_ in the following ways: * Use `--network=host`. No network namespace is created. The container will use the host’s network. Note: By using `--network=host`, the container is given full access to local system services such as D-bus and is therefore considered insecure. -Side note: Pasta is faster than the network driver [slirp4netns](https://github.com/containers/podman/blob/main/docs/tutorials/basic_networking.md#slirp4netns). -Pasta is the default network driver since Podman 5.0.0. +Pasta is the default and only rootless network driver since Podman 6.0.0. Since Podman 5.1.0 the default network driver can be shown with diff --git a/docs/tutorials/podman_tutorial.md b/docs/tutorials/podman_tutorial.md index 8722d1cb59..4db0162073 100644 --- a/docs/tutorials/podman_tutorial.md +++ b/docs/tutorials/podman_tutorial.md @@ -25,7 +25,7 @@ podman run --name basic_httpd -d -p 8080:80/tcp docker.io/nginx ``` Because the container is being run in detached mode, represented by the *-d* in the `podman run` command, Podman will print the container ID after it has run. Note that we use port forwarding to be able to -access the HTTP server. For successful running at least slirp4netns v0.3.0 is needed. +access the HTTP server. ### Listing running containers The Podman *ps* command is used to list creating and running containers. diff --git a/docs/tutorials/podman_tutorial_cn.md b/docs/tutorials/podman_tutorial_cn.md index 17ded077c3..6b090e3b9e 100644 --- a/docs/tutorials/podman_tutorial_cn.md +++ b/docs/tutorials/podman_tutorial_cn.md @@ -28,7 +28,7 @@ podman run --name basic_httpd -d -p 8080:80/tcp docker.io/nginx 因为命令中的 *-d* 参数表明容器以 "detached" 模式运行，所以 Podman 会在容器运行后打印容器的 ID。 -注意为了访问这个 HTTP 服务器，我们将使用端口转发。成功运行需要 slirp4netns 的 v0.3.0+ 版本。 +注意为了访问这个 HTTP 服务器，我们将使用端口转发。 Podman 的 *ps* 命令用于列出正在创建和运行的容器。 diff --git a/docs/tutorials/rootless_tutorial.md b/docs/tutorials/rootless_tutorial.md index 35b76990da..93fa9b69e9 100644 --- a/docs/tutorials/rootless_tutorial.md +++ b/docs/tutorials/rootless_tutorial.md @@ -18,21 +18,15 @@ For building Podman, see the [build instructions](https://podman.io/getting-star A user-mode networking tool for unprivileged network namespaces must be installed on the machine in order for Podman to run in a rootless environment. -Podman supports two rootless networking tools: [pasta](https://passt.top/passt/about/#pasta) (provided by [passt](https://passt.top/passt/about/)) and [slirp4netns](https://github.com/rootless-containers/slirp4netns). - -pasta is the default since Podman 5.0, while slirp4netns was the default for previous versions. Passt is a more modern replacement for SLIRP that amongst other things fully supports IPv6 and is more secure architecturally (runs in a separate process, uses modern Linux mechanisms for isolation etc). +Podman uses [pasta](https://passt.top/passt/about/#pasta) (provided by [passt](https://passt.top/passt/about/)) for rootless networking. Pasta fully supports IPv6 and is architecturally secure (runs in a separate process, uses modern Linux mechanisms for isolation etc). Passt is [available on most Linux distributions](https://passt.top/passt/about/#availability) via their package distribution software such as `yum`, `dnf`, `apt`, `zypper`, etc. under the name `passt`. If the package is not available, you can build and install `passt` from [its upstream](https://passt.top/passt/about/#try-it). -Alternatively, slirp4netns can be installed in the same fashion either from your distribution's repositories or by following [the instructions](https://github.com/rootless-containers/slirp4netns?tab=readme-ov-file#install) provided on its GitHub. - -The major user-facing difference between the two is outlined in [this blog post](https://blog.podman.io/2024/03/podman-5-0-breaking-changes-in-detail/) and expanded upon in **[podman-network(1)](https://github.com/containers/podman/blob/main/docs/source/markdown/podman-network.1.md#pasta)**. +More details about pasta can be found in [this blog post](https://blog.podman.io/2024/03/podman-5-0-breaking-changes-in-detail/) and in **[podman-network(1)](https://github.com/containers/podman/blob/main/docs/source/markdown/podman-network.1.md#pasta)**. > [!note] > pasta's default situation of not being able to communicate between the container and the host has been fixed in Podman 5.3: see [Podman 5.3 changes for improved networking experience with pasta](https://blog.podman.io/2024/10/podman-5-3-changes-for-improved-networking-experience-with-pasta/). -The default rootless networking tool can be selected in **[containers.conf(5)](https://github.com/containers/container-libs/blob/main/common/docs/containers.conf.5.md)** under the `[network]` section with `default_rootless_network_cmd`, which can be set to `pasta` (default) or `slirp4netns`. - ### `/etc/subuid` and `/etc/subgid` configuration Rootless Podman requires the user running it to have a range of UIDs listed in the files `/etc/subuid` and `/etc/subgid`. The `shadow-utils` or `newuid` package provides these files on different distributions and they must be installed on the system. Root privileges are required to add or update entries within these files. The following is a summary from the [How does rootless Podman work?](https://opensource.com/article/19/2/how-does-rootless-podman-work) article by Dan Walsh on [opensource.com](https://opensource.com) diff --git a/docs/tutorials/socket_activation.md b/docs/tutorials/socket_activation.md index 7d08a46c04..d97b9d5e72 100644 --- a/docs/tutorials/socket_activation.md +++ b/docs/tutorials/socket_activation.md @@ -264,9 +264,9 @@ container then runs with less privileges. ### Native network performance over the socket-activated socket -When using rootless Podman, network traffic is normally passed through slirp4netns. This comes with +When using rootless Podman, network traffic is normally passed through pasta. 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. +pasta so it has the same performance characteristics as the normal network on the host. ### Starting a socket-activated service diff --git a/rootless.md b/rootless.md index 451939a362..e8970c56bd 100644 --- a/rootless.md +++ b/rootless.md @@ -7,7 +7,7 @@ The following list categorizes the known issues and irregularities with running * You can modify the `net.ipv4.ip_unprivileged_port_start` sysctl to change the lowest port. For example `sysctl net.ipv4.ip_unprivileged_port_start=443` allows rootless Podman containers to bind to ports >= 443. * A proxy server, kernel firewall rule, or redirection tool such as [redir](https://github.com/troglobit/redir) may be used to redirect traffic from a privileged port to an unprivileged one (where a podman pod is bound) in a server scenario - where a user has access to the root account (or setuid on the binary would be an acceptable risk), but wants to run the containers as an unprivileged user for enhanced security and for a limited number of pre-known ports. * As of Podman 5.0, pasta is the default networking tool. Since pasta copies the IP address of the main interface, connections to that IP from containers do not work. This means that unless you have more than one interface, inter-container connections cannot be made without explicitly passing a pasta network configuration, either in `containers.conf` or at runtime. - * If you previously had port forwards (ex. via `-p 80:80`) that other containers could access, you can either revert back to slirp4netns or use the solution (setting pasta options with `10.0.2.x` IPs) posted [here](https://blog.podman.io/2024/03/podman-5-0-breaking-changes-in-detail/). + * If you previously had port forwards (ex. via `-p 80:80`) that other containers could access, you can use the solution (setting pasta options with `10.0.2.x` IPs) posted [here](https://blog.podman.io/2024/03/podman-5-0-breaking-changes-in-detail/). * If /etc/subuid and /etc/subgid are not set up for a user, then podman commands can easily fail * Some identity providers (e.g. FreeIPA) have integrated subuid/subgid support, but many have not.