Entry points

Entry points are the listeners that receive client traffic. Each one binds to an address (e.g. :80, :443, :8080) and decides which protocol stack to run on top.

Where the code lives

File	Purpose
pkg/config/static/entrypoints.go	Configuration types: address, transport, HTTP, HTTP/2, HTTP/3, UDP, ProxyProtocol, ForwardedHeaders.
pkg/server/server_entrypoint_tcp.go	TCP entry-point implementation (HTTP, HTTPS, raw TCP, TLS muxing). 27k bytes.
pkg/server/server_entrypoint_tcp_http3.go	HTTP/3 (QUIC) listener, attached to a TCP entry point with TLS enabled.
pkg/server/server_entrypoint_udp.go	UDP entry-point implementation.
pkg/server/server_entrypoint_listenconfig_*.go	Per-OS socket-option helpers (Linux, FreeBSD, generic, Windows).
pkg/server/socket_activation*.go	systemd socket-activation hand-off.

Configuration shape

A simple entry point is just an address:

entryPoints:
  web:
    address: :80
  websecure:
    address: :443
    http3: {}
    asDefault: true

pkg/config/static/entrypoints.go decodes this into:

type EntryPoint struct {
    Address          string
    AsDefault        bool
    Transport        *EntryPointsTransport
    ProxyProtocol    *ProxyProtocol
    ForwardedHeaders *ForwardedHeaders
    HTTP             HTTPConfig
    HTTP2            *HTTP2Config
    HTTP3            *HTTP3Config
    UDP              *UDPConfig
    AllowACMEByPass  bool
    ReusePort        bool
    Observability    ObservabilityConfig
}

Notable nested types:

• HTTPConfig controls per-entry-point HTTP redirections, EncodeQuerySemicolons, MaxHeaderBytes.
• HTTP3Config carries the HTTP/3 advertised port, the QUIC config, and rate-limit knobs.
• Transport controls Listen/Idle timeouts, Lifecycle (graceful shutdown), KeepAlive parameters, RespondingTimeouts.
• ProxyProtocol whitelists which client networks can speak PROXY protocol (v1 + v2).
• ForwardedHeaders whitelists which networks can set X-Forwarded-* headers (the rest are stripped).
• Observability toggles whether access logs / metrics / tracing apply on this entry point. Defaults to enabled.

Lifecycle

Entry points are constructed by Server.NewServer in pkg/server/server.go. The constructor receives:

• entryPoints TCPEntryPoints — a map of EntryPointName → *TCPEntryPoint.
• entryPointsUDP UDPEntryPoints — same for UDP.
• The configuration watcher.
• The observability manager.

graph TD
    StaticConf[Static config<br/>entryPoints map] --> NewTCPEntryPoint
    NewTCPEntryPoint --> SocketActivation[systemd socket activation?<br/>pkg/server/socket_activation.go]
    NewTCPEntryPoint --> ListenConfig[ListenConfig<br/>OS sockopts]
    ListenConfig --> Listener[net.Listener]
    Listener --> TCPEP[*TCPEntryPoint]
    TCPEP --> Switcher[handler switcher<br/>updated each apply]
    TCPEP --> HTTP3[Optional HTTP/3 listener]

Start and Stop are called from Server.Start and Server.Stop. The order is deliberate:

1. Build all entry points up front (so :80 and :443 are bound before configuration is applied).
2. Start TCP entry points.
3. Start UDP entry points.
4. Start the watcher.

The reverse order applies during shutdown so in-flight requests can drain before listeners close.

TCP entry-point internals

pkg/server/server_entrypoint_tcp.go is the workhorse. Its responsibilities:

• Accept TCP connections.
• Optionally negotiate TLS (using pkg/tls/tlsmanager.go).
• Sniff ALPN to dispatch to HTTP/1.x, HTTP/2, or raw TCP.
• For raw TCP and TLS-passthrough connections, hand off to the TCP muxer (pkg/muxer/tcp).
• For HTTP, hand off to the swappable HTTP handler.

The handler is swappable because pkg/server/routerfactory.go calls tcpEntryPoint.SwitchRouter(...) after each configuration apply. The swap is atomic — new connections see the new tree, in-flight connections continue with whatever they had.

HTTP/3 sidecar

When an entry point has HTTP3 enabled, an additional QUIC listener is created and attached as a sibling. pkg/server/server_entrypoint_tcp_http3.go wraps quic-go's http3.Server and forwards requests through the same handler tree as the TCP entry point. The Alt-Svc header is added on the TCP side so clients can upgrade.

TLS handling

TLS termination uses a tls.Config returned by pkg/tls/tlsmanager.go. The manager looks up:

• The certificate for the SNI name (or default certificate).
• The cipher suite list for the named tls.options (default if not specified).
• The ACME challenge certificate when an ACME validation is in progress.

When tls.passthrough is set on a TCP router, the entry point does not terminate TLS — it forwards the encrypted bytes to the matched TCP service.

PROXY protocol

If the connection comes from an address listed in ProxyProtocol.TrustedIPs, the entry point reads the PROXY header (v1 or v2) before any other processing. The original client address replaces RemoteAddr for downstream logic.

UDP entry-point internals

UDP is much simpler: pkg/server/server_entrypoint_udp.go accepts UDP datagrams, groups them into sessions keyed by source address, and forwards each session to the matched UDP service. There is no TLS or muxing — UDP routers match purely on destination port.

socket activation

pkg/server/socket_activation_unix.go checks LISTEN_FDS and LISTEN_FDNAMES (systemd's socket-activation contract). When present, listeners come from inherited file descriptors instead of net.Listen. This lets a service manager hand sockets to Traefik for zero-downtime restarts.

The Windows stub (socket_activation_windows.go) is a no-op.

Reuse port

When EntryPoint.ReusePort is set, the listener is created with SO_REUSEPORT so multiple Traefik processes (or rolling-restart instances) can bind the same port. The kernel does the load balancing across the listening sockets.

Tests

• pkg/server/server_entrypoint_tcp_test.go covers TLS, ALPN, PROXY, request lifecycle.
• pkg/server/server_entrypoint_tcp_http3_test.go covers HTTP/3 specifics.
• pkg/server/server_entrypoint_udp_test.go covers UDP session handling.
• integration/keepalive_test.go, proxy_protocol_test.go, https_test.go, and simple_test.go give end-to-end coverage from a real client.

Entry points for modification

• A new transport-level option goes into EntryPointsTransport in pkg/config/static/entrypoints.go, then is read by server_entrypoint_tcp.go.
• A new HTTP-level option goes into HTTPConfig and is wired in the same file.
• HTTP/3 settings are independent of HTTP/2 — both can coexist on the same address.