---
created: '2026-04-15T18:16:04+00:00'
id: 1bb3f6ca-2bd4-4695-8258-69172c16cc0b
keywords:
- traefik
- traefik proxy
- edge router
- application proxy
- docker labels
- traefik middleware
- acme
- letsencrypt
- certresolver
- entrypoint
- traefik v3
links: []
modified: '2026-04-15T18:16:04+00:00'
summary: Comprehensive reference for Traefik Proxy v3.x — an open-source application
  proxy and edge router with auto-discovery, dynamic routing, TLS termination, middleware
  chains, and multi-provider support including Docker, Kubernetes, and cloud platforms.
tags:
- reference
- traefik
- proxy
- reverse-proxy
- load-balancer
- docker
- kubernetes
- routing
- tls
- letsencrypt
- middleware
- observability
title: Traefik Proxy — Reference Documentation
---

---
title: Traefik Proxy — Reference Documentation
created: 2025-07-15
modified: 2025-07-15
tags:
  - reference
  - traefik
  - proxy
  - reverse-proxy
  - load-balancer
  - docker
  - kubernetes
  - routing
  - tls
  - letsencrypt
  - middleware
  - observability
links:
  - reference/docker-compose.md
keywords:
  - traefik
  - traefik proxy
  - edge router
  - application proxy
  - docker labels
  - traefik middleware
  - acme
  - letsencrypt
  - certresolver
  - entrypoint
  - traefik v3
summary: Comprehensive reference for Traefik Proxy v3.x — an open-source application proxy and edge router with auto-discovery, dynamic routing, TLS termination, middleware chains, and multi-provider support including Docker, Kubernetes, and cloud platforms.
---

# Traefik Proxy — Reference Documentation

> Source: https://doc.traefik.io/traefik/ (accessed July 2025)
> Version: v3.x (current)

## What is Traefik?

Traefik is an open-source **Application Proxy** and edge router that automatically discovers services and dynamically configures routing. Key characteristics:

- **Auto-discovery**: Inspects infrastructure (Docker, Kubernetes, etc.) to detect services and configure routes in real time — no restarts, no connection interruptions.
- **3.3 billion downloads**, 55k+ GitHub stars.
- Runs across hybrid cloud, multi-cloud, on-prem, and bare metal environments.
- Supports Kubernetes, Docker Swarm, AWS ECS, and more.

### Core Concepts

| Concept | Description |
|---------|-------------|
| **Entrypoints** | Network entry points. Define port (TCP/UDP) and protocol. |
| **Routers** | Connect incoming requests to services based on rules. May apply middleware before forwarding. |
| **Services** | Configure how to reach backend services (load balancing, etc.). |
| **Providers** | Infrastructure components (orchestrators, container engines, cloud providers, KV stores) that Traefik queries for routing info. Routes hot-reload on provider changes. |

### Request Flow

```
Client → Entrypoint → Router (rule match) → [Middlewares] → Service → Backend
```

---

## Configuration Overview

Traefik has **two distinct configuration layers**:

### 1. Install (Startup) Configuration

Sets up connections to providers and defines entrypoints. Doesn't change often. Defined via (mutually exclusive, priority order):

- **Configuration file**: `traefik.yml`/`traefik.yaml`/`traefik.toml` in `/etc/traefik/`, `$XDG_CONFIG_HOME/`, `$HOME/.config/`, or `./`. Override with `--configFile`.
- **CLI arguments**: `traefik --help` for full list.
- **Environment variables**: All install options available as env vars.

### 2. Routing Configuration (Dynamic)

Defines how requests are handled. Comes from **providers** and is **hot-reloaded** without interruption. Includes:

- HTTP/TCP/UDP routers, services, and middlewares
- TLS certificates
- Can be added/updated/removed without restarting

---

## Entrypoints

Entrypoints define where Traefik listens for incoming traffic.

### Basic Configuration

```yaml
entryPoints:
  web:
    address: ":80"
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https
          permanent: true

  websecure:
    address: ":443"
    http:
      tls: {}
      middlewares:
        - auth@kubernetescrd
        - strip@kubernetescrd
```

### Key Entrypoint Options

| Option | Description | Default |
|--------|-------------|---------|
| `address` | Port and protocol (e.g., `:80`, `:443`, `:8080/udp`) | — |
| `http.tls` | Enable default TLS for routers on this entrypoint | `false` |
| `http.redirections.entryPoint` | Auto-redirect to another entrypoint | — |
| `http.middlewares` | Default middlewares for all routers on this entrypoint | — |
| `http.sanitizePath` | Normalize paths (remove `/./`, `/../`, double slashes) | `true` |
| `forwardedHeaders.trustedIPs` | Trust X-Forwarded-\* headers only from these IPs | — |
| `forwardedHeaders.insecure` | Trust all forwarded headers | `false` |
| `http3` | Enable HTTP/3 (uses UDP on same port number) | `false` |
| `proxyProtocol.trustedIPs` | Enable PROXY protocol from specific IPs | — |
| `reusePort` | Allow multiple processes on same port (Linux/BSD/macOS) | `false` |
| `asDefault` | Include in default entrypoints for routers without explicit entrypoints | `false` |
| `allowACMEByPass` | Allow custom routers to handle ACME challenges | `false` |
| `observability.accessLogs` | Per-entrypoint access log toggle | `true` |
| `observability.metrics` | Per-entrypoint metrics toggle | `true` |
| `observability.tracing` | Per-entrypoint tracing toggle | `true` |
| `transport.lifecycle.graceTimeOut` | Grace period for active requests on shutdown | `10s` |
| `transport.respondingTimeouts.readTimeout` | Max duration to read full request | `60s` |
| `transport.respondingTimeouts.writeTimeout` | Max duration to write response | `0` (none) |
| `transport.respondingTimeouts.idleTimeout` | Max keep-alive idle duration | `180s` |
| `http2.maxConcurrentStreams` | Max concurrent HTTP/2 streams per connection | `250` |

---

## HTTP Routers

Routers connect incoming requests to services based on matching rules.

### Configuration Example

```yaml
http:
  routers:
    my-router:
      entryPoints:
        - "web"
        - "websecure"
      rule: "Host(`example.com`) && Path(`/api`)"
      priority: 10
      middlewares:
        - "auth"
        - "ratelimit"
      tls:
        certResolver: "letsencrypt"
        options: "modern"
        domains:
          - main: "example.com"
            sans:
              - "www.example.com"
      service: my-service
      observability:
        metrics: true
        accessLogs: true
        tracing: true
```

### Router Configuration Options

| Field | Description | Required |
|-------|-------------|----------|
| `rule` | Matching rule (matchers: `Host()`, `Path()`, `PathPrefix()`, `Headers()`, `Query()`, `Method()`, etc.) | Yes |
| `entryPoints` | List of entrypoints (default: all) | No |
| `service` | Service to forward matched requests to | Yes |
| `priority` | Rule priority (default: auto by rule length; `0` ignored; negatives supported) | No |
| `middlewares` | Ordered list of middleware names to apply | No |
| `tls` | Enable TLS (router only handles HTTPS when set) | No |
| `tls.certResolver` | ACME certificate resolver name | No |
| `tls.options` | TLS options name (cipher suites, min/max version, client auth) | No |
| `tls.domains` | Explicit domain/SAN list for certificates | No |
| `observability` | Per-router metrics, access logs, tracing overrides | No |
| `parentRefs` | Parent routers for multi-layer routing | No |

### Rule Examples

```
Host(`example.com`)
Path(`/api`)
Host(`example.com`) && PathPrefix(`/api`)
Headers(`X-Custom`, `value`)
Method(`GET`, `POST`)
HostRegexp(`{subdomain:.+}.example.com`)
```

---

## Services

Services configure how to reach backend servers. Each service has a load balancer.

```yaml
http:
  services:
    my-service:
      loadBalancer:
        servers:
          - url: "http://10.0.0.1:8080"
          - url: "http://10.0.0.2:8080"
        passHostHeader: true
        sticky:
          cookie:
            name: traefik_lb
            secure: true
            httpOnly: true
```

Service types: **loadBalancer** (round-robin, weighted, mirroring, failover).

---

## Middlewares

Middlewares modify requests/responses before forwarding. Applied in declared order on routers, **and** can be attached to entrypoints (applied before router-level middleware).

### Available HTTP Middlewares (OSS)

| Middleware | Purpose |
|-----------|---------|
| **AddPrefix** | Add path prefix |
| **StripPrefix** | Strip path prefix |
| **StripPrefixRegex** | Strip path prefix via regex |
| **ReplacePath** | Replace request path |
| **ReplacePathRegex** | Replace path via regex |
| **RedirectRegex** | Redirect based on regex match |
| **RedirectScheme** | Redirect to different scheme (HTTP→HTTPS) |
| **Headers** | Add/remove/modify request/response headers |
| **BasicAuth** | HTTP Basic Authentication |
| **DigestAuth** | HTTP Digest Authentication |
| **ForwardAuth** | Delegate auth to external service |
| **RateLimit** | Rate limiting per source IP |
| **InFlightReq** | Limit concurrent requests |
| **CircuitBreaker** | Circuit breaker pattern |
| **Retry** | Retry failed requests |
| **Compress** | Gzip compression |
| **Buffering** | Buffer request/response |
| **Errors** | Custom error pages |
| **IPAllowList** | IP whitelist/blacklist |
| **ContentType** | Content-Type validation |
| **PassTLSClientCert** | Pass client certificate info in headers |
| **GrpcWeb** | gRPC-Web support |
| **Chain** | Combine multiple middlewares |

### Middleware Declaration (Docker Labels)

```yaml
labels:
  # Declare middleware
  - "traefik.http.middlewares.my-redirect.redirectscheme.scheme=https"
  # Apply to router
  - "traefik.http.routers.my-container.middlewares=my-redirect"
```

---

## Docker Provider

Traefik discovers Docker containers and creates routes from labels. Docker is a **first-class provider**.

### Enabling

```yaml
# In traefik.yml or CLI:
providers:
  docker: {}
# CLI: --providers.docker=true
```

### Docker Provider Options

| Option | Description | Default |
|--------|-------------|---------|
| `endpoint` | Docker API endpoint | `unix:///var/run/docker.sock` |
| `exposedByDefault` | Expose all containers automatically | `true` |
| `network` | Default Docker network | — |
| `watch` | Watch Docker events | `true` |
| `defaultRule` | Default routing rule template | `Host({{ normalize .Name }})` |
| `constraints` | Filter which containers to route | — |
| `useBindPortIP` | Use bound port IP instead of inner network IP | `false` |

### Docker Label Examples

```yaml
services:
  whoami:
    image: traefik/whoami
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.whoami.rule=Host(`whoami.localhost`)"
      - "traefik.http.routers.whoami.entrypoints=websecure"
      - "traefik.http.routers.whoami.tls=true"
```

#### Custom Container Port

```yaml
labels:
  - "traefik.http.routers.my-container.rule=Host(`example.com`)"
  - "traefik.http.services.my-service.loadbalancer.server.port=12345"
```

#### Multiple Routers per Container

```yaml
labels:
  - "traefik.http.routers.www-router.rule=Host(`example-a.com`)"
  - "traefik.http.routers.www-router.service=www-service"
  - "traefik.http.services.www-service.loadbalancer.server.port=8000"
  - "traefik.http.routers.admin-router.rule=Host(`example-b.com`)"
  - "traefik.http.routers.admin-router.service=admin-service"
  - "traefik.http.services.admin-service.loadbalancer.server.port=9000"
```

#### TCP Routing

```yaml
labels:
  - "traefik.tcp.routers.my-router.rule=HostSNI(`example.com`)"
  - "traefik.tcp.routers.my-router.tls=true"
  - "traefik.tcp.services.my-service.loadbalancer.server.port=4123"
```

#### UDP Routing

```yaml
labels:
  - "traefik.udp.routers.my-router.entrypoints=udp"
  - "traefik.udp.services.my-service.loadbalancer.server.port=4123"
```

### Automatic Service Assignment

1. If a router rule is defined and a service port is set, but router doesn't specify a service → service auto-assigned.
2. If only a router rule is defined with no service at all → service auto-created and assigned.
3. If router explicitly names a service → that service is used.

---

## TLS

### Per-Router TLS

```yaml
http:
  routers:
    my-router:
      rule: "Host(`example.com`)"
      tls:
        certResolver: "letsencrypt"
```

### Certificate Resolvers (ACME / Let's Encrypt)

```yaml
certificatesResolvers:
  le:
    acme:
      email: "admin@example.com"
      storage: "/letsencrypt/acme.json"
      httpChallenge:
        entryPoint: web
      # dnsChallenge:
      #   provider: your-dns-provider
```

### Entrypoint-Level Default TLS

```yaml
entryPoints:
  websecure:
    address: ":443"
    http:
      tls:
        certResolver: "le"
```

### ACME Challenge Types

- **HTTP-01**: Uses port 80 entrypoint (most common)
- **DNS-01**: Uses DNS TXT records (wildcard certs, no exposed port needed)
- **TLS-ALPN-01**: Uses port 443 entrypoint

---

## Observability

### Access Logs

```yaml
accessLog:
  filePath: "/path/to/access.log"
  format: json           # json | common
  filters:
    statusCodes: "400-599"
    minDuration: "10ms"
    retryAttempts: true
```

### Metrics

```yaml
metrics:
  prometheus:
    entryPoint: metrics
    addRoutersLabels: true
    addServicesLabels: true
  otlp:
    grpc:
      endpoint: "localhost:4317"
```

Supported exporters: **Prometheus**, **Datadog**, **StatsD**, **InfluxDB v2**, **OpenTelemetry (OTLP)**.

### Tracing

```yaml
tracing:
  otlp:
    grpc:
      endpoint: "otel-collector:4317"
    http:
      endpoint: "otel-collector:4318"
```

### Per-Component Observability Override

All three (access logs, metrics, tracing) can be disabled/enabled per entrypoint or per router:

```yaml
entryPoints:
  web:
    observability:
      accessLogs: false
      metrics: false
      tracing: false
```

---

## Complete Docker Setup Example

```yaml
services:
  traefik:
    image: traefik:v3.6
    container_name: traefik
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    networks:
      - proxy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./certs:/certs:ro
      - ./dynamic:/dynamic:ro
    command:
      # Entrypoints
      - "--entrypoints.web.address=:80"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--entrypoints.web.http.redirections.entrypoint.permanent=true"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.websecure.http.tls=true"
      # Providers
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--providers.docker.network=proxy"
      - "--providers.file.filename=/dynamic/tls.yaml"
      # Dashboard (secured)
      - "--api.dashboard=true"
      - "--api.insecure=false"
      # Observability
      - "--log.level=INFO"
      - "--accesslog=true"
      - "--metrics.prometheus=true"
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.dashboard.rule=Host(`dashboard.docker.localhost`)"
      - "traefik.http.routers.dashboard.entrypoints=websecure"
      - "traefik.http.routers.dashboard.service=api@internal"
      - "traefik.http.routers.dashboard.tls=true"
      - "traefik.http.middlewares.dashboard-auth.basicauth.users=<HASH>"
      - "traefik.http.routers.dashboard.middlewares=dashboard-auth@docker"
```

---

## Supported Providers

| Provider | Type | Config Method |
|----------|------|--------------|
| Docker | Orchestrator | Labels |
| Kubernetes (CRD, Gateway API, Ingress) | Orchestrator | CRDs / Ingress |
| Docker Swarm | Orchestrator | Labels |
| Consul / Consul Catalog | Service Registry | KV tags |
| Nomad | Orchestrator | Tags |
| Redis / etcd / ZooKeeper / Consul (KV) | KV Store | Keys |
| File | Config File | YAML/TOML |
| HTTP | REST API | JSON/YAML |
| AWS ECS | Cloud | Labels |

---

## Key CLI Reference

```bash
# Run with Docker
docker run -d -p 80:80 -p 443:443 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $PWD/traefik.yml:/etc/traefik/traefik.yml \
  traefik:v3.6

# Help
traefik --help

# Override config file
traefik --configFile=foo/bar/myconfigfile.yml
```