config.example.toml

# TeleGO Configuration Example
# Copy this file to config.toml and customize

# General settings
[general]
# Network binding address
# TCP: "0.0.0.0:443" or "tcp://0.0.0.0:443"
# Unix socket: "/run/telego/telego.sock" or "unix:///run/telego/telego.sock"
bind-to = "0.0.0.0:443"

# Log level: trace, debug, info, warn, error
log-level = "info"

# Accept incoming PROXY protocol headers (from HAProxy/nginx)
# When enabled, parses PROXY protocol v1/v2 to get real client IP
# proxy-protocol = false

# Maximum connections per IP (0 = unlimited)
# Applies to ALL connections (including unauthenticated) from a single IP.
# Protects against connection floods from scanners/probes.
# max-connections-per-ip = 100

# Max time to complete handshake before closing (default: 5s)
# Connections that don't authenticate within this time are dropped.
# handshake-timeout = "5s"

# Maximum unique IP addresses per user/secret (0 = unlimited)
# When exceeded, oldest IP is evicted and blocked. Protects against secret sharing.
# max-ips-per-user = 3

# How long evicted IPs stay blocked (refreshes on connection attempts)
# ip-block-timeout = "5m"

# Correct a skewed server clock at startup from a remote HTTP Date header.
# The FakeTLS handshake check rejects clients whose timestamp is outside a few
# seconds of the server clock; on a VPS without NTP a wrong clock locks out
# everyone. When set, this URL is fetched once at boot and its Date header
# offset (clamped to +-1 day) is applied to the check. Empty = off.
# clock-sync-url = "https://www.cloudflare.com"

# Named secrets (32 hex characters = 16 bytes)
# Generate with: telego generate <hostname>
[secrets]
user1 = "0123456789abcdef0123456789abcdef"
# user2 = "fedcba9876543210fedcba9876543210"

# TLS fronting configuration
[tls-fronting]
# Host to mimic - used for certificate fetching and SNI validation
# Must match the hostname in your secret
mask-host = "www.google.com"

# Port for mask-host (optional, default: 443)
# mask-port = 443

# Where to fetch TLS certificate from (optional)
# Defaults to mask-host:mask-port if not set
# Useful when running behind a front proxy (e.g., Xray) and you need
# to fetch certs from a local nginx instance directly
# cert-host = "127.0.0.1"
# cert-port = 8443

# Where to forward unrecognized/invalid clients (optional)
# Useful for forwarding probes to a local decoy server
# Defaults to mask-host:mask-port if not set
# splice-host = "127.0.0.1"
# splice-port = 8080

# Send PROXY protocol header to splice target (optional)
# Allows backend (nginx/haproxy) to see real client IP
# 0 = off (default), 1 = v1 (text), 2 = v2 (binary)
# splice-proxy-protocol = 1

# Idle timeout for spliced (unrecognized) connections (default: 30s)
# Shorter than authenticated connections since these are just decoy traffic.
# splice-idle-timeout = "30s"

# Size (bytes) of the fake encrypted-certificate record in the FakeTLS
# ServerHello. 0 = auto: match the mask backend's real first cert-record size
# (captured when fetching the ServerHello), so the accept path and the splice
# (probe) path present the same cert-record length. Set an explicit value only
# to override. Clamped to 256..16384.
# fake-cert-size = 0

# SNI-following mask safelist (opt-in active-probe robustness).
# When an unauthenticated probe presents a ClientHello whose SNI is on this
# list, it is fronted to THAT domain's own server (port 443) instead of the
# default splice target, so the on-wire conversation matches the claimed SNI.
# Empty = off; never an open relay (only these exact domains).
# mask-sni-safelist = ["www.microsoft.com", "www.apple.com"]

# Anti-DPI record shaping on the proxy -> client direction.
# Both default to true. Set to false to disable.
# enable-drs = true        # Chrome-style probe-then-ramp record sizer:
#                          # outbound ApplicationData starts at 1369-byte records,
#                          # ramps to 16384 after 8 records or 128 KB.
# enable-split-tls = true  # Emit first outbound ApplicationData record as 1 byte
#                          # to defeat passive signatures keyed on the first record.

# Performance tuning (all optional)
[performance]
# IP preference for DC connections: prefer-ipv4, prefer-ipv6, only-ipv4, only-ipv6
prefer-ip = "prefer-ipv4"

# Connection idle timeout
idle-timeout = "5m"

# Break the iOS "Updating" wedge (bad_server_salt). After a long background, an
# iOS client can discard the DC's salt and stop sending, hanging ~90-120s until
# the DC closes the socket. When set, the proxy closes a relay whose last
# relayed payload was server->client and has gone unanswered by the client for
# this long, triggering an instant (~450ms) clean reconnect. A healthy idle
# connection (whose last word was its own request/ack) is never touched.
# Best-effort: a value below your slowest legitimate server response will
# occasionally close a healthy connection too (just a brief reconnect). Keep it
# well above that. 0 = off (default); ~10-15s is a sane starting point.
# Requires a restart to change (enables the engine ticker).
# client-silence-close = "12s"

# Number of event loops (0 = auto, uses all CPU cores)
num-event-loops = 0

# Max pending write bytes per connection before closing slow client (MB)
# Prevents memory exhaustion when clients are slow to receive data
# 0 = 4MB default, which allows ~4MB buffered data per connection
# max-write-buffer-mb = 4

# Upstream (DC connection) settings
[upstream]
# SOCKS5 proxy for Telegram DC connections
# Useful for routing through VPN/tunnel (e.g., Hysteria2, VLESS)
# socks5 = "127.0.0.1:1080"

# Prometheus metrics endpoint (optional)
[metrics]
# Address to bind metrics server (empty = disabled)
# bind-to = "127.0.0.1:9090"

# Metrics path (default: /metrics)
# path = "/metrics"