> ## Documentation Index
> Fetch the complete documentation index at: https://traefik-traefik.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Routers Configuration

> Configure routers to connect incoming requests to services based on rules, paths, hosts, and headers.

# Routers

Connecting Requests to Services

Routers analyze incoming requests and determine which service should handle them based on configurable rules. They are part of the **dynamic configuration**.

## HTTP Routers

### Basic Router Configuration

**YAML**

```yaml theme={null}
http:
  routers:
    my-router:
      rule: "Host(`example.com`) && Path(`/api`)"
      service: api-service
      entryPoints:
        - websecure
      tls:
        certResolver: letsencrypt
```

**TOML**

```toml theme={null}
[http.routers.my-router]
  rule = "Host(`example.com`) && Path(`/api`)"
  service = "api-service"
  entryPoints = ["websecure"]
  [http.routers.my-router.tls]
    certResolver = "letsencrypt"
```

**rule** `string` *required*

Matching rule that determines if this router handles the request

**service** `string` *required*

Name of the service to forward matching requests to

**entryPoints** `array`

List of EntryPoints to listen on. If not specified, listens on all default EntryPoints

## Routing Rules

Rules determine which requests match a router using matchers and logical operators.

### Available Matchers

**Host(`domain`)** `matcher`

Match requests to specific domain

```yaml theme={null}
rule: "Host(`example.com`)"
```

**HostRegexp(`regexp`)** `matcher`

Match requests using regular expression

```yaml theme={null}
rule: "HostRegexp(`^.+\\.example\\.com$`)"
```

**Path(`path`)** `matcher`

Match exact path

```yaml theme={null}
rule: "Path(`/api/users`)"
```

**PathPrefix(`prefix`)** `matcher`

Match path prefix

```yaml theme={null}
rule: "PathPrefix(`/api`)"
```

**PathRegexp(`regexp`)** `matcher`

Match path using regular expression

```yaml theme={null}
rule: "PathRegexp(`^/api/v[0-9]+`)"
```

**Method(`method`)** `matcher`

Match HTTP method

```yaml theme={null}
rule: "Method(`POST`)"
```

**Header(`key`, `value`)** `matcher`

Match requests with specific header

```yaml theme={null}
rule: "Header(`Content-Type`, `application/json`)"
```

**HeaderRegexp(`key`, `regexp`)** `matcher`

Match header using regular expression

```yaml theme={null}
rule: "HeaderRegexp(`Content-Type`, `^application/(json|yaml)$`)"
```

**Query(`key`, `value`)** `matcher`

Match query parameter

```yaml theme={null}
rule: "Query(`version`, `v2`)"
```

**ClientIP(`ip`)** `matcher`

Match client IP address or CIDR range

```yaml theme={null}
rule: "ClientIP(`192.168.1.0/24`)"
```

### Combining Rules

Use logical operators to create complex rules:

```yaml AND Operator theme={null}
rule: "Host(`example.com`) && Path(`/api`)"
```

```yaml OR Operator theme={null}
rule: "Host(`example.com`) || Host(`example.org`)"
```

```yaml NOT Operator theme={null}
rule: "Host(`example.com`) && !Path(`/admin`)"
```

```yaml Parentheses for Grouping theme={null}
rule: "Host(`example.com`) && (Path(`/api`) || Path(`/v2`))"
```

```yaml Complex Example theme={null}
rule: "(Host(`api.example.com`) || Host(`api.example.org`)) && PathPrefix(`/v2`) && !Method(`DELETE`)"
```

### Rule Examples

**Domain Routing**

```yaml theme={null}
http:
  routers:
    # Route by domain
    blog:
      rule: "Host(`blog.example.com`)"
      service: blog-service
    
    # Route subdomains with regex
    api:
      rule: "HostRegexp(`^api-[a-z]+\\.example\\.com$`)"
      service: api-service
    
    # Route multiple domains
    main:
      rule: "Host(`example.com`) || Host(`www.example.com`)"
      service: main-service
```

**Path Routing**

```yaml theme={null}
http:
  routers:
    # API v1 routes
    api-v1:
      rule: "PathPrefix(`/api/v1`)"
      service: api-v1-service
    
    # API v2 routes
    api-v2:
      rule: "PathPrefix(`/api/v2`)"
      service: api-v2-service
    
    # Static files
    static:
      rule: "PathRegexp(`\\.(js|css|png|jpg|svg)$`)"
      service: cdn-service
```

**Header Routing**

```yaml theme={null}
http:
  routers:
    # Route by content type
    json-api:
      rule: "Header(`Content-Type`, `application/json`) && PathPrefix(`/api`)"
      service: json-service
    
    # Route by custom header
    mobile:
      rule: "Header(`X-Client-Type`, `mobile`)"
      service: mobile-service
    
    # Route by API version header
    versioned:
      rule: "HeaderRegexp(`X-API-Version`, `^v[2-3]$`)"
      service: new-api-service
```

## Priority

Routers are evaluated by priority. Higher priority routers are checked first.

**YAML**

```yaml theme={null}
http:
  routers:
    specific:
      rule: "Host(`api.example.com`) && Path(`/users/123`)"
      service: specific-service
      priority: 100
    
    general:
      rule: "Host(`api.example.com`)"
      service: general-service
      priority: 1
```

**TOML**

```toml theme={null}
[http.routers.specific]
  rule = "Host(`api.example.com`) && Path(`/users/123`)"
  service = "specific-service"
  priority = 100

[http.routers.general]
  rule = "Host(`api.example.com`)"
  service = "general-service"
  priority = 1
```

> [!NOTE]
>
> By default, priority equals the length of the rule. Longer rules have higher priority.

## Middlewares

Attach middlewares to process requests before forwarding to services:

**YAML**

```yaml theme={null}
http:
  routers:
    secured-api:
      rule: "Host(`api.example.com`)"
      service: api-service
      middlewares:
        - auth
        - rate-limit
        - compress
  
  middlewares:
    auth:
      basicAuth:
        users:
          - "admin:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
    
    rate-limit:
      rateLimit:
        average: 100
        burst: 50
    
    compress:
      compress: {}
```

**TOML**

```toml theme={null}
[http.routers.secured-api]
  rule = "Host(`api.example.com`)"
  service = "api-service"
  middlewares = ["auth", "rate-limit", "compress"]

[http.middlewares.auth.basicAuth]
  users = ["admin:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"]

[http.middlewares.rate-limit.rateLimit]
  average = 100
  burst = 50

[http.middlewares.compress]
  [http.middlewares.compress.compress]
```

> [!NOTE]
>
> Middlewares are applied in the order they appear in the list.

## TLS Configuration

### Basic TLS

Enable TLS termination:

**YAML**

```yaml theme={null}
http:
  routers:
    secure:
      rule: "Host(`example.com`)"
      service: web-service
      entryPoints:
        - websecure
      tls: {}
```

**TOML**

```toml theme={null}
[http.routers.secure]
  rule = "Host(`example.com`)"
  service = "web-service"
  entryPoints = ["websecure"]
  [http.routers.secure.tls]
```

### Automatic Certificate Resolution

**YAML**

```yaml theme={null}
http:
  routers:
    secure:
      rule: "Host(`example.com`)"
      service: web-service
      tls:
        certResolver: letsencrypt
        domains:
          - main: "example.com"
            sans:
              - "*.example.com"
```

**TOML**

```toml theme={null}
[http.routers.secure]
  rule = "Host(`example.com`)"
  service = "web-service"
  [http.routers.secure.tls]
    certResolver = "letsencrypt"
    [[http.routers.secure.tls.domains]]
      main = "example.com"
      sans = ["*.example.com"]
```

> [!WARNING]
>
> Wildcard certificates require DNS-01 challenge. HTTP-01 challenge only works for single domains.

## TCP Routers

TCP routers handle non-HTTP TCP connections:

**YAML**

```yaml theme={null}
tcp:
  routers:
    postgres:
      rule: "HostSNI(`db.example.com`)"
      service: postgres-service
      entryPoints:
        - postgres
      tls:
        certResolver: letsencrypt
```

**TOML**

```toml theme={null}
[tcp.routers.postgres]
  rule = "HostSNI(`db.example.com`)"
  service = "postgres-service"
  entryPoints = ["postgres"]
  [tcp.routers.postgres.tls]
    certResolver = "letsencrypt"
```

### TCP Router Rules

**HostSNI(`domain`)** `matcher`

Match Server Name Indication

```yaml theme={null}
rule: "HostSNI(`example.com`)"
```

**HostSNI(`*`)** `matcher`

Match all non-TLS connections

```yaml theme={null}
rule: "HostSNI(`*`)"
```

**ClientIP(`ip`)** `matcher`

Match client IP

```yaml theme={null}
rule: "ClientIP(`192.168.1.0/24`)"
```

### TLS Passthrough

Forward TLS connections without decryption:

**YAML**

```yaml theme={null}
tcp:
  routers:
    secure-backend:
      rule: "HostSNI(`backend.example.com`)"
      service: backend-service
      tls:
        passthrough: true
```

**TOML**

```toml theme={null}
[tcp.routers.secure-backend]
  rule = "HostSNI(`backend.example.com`)"
  service = "backend-service"
  [tcp.routers.secure-backend.tls]
    passthrough = true
```

## Complete Example

**YAML**

```yaml theme={null}
http:
  routers:
    # Main website
    web:
      rule: "Host(`example.com`) || Host(`www.example.com`)"
      service: web-service
      entryPoints:
        - websecure
      middlewares:
        - redirect-www
        - compress
      tls:
        certResolver: letsencrypt
    
    # API with authentication
    api:
      rule: "Host(`api.example.com`) && PathPrefix(`/v2`)"
      service: api-service
      priority: 10
      middlewares:
        - api-auth
        - rate-limit
      tls:
        certResolver: letsencrypt
    
    # Admin panel (IP restricted)
    admin:
      rule: "Host(`admin.example.com`) && ClientIP(`192.168.1.0/24`)"
      service: admin-service
      middlewares:
        - admin-auth
      tls:
        certResolver: letsencrypt
  
  middlewares:
    redirect-www:
      redirectRegex:
        regex: "^https://example\\.com/(.*)"
        replacement: "https://www.example.com/${1}"
    
    api-auth:
      basicAuth:
        users:
          - "api:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
    
    admin-auth:
      basicAuth:
        users:
          - "admin:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
    
    rate-limit:
      rateLimit:
        average: 100
        burst: 50
    
    compress:
      compress: {}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.