Configuration

tcpcc accepts direct CLI service options or an explicit versioned TOML file. Both paths converge on the same native runtime configuration.

The canonical schema is maintained in docs/configuration.md in the main repository.

Minimal configuration

version = 1
cc = "bbr"
memory_mib = 128

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

Validate it without creating the runtime packet path:

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

Then start the same configuration:

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

Important rules

  • version = 1 is required.
  • Unknown keys, duplicate keys, wrong types, malformed endpoints, and unsupported versions are fatal.
  • Public listen endpoints may be literal IPv4 or bracketed IPv6.
  • The backend is currently restricted to 127.0.0.1:PORT.
  • All public listeners in one process must use the same address family.
  • Public TCP ports must be unique within one process.
  • Configuration is startup-only; there is no SIGHUP hot reload.
  • --check is the only service CLI option that may be combined with --config. tcpcc does not define an override-precedence layer between TOML and direct service options.

Multiple listeners

version = 1
cc = "bbr"
memory_mib = 128

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

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

IPv6

IPv6 literals must use brackets:

version = 1
cc = "bbr"
memory_mib = 128

[[forward]]
listen = "[2001:db8::10]:443"
backend = "127.0.0.1:8443"

When TUN addresses are omitted, the runtime chooses defaults for the listener family:

Public family Host TUN address Hosted TUN address
IPv4 198.18.0.1 198.18.0.2
IPv6 fd00:198:18::1 fd00:198:18::2

Explicit TUN addresses must match the public listener family and must differ from each other.

Memory and admission

Hosted RAM defaults to a 128 MiB guest-capacity arena. Physical host residency is demand-backed and reclaimable; --memory-mib=N is not an instruction to eagerly resident all N MiB.

--max-connections 0 is the default and disables the admission-policy ceiling. A positive value opts into an aggregate service-wide limit.