Skip to content

port.md

Latest commit

 

History

History
84 lines (59 loc) · 4.92 KB

port.md

File metadata and controls

84 lines (59 loc) · 4.92 KB
Raw

Port Drivers

To the ports in the network namespace to the host network namespace, --port-driver needs to be specified.

The default value is none (do not expose ports).

--port-driver Throughput Source IP Notes
slirp4netns 7.56 Gbps Propagated
builtin 29.3 Gbps Propagated for TCP (since v3.0) Source IP propagation (--source-ip-transparent) applies to TCP only; UDP is not propagated. In the case of Rootless Docker, userland-proxy has to be disabled for propagating the source IP. The underlying firewall rules use nft, falling back to iptables if nft is unavailable; the backend name is resolved eagerly at startup but rules are installed lazily on first transparent connection. --source-ip-transparent-backend can be used to force one or the other. The resolved backend is reported via the REST API (PortDriverInfo.Extra["sourceIPTransparentBackend"]).
implicit 39.9 Gbps Propagated Requires pasta network
pesto (Experimental) 45.2 Gbps Propagated Requires pasta network and passt 2026_05_07.1afd4ed or later. Supports explicit port management through rootlessctl.
gvisor-tap-vsock (Experimental) 3.77 Gbps Not propagated Throughput is currently limited; see issue link below for improvement ideas.

Benchmark: iperf3 from the parent to the child is measured on GitHub Actions (Aug 4, 2026)

The builtin driver is fast and should be the best choice for most use cases.

For pasta networks, choose the port driver based on how ports should be exposed:

  • Use pesto to expose only explicitly published ports using rootlessctl list-ports, add-ports, and remove-ports.
  • Use implicit to automatically expose ports listened on in the network namespace. This may expose ports that were not intended to be reachable from the host.

The pesto port driver is experimental. Both the pasta and pesto executables must be installed. IPv6 port forwarding additionally requires the --ipv6 flag, as the pasta network driver is IPv4-only without it.

Note

The gvisor-tap-vsock port driver is experimental.

  • Source IP is not propagated: #573
  • Current throughput is known to be slower than other drivers. We are tracking ideas for improving throughput here: #529

Exposing ports

For example, to expose 80 in the child as 8080 in the parent:

$ rootlesskit --state-dir=/run/user/1001/rootlesskit/foo --net=slirp4netns --disable-host-loopback --copy-up=/etc --port-driver=builtin bash
rootlesskit$ rootlessctl --socket=/run/user/1001/rootlesskit/foo/api.sock add-ports 0.0.0.0:8080:80/tcp
1
rootlesskit$ rootlessctl --socket=/run/user/1001/rootlesskit/foo/api.sock list-ports
ID    PROTO    PARENTIP   PARENTPORT    CHILDPORT    
1     tcp      0.0.0.0    8080          80
rootlesskit$ rootlessctl --socket=/run/user/1001/rootlesskit/foo/api.sock remove-ports 1
1

Exposing privileged ports

To expose privileged ports (< 1024), add net.ipv4.ip_unprivileged_port_start=0 to /etc/sysctl.conf (or /etc/sysctl.d) and run sudo sysctl --system.

If you are using builtin driver, you can expose the privileged ports without changing the sysctl value, but you need to set CAP_NET_BIND_SERVICE on rootlesskit binary.

$ sudo setcap cap_net_bind_service=ep $(pwd rootlesskit)

Note about IPv6

Specifying 0.0.0.0:8080:80/tcp may cause listening on IPv6 as well as on IPv4. Same applies to [::]:8080:80/tcp.

This behavior may sound weird but corresponds to Go's behavior, so this is not a bug.

To specify IPv4 explicitly, use tcp4 instead of tcp, e.g., 0.0.0.0:8080:80/tcp4. To specify IPv6 explicitly, use tcp6, e.g., [::]:8080:80/tcp6.

The tcp4 and tcp6 forms were introduced in RootlessKit v0.14.0. The tcp6 is currently supported only for the builtin and pesto port drivers.

The dual-stack behavior described above is specific to the builtin port driver. For pesto, the address family is determined only by the parent IP: 0.0.0.0:8080:80/tcp listens on IPv4 only, and [::]:8080:80/tcp listens on IPv6 only. When the parent IP is omitted, it defaults to 0.0.0.0 for tcp, tcp4, udp, and udp4, and to :: for tcp6 and udp6. Specifying a child IP other than the namespace address is not supported by pesto.

IPv6 support in pesto has been only verified for loopback parent addresses (::1, [::]).

Build tags to omit port drivers

Build-time driver selection is documented in BUILDING.md.