Document pasta forwarding mode for rootless bridge networks

Signed-off-by: Jan Rodák <hony.com@seznam.cz>

Author: Honny1

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`.
 
 - _\<network name or ID\>_**[: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. \

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.

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"
     },

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
 ```

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.