Learn Traefik - TCP & UDP Routing

#Introduction

So far all Traefik routing has dealt with HTTP. But Traefik is also a capable TCP and UDP proxy: PostgreSQL databases, SSH, SMTP, DNS, and game servers can all pass through the same gateway, with flexible routing rules and TLS passthrough.

Episode 18 dissects three layers: TCP routers with HostSNI, UDP routers, and the TLS passthrough pattern. By understanding these, you can centralize all your network access — not just web — into a single control point.

#TCP Routers and Entrypoints

#Defining TCP Entrypoints

A TCP entrypoint is defined with the tcp protocol. Naming is free, e.g. ssh, db, or smtp:

entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"
  ssh:
    address: ":2222"
  db:
    address: ":5432"

#The HostSNI Rule

TCP routers use HostSNI as the main matcher — the same value as SNI in the TLS handshake. An example TCP router for a PostgreSQL database, complete with the equivalent traefik.tcp.routers.pg.rule label alternative in Docker:

tcp:
  routers:
    pg-internal:
      rule: "HostSNI(`pg.internal.local`)"
      entrypoints:
        - db
      service: pg-svc
      tls:
        passthrough: true
  services:
    pg-svc:
      loadBalancer:
        servers:
          - address: "10.0.0.80:5432"

Note tls.passthrough: true: Traefik does not decrypt the connection, only sees SNI to decide the route, then forwards the raw stream to PostgreSQL. The backend holds the certificate and handles TLS entirely.

#TLS Termination vs. Passthrough on TCP

#Two Modes for TCP

• Termination: Traefik holds the certificate, decrypts, and forwards plaintext to the backend. Suitable if the backend does not want to deal with TLS. TCP middlewares like IPWhiteList can still be applied.
• Passthrough: Traefik only splices the stream. Required if the backend demands end-to-end TLS or the protocol does not support mid-stream decryption.

tcp:
  routers:
    smtp-secure:
      rule: "HostSNI(`mail.example.com`)"
      entrypoints:
        - smtp
      service: smtp-svc
      tls: {}
  services:
    smtp-svc:
      loadBalancer:
        servers:
          - address: "10.0.0.90:2525"

The SMTP router above uses tls: {} — Traefik handles TLS with the available certificates, then forwards plaintext to the backend on an internal port. The best time to choose termination: you want a single place for certificates; the best time for passthrough: end-to-end security is mandatory.

#Common TCP Use Cases

#Databases, SSH, and More

• PostgreSQL/MySQL: HostSNI route per instance, terminate or passthrough as needed.
• SSH: passthrough to the destination server; because SSH uses its own protocol, SNI-based routing is unavailable — use a separate entrypoint per destination.
• SMTP/IMAP: terminate at Traefik to consolidate mail server certificates.
• Custom protocols: anything TCP-based can be routed as long as a matcher is available.

For protocols that do not use TLS at all (e.g. raw SSH), Traefik provides a special matcher: the HostSNI(*) rule matches all connections and directs them to the chosen service. This is the pattern used for single-purpose entrypoints:

tcp:
  routers:
    ssh-gateway:
      rule: "HostSNI(`*`)"
      entrypoints:
        - ssh
      service: ssh-svc
  services:
    ssh-svc:
      loadBalancer:
        servers:
          - address: "10.0.0.100:22"

#UDP Routers and Services

#UDP Entrypoints and Load Balancing

UDP works similarly to TCP, with one big difference: there is no handshake. For that reason, UDP routers use the HostSNI(*) rule to accept all datagrams on their entrypoint:

entryPoints:
  dns-udp:
    address: ":53/udp"
 
udp:
  routers:
    dns-router:
      rule: "HostSNI(`*`)"
      entrypoints:
        - dns-udp
      service: dns-svc
  services:
    dns-svc:
      loadBalancer:
        servers:
          - address: "10.0.0.110:53"

#UDP Use Cases

• DNS proxying: forwards DNS queries to an internal resolver.
• Game servers: many games use UDP for gameplay.
• VoIP/SIP: UDP-based telephony protocols.
• Custom UDP protocols: as long as Traefik only forwards datagrams, anything can be a target.

UDP load balancing in Traefik forwards datagrams to a server selected based on the route; because of its connectionless nature, server selection uses a hash of the source address to keep conversation consistency.

#Closing

Key takeaways:

• TCP and UDP entrypoints are defined separately in static config.
• TCP routers use HostSNI as the matcher; HostSNI(*) covers everything.
• TLS passthrough passes the raw stream; termination decrypts at Traefik.
• Databases, SSH, SMTP, and custom protocols can all be routed.
• UDP routers use HostSNI(*) and can load-balance datagrams.
• Use separate entrypoints for TCP and UDP on the same port.

In episode 19 next we will cover file provider & dynamic configuration — writing routers, services, and middlewares in YAML/TOML files, directory watching with hot reload, the http, tcp, udp, and tls section structure, and best practices for non-container services. Your gateway can now manage anything without Docker.