Quick start

This page is the shortest path from a suitable host to a tcpcc listener.

Prerequisites

The host/container must provide the packet path that tcpcc needs:

  • a usable /dev/net/tun;
  • enough network authority to configure the TUN interface and firewall state;
  • nftables or the selected iptables backend;
  • IP forwarding enabled for the public address family;
  • a loopback backend listening on 127.0.0.1:<port>.

The outer host does not need to provide BBR. Congestion control for the public connection is selected inside the hosted Linux stack.

Check forwarding:

sysctl net.ipv4.ip_forward
sysctl net.ipv6.conf.all.forwarding

IPv4 listeners require net.ipv4.ip_forward=1. IPv6 listeners require net.ipv6.conf.all.forwarding=1.

Build and install

From the source tree:

bash ./scripts/validate-tcpcc-bootstrap.sh
sudo make install

The installed runtime is native C and does not depend on Python.

Start a listener

Assume an application already listens on 127.0.0.1:8443:

sudo tcpcc \
  --forward 203.0.113.10:443=127.0.0.1:8443 \
  --cc bbr

The public TCP connection terminates inside hosted Linux. tcpcc then opens a separate ordinary loopback TCP connection to the backend.

Multiple forwards

Repeat the complete --forward LISTEN=BACKEND mapping:

sudo tcpcc \
  --forward 203.0.113.10:443=127.0.0.1:8443 \
  --forward 203.0.113.10:8443=127.0.0.1:9443 \
  --cc bbr

All public listeners in one process currently use one address family and must use distinct public TCP ports.

Prefer TOML for services

For long-running deployments, see Configuration. tcpcc never loads a configuration file implicitly; the operator must pass --config FILE.