From baf8fa6223db7fddb9707da6dddfffd3f21bc6fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Rod=C3=A1k?= Date: Mon, 11 May 2026 20:17:35 +0200 Subject: [PATCH] Document pasta forwarding mode for rootless bridge networks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Jan Rodák --- docs/source/markdown/options/network.md | 2 ++ docs/source/markdown/options/publish.md | 8 ++++++++ docs/source/markdown/podman-info.1.md | 2 ++ docs/tutorials/basic_networking.md | 8 ++++++++ rootless.md | 1 + 5 files changed, 21 insertions(+) diff --git a/docs/source/markdown/options/network.md b/docs/source/markdown/options/network.md index 9234289da3..3a33d9253c 100644 --- a/docs/source/markdown/options/network.md +++ b/docs/source/markdown/options/network.md @@ -35,6 +35,8 @@ Valid _mode_ values are: Any other options will be passed through to netavark without validation. This can be useful to pass arguments to netavark plugins. + For rootless bridge networks, port forwarding uses `rootlessport` by default. Setting `rootless_port_forwarder="pasta"` in the `[network]` section of **[containers.conf(5)](https://github.com/containers/container-libs/blob/main/common/docs/containers.conf.5.md)** switches to pasta's kernel-level forwarding (via `pesto`), which preserves the original client source IP address inside the container. This option is experimental and its behavior is subject to change. + For example, to set a static IPv4 address and a static mac address, use `--network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99`. - _\_**[:OPTIONS,...]**: Connect to a user-defined network; this is the network name or ID from a network created by **[podman network create](podman-network-create.1.md)**. It is possible to specify the same options described under the bridge mode above. Use the **--network** option multiple times to specify additional networks. \ diff --git a/docs/source/markdown/options/publish.md b/docs/source/markdown/options/publish.md index 07cc360f35..493e886088 100644 --- a/docs/source/markdown/options/publish.md +++ b/docs/source/markdown/options/publish.md @@ -28,3 +28,11 @@ Use **podman port** to see the actual mapping: `podman port $CONTAINER $CONTAINE Port publishing is only supported for containers utilizing their own network namespace through `bridge` networks, or the `pasta` network mode. + +For rootless bridge networks, port forwarding uses `rootlessport` by default, which +is a userspace proxy that does not preserve client source IPs. Setting +`rootless_port_forwarder="pasta"` in the `[network]` section of +**[containers.conf(5)](https://github.com/containers/container-libs/blob/main/common/docs/containers.conf.5.md)** +switches to pasta's kernel-level forwarding via `pesto`, preserving the original +client IP address inside the container. This option is experimental and its +behavior is subject to change. diff --git a/docs/source/markdown/podman-info.1.md b/docs/source/markdown/podman-info.1.md index f9a784b2c6..cb7151d940 100644 --- a/docs/source/markdown/podman-info.1.md +++ b/docs/source/markdown/podman-info.1.md @@ -96,6 +96,7 @@ host: spec: 1.0.0 +SYSTEMD +SELINUX +APPARMOR +CAP +SECCOMP +EBPF +CRIU +YAJL os: linux + rootlessPortForwarder: rootlessport pasta: executable: /usr/bin/passt package: passt-0^20221116.gace074c-1.fc34.x86_64 @@ -237,6 +238,7 @@ $ podman info --format json "version": "crun version 1.0\ncommit: 139dc6971e2f1d931af520188763e984d6cdfbf8\nspec: 1.0.0\n+SYSTEMD +SELINUX +APPARMOR +CAP +SECCOMP +EBPF +CRIU +YAJL" }, "os": "linux", + "rootlessPortForwarder": "rootlessport", "remoteSocket": { "path": "/run/user/3267/podman/podman.sock" }, diff --git a/docs/tutorials/basic_networking.md b/docs/tutorials/basic_networking.md index 151e2db184..112fecfdc6 100644 --- a/docs/tutorials/basic_networking.md +++ b/docs/tutorials/basic_networking.md @@ -80,6 +80,14 @@ The user experience of rootless netavark is very akin to a rootful netavark, exc there is no default network configuration provided. You simply need to create a network, and the one will be created as a bridge network. +By default, rootless bridge networks use `rootlessport` for port forwarding, which +is a userspace proxy that does not preserve client source IPs. To preserve source +IPs, set `rootless_port_forwarder="pasta"` in the `[network]` section of +`containers.conf`. This uses `pesto` to configure pasta's kernel-level forwarding, +so containers see the real client IP address instead of the bridge gateway. +This option is experimental and its behavior is subject to change. +It requires a version of passt (`>= passt-0^20260507.g1afd4ed`) that ships the `pesto` binary. + ``` $ podman network create ``` diff --git a/rootless.md b/rootless.md index e8970c56bd..ab07d56563 100644 --- a/rootless.md +++ b/rootless.md @@ -8,6 +8,7 @@ The following list categorizes the known issues and irregularities with running * 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 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/). +* Rootless bridge networks use `rootlessport` for port forwarding by default, which is a userspace proxy that does not preserve client source IPs. Setting `rootless_port_forwarder="pasta"` in the `[network]` section of `containers.conf` switches to pasta's kernel-level forwarding (via `pesto`), preserving the original client IP. This option is experimental and its behavior is subject to change. It requires a version of passt (`>= passt-0^20260507.g1afd4ed`) that ships the `pesto` binary. * 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.