linux-tcp-cc¶

linux-tcp-cc runs upstream Linux TCP congestion control on public TCP connections even when the surrounding host or container kernel cannot provide or select that algorithm.

The primary target is a constrained VPS/container such as OpenVZ: the tenant can use TUN and netfilter and can run an ordinary application, but cannot replace the provider kernel, load tcp_bbr, or change the host TCP congestion-control policy.

tcpcc moves ownership of the public TCP endpoint into a small userspace-hosted upstream Linux network stack. The application remains an ordinary loopback service.

remote client
    |
    | public TCP packets
    v
outer host DNAT / conntrack
    |
    | raw IPv4 or IPv6 packets
    v
TUN
    |
    v
hosted upstream Linux TCP listener
    |  TCP_CONGESTION = --cc
    |  upstream CUBIC / BBR / recovery / rate sampling / fq
    v
byte-stream bridge
    |
    | separate ordinary host-loopback TCP connection
    v
127.0.0.1 backend

Download / Releases Production deployment Build from source

Quick start¶

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

For a long-running service, use an explicit versioned TOML file:

version = 1
cc = "bbr"
memory_mib = 128

[[forward]]
listen = "203.0.113.10:443"
backend = "127.0.0.1:8443"

Then validate and start it:

sudo tcpcc --check --config /etc/tcpcc/tcpcc.toml
sudo tcpcc --config /etc/tcpcc/tcpcc.toml

Design goal¶

The defining choice is upstream Linux fidelity. tcpcc moves public TCP ownership into hosted Linux so BBR, CUBIC, delivery-rate sampling, recovery, and fq remain Linux-owned behavior rather than project reimplementations.

That costs more memory than a purpose-built userspace stack. The project accepts that tradeoff and optimizes the hosting/runtime boundary instead. See Why upstream Linux.

What tcpcc is¶

• A userspace-hosted upstream Linux networking stack.
• A way to make the hosted Linux kernel own the public TCP socket.
• A TUN + DNAT packet path in front of an ordinary loopback application.
• A native C supervisor plus a small hosted vmlinux.
• A project that preserves upstream BBR, CUBIC, rate sampling, loss recovery, and fq instead of reimplementing them.

What tcpcc is not¶

• It is not an HTTP, SOCKS, or application-layer proxy.
• It is not a new congestion-control implementation.
• It is not an embedded-Linux project.
• It does not make TUN, netfilter, or IP forwarding unnecessary.
• It does not apply --cc to the separate loopback backend TCP connection.

Current branch¶

The current supported series is Linux 6.18.y.

The exact pinned stable patch is intentionally not duplicated here. Use GitHub Releases for published binaries and release notes, or the source repository for current branch state.

Documentation map¶

Start with:

1. Quick start
2. Installation / build from source
3. Production deployment
4. Architecture
5. Why upstream Linux
6. Configuration
7. Networking and TUN
8. Security and privileges
9. Benchmarks and evidence
10. Related projects / prior art
11. Troubleshooting