homelab/traefik
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

New Routing Reference Documentation

Browse source
This commit is contained in:
Sheddy 2025-03-10 14:28:06 +00:00 • committed by GitHub
parent 3c99135bf9
commit b7170df2c3
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
65 changed files with 12109 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

112
docs/content/reference/routing-configuration/http/load-balancing/serverstransport.md Normal file
View file

@ -0,0 +1,112 @@
---
title: "ServersTransport"
description: "ServersTransport allows configuring the connection between Traefik and the HTTP servers."
---
ServersTransport allows you to configure the transport between Traefik and your HTTP servers.
## Configuration Example
Declare the serversTransport:
```yaml tab="Structured (YAML)"
http:
serversTransports:
mytransport:
serverName: "myhost"
certificates:
- "/path/to/cert1.pem"
- "/path/to/cert2.pem"
insecureSkipVerify: true
rootcas:
- "/path/to/rootca1.pem"
- "/path/to/rootca2.pem"
maxIdleConnsPerHost: 100
disableHTTP2: true
peerCertURI: "spiffe://example.org/peer"
forwardingTimeouts:
dialTimeout: "30s"
responseHeaderTimeout: "10s"
idleConnTimeout: "60s"
readIdleTimeout: "5s"
pingTimeout: "15s"
spiffe:
ids:
- "spiffe://example.org/id1"
- "spiffe://example.org/id2"
trustDomain: "example.org"
```
```toml tab="Structured (TOML)"
[http.serversTransports.mytransport]
serverName = "myhost"
certificates = ["/path/to/cert1.pem", "/path/to/cert2.pem"]
insecureSkipVerify = true
rootcas = ["/path/to/rootca1.pem", "/path/to/rootca2.pem"]
maxIdleConnsPerHost = 100
disableHTTP2 = true
peerCertURI = "spiffe://example.org/peer"
[http.serversTransports.mytransport.forwardingTimeouts]
dialTimeout = "30s"
responseHeaderTimeout = "10s"
idleConnTimeout = "60s"
readIdleTimeout = "5s"
pingTimeout = "15s"
[http.serversTransports.mytransport.spiffe]
ids = ["spiffe://example.org/id1", "spiffe://example.org/id2"]
trustDomain = "example.org"
```
Attach the serversTransport to a service:
```yaml tab="Structured (YAML)"
## Dynamic configuration
http:
services:
Service01:
loadBalancer:
serversTransport: mytransport
```
```toml tab="Structured(TOML)"
## Dynamic configuration
[http.services]
[http.services.Service01]
[http.services.Service01.loadBalancer]
serversTransport = "mytransport"
```
```yaml tab="Labels"
labels:
- "traefik.http.services.Service01.loadBalancer.serversTransport=mytransport"
```
```json tab="Tags"
{
// ...
"Tags": [
"traefik.http.services.Service01.loadBalancer.serversTransport=mytransport"
]
}
```
## Configuration Options
| Field | Description | Default | Required |
|:------|:----------------------------------------------------------|:---------------------|:---------|
| `serverName` | Configures the server name that will be used as the SNI. | "" | No |
| `certificates` | Defines the list of certificates (as file paths, or data bytes) that will be set as client certificates for mTLS. | [] | No |
| `insecureSkipVerify` | Controls whether the server's certificate chain and host name is verified. | false | No |
| `rootcas` | Set of root certificate authorities to use when verifying server certificates. (for mTLS connections). | [] | No |
| `maxIdleConnsPerHost` | Maximum idle (keep-alive) connections to keep per-host. | 200 | No |
| `disableHTTP2` | Disables HTTP/2 for connections with servers. | false | No |
| `peerCertURI` | Defines the URI used to match against SAN URIs during the server's certificate verification. | "" | No |
| `forwardingTimeouts.dialTimeout` | Amount of time to wait until a connection to a server can be established.<br />0 = no timeout | 30s | No |
| `forwardingTimeouts.responseHeaderTimeout` | Amount of time to wait for a server's response headers after fully writing the request (including its body, if any).<br />0 = no timeout | 0s | No |
| `forwardingTimeouts.idleConnTimeout` | Maximum amount of time an idle (keep-alive) connection will remain idle before closing itself.<br />0 = no timeout | 90s | No |
| `forwardingTimeouts.readIdleTimeout` | Defines the timeout after which a health check using ping frame will be carried out if no frame is received on the HTTP/2 connection. | 0s | No |
| `forwardingTimeouts.pingTimeout` | Defines the timeout after which the HTTP/2 connection will be closed if a response to ping is not received. | 15s | No |
| `spiffe.ids` | Defines the allowed SPIFFE IDs.<br />This takes precedence over the SPIFFE TrustDomain. | [] | No |
| `spiffe.trustDomain` | Defines the SPIFFE trust domain. | "" | No |

471
docs/content/reference/routing-configuration/http/load-balancing/service.md Normal file
View file

@ -0,0 +1,471 @@
---
title: "Traefik HTTP Services Documentation"
description: "A service is in charge of connecting incoming requests to the Servers that can handle them. Read the technical documentation."
---
## Service Load Balancer
The load balancers are able to load balance the requests between multiple instances of your programs.
Each service has a load-balancer, even if there is only one server to forward traffic to.
## Configuration Example
```yaml tab="Structured (YAML)"
http:
services:
my-service:
loadBalancer:
servers:
- url: "http://private-ip-server-1/"
weight: 2
preservePath: true
sticky:
cookie:
name: "sticky-cookie"
healthcheck:
path: "/health"
interval: "10s"
timeout: "3s"
passHostHeader: true
serversTransport: "customTransport@file"
responseForwarding:
flushInterval: "150ms"
```
```toml tab="Structured (TOML)"
[http.services]
[http.services.my-service.loadBalancer]
[[http.services.my-service.loadBalancer.servers]]
url = "http://private-ip-server-1/"
[http.services.my-service.loadBalancer.sticky.cookie]
name = "sticky-cookie"
[http.services.my-service.loadBalancer.healthcheck]
path = "/health"
interval = "10s"
timeout = "3s"
passHostHeader = true
serversTransport = "customTransport@file"
[http.services.my-service.loadBalancer.responseForwarding]
flushInterval = "150ms"
```
```yaml tab="Labels"
labels:
- "traefik.http.services.my-service.loadBalancer.servers[0].url=http://private-ip-server-1/"
- "traefik.http.services.my-service.loadBalancer.servers[0].weight=2"
- "traefik.http.services.my-service.loadBalancer.servers[0].preservePath=true"
- "traefik.http.services.my-service.loadBalancer.sticky.cookie.name=sticky-cookie"
- "traefik.http.services.my-service.loadBalancer.healthcheck.path=/health"
- "traefik.http.services.my-service.loadBalancer.healthcheck.interval=10s"
- "traefik.http.services.my-service.loadBalancer.healthcheck.timeout=3s"
- "traefik.http.services.my-service.loadBalancer.passHostHeader=true"
- "traefik.http.services.my-service.loadBalancer.serversTransport=customTransport@file"
- "traefik.http.services.my-service.loadBalancer.responseForwarding.flushInterval=150ms"
```
```json tab="Tags"
{
// ...
"Tags": [
"traefik.http.services.my-service.loadBalancer.servers[0].url=http://private-ip-server-1/",
"traefik.http.services.my-service.loadBalancer.servers[0].weight=2",
"traefik.http.services.my-service.loadBalancer.servers[0].preservePath=true",
"traefik.http.services.my-service.loadBalancer.sticky.cookie.name=sticky-cookie",
"traefik.http.services.my-service.loadBalancer.healthcheck.path=/health",
"traefik.http.services.my-service.loadBalancer.healthcheck.interval=10s",
"traefik.http.services.my-service.loadBalancer.healthcheck.timeout=3s",
"traefik.http.services.my-service.loadBalancer.passHostHeader=true",
"traefik.http.services.my-service.loadBalancer.serversTransport=customTransport@file",
"traefik.http.services.my-service.loadBalancer.responseForwarding.flushInterval=150ms"
]
}
```
### Configuration Options
| Field | Description | Required |
|----------|------------------------------------------|----------|
|`servers`| Represents individual backend instances for your service | Yes |
|`sticky`| Defines a `Set-Cookie` header is set on the initial response to let the client know which server handles the first response. | No |
|`healthcheck`| Configures health check to remove unhealthy servers from the load balancing rotation. | No |
|`passHostHeader`| Allows forwarding of the client Host header to server. By default, `passHostHeader` is true. | No |
|`serversTransport`| Allows to reference an [HTTP ServersTransport](./serverstransport.md) configuration for the communication between Traefik and your servers. If no `serversTransport` is specified, the `default@internal` will be used. | No |
| `responseForwarding` | Configures how Traefik forwards the response from the backend server to the client.| No |
| `responseForwarding.FlushInterval` | Specifies the interval in between flushes to the client while copying the response body. It is a duration in milliseconds, defaulting to 100ms. A negative value means to flush immediately after each write to the client. The `FlushInterval` is ignored when ReverseProxy recognizes a response as a streaming response; for such responses, writes are flushed to the client immediately. | No |
#### Servers
Servers represent individual backend instances for your service. The [service loadBalancer](#service-load-balancer) `servers` option lets you configure the list of instances that will handle incoming requests.
##### Configuration Options
| Field | Description | Required |
|----------|------------------------------------------|----------|
|`url`| Points to a specific instance. | Yes for File provider, No for [Docker provider](../../other-providers/docker.md) |
|`weight`| Allows for weighted load balancing on the servers. | No |
|`preservePath`| Allows to preserve the URL path. | No |
#### Health Check
The `healthcheck` option configures health check to remove unhealthy servers from the load balancing rotation. Traefik will consider HTTP(s) servers healthy as long as they return a status code to the health check request (carried out every interval) between `2XX` and `3XX`, or matching the configured status. For gRPC servers, Traefik will consider them healthy as long as they return SERVING to [gRPC health check v1 requests](https://github.com/grpc/grpc/blob/master/doc/health-checking.md).
To propagate status changes (e.g. all servers of this service are down) upwards, HealthCheck must also be enabled on the parent(s) of this service.
Below are the available options for the health check mechanism:
| Field | Description | Default | Required |
|----------|------------------------------------------|----------|--------|
|`path`| Defines the server URL path for the health check endpoint. | "" | Yes |
|`scheme`| Replaces the server URL scheme for the health check endpoint. | | No |
|`mode`| If defined to `grpc`, will use the gRPC health check protocol to probe the server. | http | No |
|`hostname`| Defines the value of hostname in the Host header of the health check request. | "" | No |
|`port`| Replaces the server URL port for the health check endpoint. | | No |
|`interval`| Defines the frequency of the health check calls. | 30s | No |
|`timeout`| Defines the maximum duration Traefik will wait for a health check request before considering the server unhealthy. | 5s | No |
|`headers`| Defines custom headers to be sent to the health check endpoint. | | No |
|`followRedirects`| Defines whether redirects should be followed during the health check calls. | true | No |
|`hostname`| Defines the value of hostname in the Host header of the health check request. | "" | No |
|`method`| Defines the HTTP method that will be used while connecting to the endpoint. | GET | No |
|`status`| Defines the expected HTTP status code of the response to the health check request. | | No |
## Weighted Round Robin (WRR)
The WRR is able to load balance the requests between multiple services based on weights.
This strategy is only available to load balance between services and not between servers.
!!! info "Supported Providers"
This strategy can be defined currently with the [File](../../../install-configuration/providers/others/file.md) or [IngressRoute](../../../install-configuration/providers/kubernetes/kubernetes-ingress.md) providers. To load balance between servers based on weights, the Load Balancer service should be used instead.
```yaml tab="Structured (YAML)"
## Dynamic configuration
http:
services:
app:
weighted:
services:
- name: appv1
weight: 3
- name: appv2
weight: 1
appv1:
loadBalancer:
servers:
- url: "http://private-ip-server-1/"
appv2:
loadBalancer:
servers:
- url: "http://private-ip-server-2/"
```
```toml tab="Structured (TOML)"
## Dynamic configuration
[http.services]
[http.services.app]
[[http.services.app.weighted.services]]
name = "appv1"
weight = 3
[[http.services.app.weighted.services]]
name = "appv2"
weight = 1
[http.services.appv1]
[http.services.appv1.loadBalancer]
[[http.services.appv1.loadBalancer.servers]]
url = "http://private-ip-server-1/"
[http.services.appv2]
[http.services.appv2.loadBalancer]
[[http.services.appv2.loadBalancer.servers]]
url = "http://private-ip-server-2/"
```
### Health Check
HealthCheck enables automatic self-healthcheck for this service, i.e. whenever one of its children is reported as down, this service becomes aware of it, and takes it into account (i.e. it ignores the down child) when running the load-balancing algorithm. In addition, if the parent of this service also has HealthCheck enabled, this service reports to its parent any status change.
!!! note "Behavior"
If HealthCheck is enabled for a given service and any of its descendants does not have it enabled, the creation of the service will fail.
HealthCheck on Weighted services can be defined currently only with the [File provider](../../../install-configuration/providers/others/file.md).
```yaml tab="Structured (YAML)"
## Dynamic configuration
http:
services:
app:
weighted:
healthCheck: {}
services:
- name: appv1
weight: 3
- name: appv2
weight: 1
appv1:
loadBalancer:
healthCheck:
path: /status
interval: 10s
timeout: 3s
servers:
- url: "http://private-ip-server-1/"
appv2:
loadBalancer:
healthCheck:
path: /status
interval: 10s
timeout: 3s
servers:
- url: "http://private-ip-server-2/"
```
```toml tab="Structured (TOML)"
## Dynamic configuration
[http.services]
[http.services.app]
[http.services.app.weighted.healthCheck]
[[http.services.app.weighted.services]]
name = "appv1"
weight = 3
[[http.services.app.weighted.services]]
name = "appv2"
weight = 1
[http.services.appv1]
[http.services.appv1.loadBalancer]
[http.services.appv1.loadBalancer.healthCheck]
path = "/health"
interval = "10s"
timeout = "3s"
[[http.services.appv1.loadBalancer.servers]]
url = "http://private-ip-server-1/"
[http.services.appv2]
[http.services.appv2.loadBalancer]
[http.services.appv2.loadBalancer.healthCheck]
path = "/health"
interval = "10s"
timeout = "3s"
[[http.services.appv2.loadBalancer.servers]]
url = "http://private-ip-server-2/"
```
## Mirroring
The mirroring is able to mirror requests sent to a service to other services. Please note that by default the whole request is buffered in memory while it is being mirrored. See the `maxBodySize` option in the example below for how to modify this behaviour. You can also omit the request body by setting the `mirrorBody` option to false.
!!! info "Supported Providers"
This strategy can be defined currently with the [File](../../../install-configuration/providers/others/file.md) or [IngressRoute](../../../install-configuration/providers/kubernetes/kubernetes-ingress.md) providers.
```yaml tab="Structured (YAML)"
## Dynamic configuration
http:
services:
mirrored-api:
mirroring:
service: appv1
# mirrorBody defines whether the request body should be mirrored.
# Default value is true.
mirrorBody: false
# maxBodySize is the maximum size allowed for the body of the request.
# If the body is larger, the request is not mirrored.
# Default value is -1, which means unlimited size.
maxBodySize: 1024
mirrors:
- name: appv2
percent: 10
appv1:
loadBalancer:
servers:
- url: "http://private-ip-server-1/"
appv2:
loadBalancer:
servers:
- url: "http://private-ip-server-2/
```
```toml tab="Structured (TOML)"
## Dynamic configuration
[http.services]
[http.services.mirrored-api]
[http.services.mirrored-api.mirroring]
service = "appv1"
# maxBodySize is the maximum size in bytes allowed for the body of the request.
# If the body is larger, the request is not mirrored.
# Default value is -1, which means unlimited size.
maxBodySize = 1024
# mirrorBody defines whether the request body should be mirrored.
# Default value is true.
mirrorBody = false
[[http.services.mirrored-api.mirroring.mirrors]]
name = "appv2"
percent = 10
[http.services.appv1]
[http.services.appv1.loadBalancer]
[[http.services.appv1.loadBalancer.servers]]
url = "http://private-ip-server-1/"
[http.services.appv2]
[http.services.appv2.loadBalancer]
[[http.services.appv2.loadBalancer.servers]]
url = "http://private-ip-server-2/"
```
### Health Check
HealthCheck enables automatic self-healthcheck for this service, i.e. if the main handler of the service becomes unreachable, the information is propagated upwards to its parent.
!!! note "Behavior"
If HealthCheck is enabled for a given service and any of its descendants does not have it enabled, the creation of the service will fail.
HealthCheck on Mirroring services can be defined currently only with the [File provider](../../../install-configuration/providers/others/file.md).
```yaml tab="Structured (YAML)"
## Dynamic configuration
http:
services:
mirrored-api:
mirroring:
healthCheck: {}
service: appv1
mirrors:
- name: appv2
percent: 10
appv1:
loadBalancer:
healthCheck:
path: /status
interval: 10s
timeout: 3s
servers:
- url: "http://private-ip-server-1/"
appv2:
loadBalancer:
servers:
- url: "http://private-ip-server-2/"
```
```toml tab="Structured (TOML)"
## Dynamic configuration
[http.services]
[http.services.mirrored-api]
[http.services.mirrored-api.mirroring]
service = "appv1"
[http.services.mirrored-api.mirroring.healthCheck]
[[http.services.mirrored-api.mirroring.mirrors]]
name = "appv2"
percent = 10
[http.services.appv1]
[http.services.appv1.loadBalancer]
[http.services.appv1.loadBalancer.healthCheck]
path = "/health"
interval = "10s"
timeout = "3s"
[[http.services.appv1.loadBalancer.servers]]
url = "http://private-ip-server-1/"
[http.services.appv2]
[http.services.appv2.loadBalancer]
[http.services.appv1.loadBalancer.healthCheck]
path = "/health"
interval = "10s"
timeout = "3s"
[[http.services.appv2.loadBalancer.servers]]
url = "http://private-ip-server-2/"
```
## Failover
A failover service job is to forward all requests to a fallback service when the main service becomes unreachable.
!!! info "Relation to HealthCheck"
The failover service relies on the HealthCheck system to get notified when its main service becomes unreachable, which means HealthCheck needs to be enabled and functional on the main service. However, HealthCheck does not need to be enabled on the failover service itself for it to be functional. It is only required in order to propagate upwards the information when the failover itself becomes down (i.e. both its main and its fallback are down too).
!!! info "Supported Provider"
This strategy can currently only be defined with the [File](../../../install-configuration/providers/others/file.md) provider.
### HealthCheck
HealthCheck enables automatic self-healthcheck for this service, i.e. if the main and the fallback services become unreachable, the information is propagated upwards to its parent.
!!! note "Behavior"
If HealthCheck is enabled for a given service and any of its descendants does not have it enabled, the creation of the service will fail.
HealthCheck on a Failover service can be defined currently only with the [File provider](../../../install-configuration/providers/others/file.md).
```yaml tab="Structured (YAML)"
## Dynamic configuration
http:
services:
app:
failover:
healthCheck: {}
service: main
fallback: backup
main:
loadBalancer:
healthCheck:
path: /status
interval: 10s
timeout: 3s
servers:
- url: "http://private-ip-server-1/"
backup:
loadBalancer:
healthCheck:
path: /status
interval: 10s
timeout: 3s
servers:
- url: "http://private-ip-server-2/"
```
```toml tab="Structured (TOML)"
## Dynamic configuration
[http.services]
[http.services.app]
[http.services.app.failover.healthCheck]
[http.services.app.failover]
service = "main"
fallback = "backup"
[http.services.main]
[http.services.main.loadBalancer]
[http.services.main.loadBalancer.healthCheck]
path = "/health"
interval = "10s"
timeout = "3s"
[[http.services.main.loadBalancer.servers]]
url = "http://private-ip-server-1/"
[http.services.backup]
[http.services.backup.loadBalancer]
[http.services.backup.loadBalancer.healthCheck]
path = "/health"
interval = "10s"
timeout = "3s"
[[http.services.backup.loadBalancer.servers]]
url = "http://private-ip-server-2/"
```

59
docs/content/reference/routing-configuration/http/middlewares/addprefix.md Normal file
View file

@ -0,0 +1,59 @@
---
title: "Traefik AddPrefix Documentation"
description: "Learn how to implement the HTTP AddPrefix middleware in Traefik Proxy to updates request paths before being forwarded. Read the technical documentation."
---
![AddPrefix](../../../../assets/img/middleware/addprefix.png)
The `addPrefix` middleware updates the path of a request before forwarding it.
## Configuration Examples
```yaml tab="Structured (YAML)"
# Prefixing with /foo
http:
middlewares:
add-foo:
addPrefix:
prefix: "/foo"
```
```toml tab="Structured (TOML)"
# Prefixing with /foo
[http.middlewares]
[http.middlewares.add-foo.addPrefix]
prefix = "/foo"
```
```yaml tab="Labels"
# Prefixing with /foo
labels:
- "traefik.http.middlewares.add-foo.addprefix.prefix=/foo"
```
```json tab="Tags"
// Prefixing with /foo
{
// ...
"Tags": [
"traefik.http.middlewares.add-foo.addprefix.prefix=/foo"
]
}
```
```yaml tab="Kubernetes"
# Prefixing with /foo
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: add-foo
spec:
addPrefix:
prefix: /foo
```
## Configuration Options
| Field | Description | Default | Required |
|:-----------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------|
| `prefix` | String to add **before** the current path in the requested URL. It should include a leading slash (`/`). | "" | Yes |

97
docs/content/reference/routing-configuration/http/middlewares/basicauth.md Normal file
View file

@ -0,0 +1,97 @@
---
title: "Traefik BasicAuth Documentation"
description: "The HTTP basic authentication (BasicAuth) middleware in Traefik Proxy restricts access to your Services to known users. Read the technical documentation."
---
![BasicAuth](../../../../assets/img/middleware/basicauth.png)
The `basicAuth` middleware grants access to services to authorized users only.
## Configuration Examples
```yaml tab="Structured (YAML)"
# Declaring the user list
http:
middlewares:
test-auth:
basicAuth:
users:
- "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
- "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"
```
```toml tab="Structured (TOML)"
# Declaring the user list
[http.middlewares]
[http.middlewares.test-auth.basicAuth]
users = [
"test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
"test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0",
]
```
```yaml tab="Labels"
# Declaring the user list
#
# Note: when used in docker-compose.yml all dollar signs in the hash need to be doubled for escaping.
# To create user:password pair, it's possible to use this command:
# echo $(htpasswd -nB user) | sed -e s/\\$/\\$\\$/g
#
# Also, note that dollar signs should NOT be doubled when not evaluated (e.g. Ansible docker_container module).
labels:
- "traefik.http.middlewares.test-auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"
```
```json tab="Tags"
{
// ...
"Tags": [
"traefik.http.middlewares.test-auth.basicauth.users=test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/,test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"
]
}
```
```yaml tab="Kubernetes"
# Declaring the user list
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-auth
spec:
basicAuth:
secret: secretName
```
## Configuration Options
| Field | Description | Default | Required |
|:-----------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------|
| `users` | Array of authorized users. Each user must be declared using the `name:hashed-password` format. (More information [here](#users))| "" | No |
| `usersFile` | Path to an external file that contains the authorized users for the middleware. <br />The file content is a list of `name:hashed-password`. (More information [here](#usersfile)) | "" | No |
| `realm` | Allow customizing the realm for the authentication.| "traefik" | No |
| `headerField` | Allow defining a header field to store the authenticated user.| "" | No |
| `removeHeader` | Allow removing the authorization header before forwarding the request to your service. | false | No |
### Passwords format
Passwords must be hashed using MD5, SHA1, or BCrypt.
Use `htpasswd` to generate the passwords.
### users & usersFile
- If both `users` and `usersFile` are provided, they are merged. The contents of `usersFile` have precedence over the values in users.
- Because referencing a file path isn’t feasible on Kubernetes, the `users` & `usersFile` field isn’t used in Kubernetes IngressRoute. Instead, use the `secret` field.
#### Kubernetes Secrets
The option `users` supports Kubernetes secrets.
!!! note "Kubernetes `kubernetes.io/basic-auth` secret type"
Kubernetes supports a special `kubernetes.io/basic-auth` secret type.
This secret must contain two keys: `username` and `password`.
Please note that these keys are not hashed or encrypted in any way, and therefore is less secure than other methods.
You can find more information on the [Kubernetes Basic Authentication Secret Documentation](https://kubernetes.io/docs/concepts/configuration/secret/#basic-authentication-secret)
{!traefik-for-business-applications.md!}

76
docs/content/reference/routing-configuration/http/middlewares/buffering.md Normal file
View file

@ -0,0 +1,76 @@
---
title: "Traefik Buffering Documentation"
description: "The HTTP buffering middleware in Traefik Proxy limits the size of requests that can be forwarded to Services. Read the technical documentation."
---
![Buffering](../../../../assets/img/middleware/buffering.png)
The `buffering` middleware limits the size of requests that can be forwarded to services.
With buffering, Traefik reads the entire request into memory (possibly buffering large requests into disk), and rejects requests that are over a specified size limit.
This can help services avoid large amounts of data (`multipart/form-data` for example), and can minimize the time spent sending data to a Service
## Configuration Examples
```yaml tab="Structured (YAML)"
# Sets the maximum request body to 2MB
http:
middlewares:
limit:
buffering:
maxRequestBodyBytes: 2000000
```
```toml tab="Structured (TOML)"
# Sets the maximum request body to 2MB
[http.middlewares]
[http.middlewares.limit.buffering]
maxRequestBodyBytes = 2000000
```
```yaml tab="Labels"
# Sets the maximum request body to 2MB
labels:
- "traefik.http.middlewares.limit.buffering.maxRequestBodyBytes=2000000"
```
```json tab="Tags"
// Sets the maximum request body to 2MB
{
// ...
"Tags": [
"traefik.http.middlewares.test-auth.basicauth.users=test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/,test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"
]
}
```
```yaml tab="Kubernetes"
# Sets the maximum request body to 2MB
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: limit
spec:
buffering:
maxRequestBodyBytes: 2000000
```
## Configuration Options
| Field | Description | Default | Required |
|:------|:------------|:--------|:---------|
| `maxRequestBodyBytes` | Maximum allowed body size for the request (in bytes). <br /> If the request exceeds the allowed size, it is not forwarded to the Service, and the client gets a `413` (Request Entity Too Large) response. | 0 | No |
| `memRequestBodyBytes` | Threshold (in bytes) from which the request will be buffered on disk instead of in memory with the `memRequestBodyBytes` option.| 1048576 | No |
| `maxResponseBodyBytes` | Maximum allowed response size from the Service (in bytes). <br /> If the response exceeds the allowed size, it is not forwarded to the client. The client gets a `500` (Internal Server Error) response instead. | 0 | No |
| `memResponseBodyBytes` | Threshold (in bytes) from which the response will be buffered on disk instead of in memory with the `memResponseBodyBytes` option.| 1048576 | No |
| `retryExpression` | Replay the request using `retryExpression`.<br /> More information [here](#retryexpression). | "" | No |
### retryExpression
The retry expression is defined as a logical combination of the functions below with the operators AND (`&&`) and OR (`||`).
At least one function is required:
- `Attempts()` number of attempts (the first one counts).
- `ResponseCode()` response code of the Service.
- `IsNetworkError()` whether the response code is related to networking error.

171
docs/content/reference/routing-configuration/http/middlewares/chain.md Normal file
View file

@ -0,0 +1,171 @@
---
title: "Traefik Chain Middleware Documentation"
description: "The HTTP chain middleware lets you define reusable combinations of other middleware, to reuse the same groups. Read the technical documentation."
---
The `chain` middleware enables you to define reusable combinations of other pieces of middleware.
It makes it effortless to reuse the same groups.
## Configuration Example
Below is an example of a Chain containing `AllowList`, `BasicAuth`, and `RedirectScheme`.
```yaml tab="Structured (YAML)"
# ...
http:
routers:
router1:
service: service1
middlewares:
- secured
rule: "Host(`mydomain`)"
middlewares:
secured:
chain:
middlewares:
- https-only
- known-ips
- auth-users
auth-users:
basicAuth:
users:
- "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
https-only:
redirectScheme:
scheme: https
known-ips:
ipAllowList:
sourceRange:
- "192.168.1.7"
- "127.0.0.1/32"
services:
service1:
loadBalancer:
servers:
- url: "http://127.0.0.1:80"
```
```toml tab="Structured (TOML)"
# ...
[http.routers]
[http.routers.router1]
service = "service1"
middlewares = ["secured"]
rule = "Host(`mydomain`)"
[http.middlewares]
[http.middlewares.secured.chain]
middlewares = ["https-only", "known-ips", "auth-users"]
[http.middlewares.auth-users.basicAuth]
users = ["test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"]
[http.middlewares.https-only.redirectScheme]
scheme = "https"
[http.middlewares.known-ips.ipAllowList]
sourceRange = ["192.168.1.7", "127.0.0.1/32"]
[http.services]
[http.services.service1]
[http.services.service1.loadBalancer]
[[http.services.service1.loadBalancer.servers]]
url = "http://127.0.0.1:80"
```
```yaml tab="Labels"
labels:
- "traefik.http.routers.router1.service=service1"
- "traefik.http.routers.router1.middlewares=secured"
- "traefik.http.routers.router1.rule=Host(`mydomain`)"
- "traefik.http.middlewares.secured.chain.middlewares=https-only,known-ips,auth-users"
- "traefik.http.middlewares.auth-users.basicauth.users=test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
- "traefik.http.middlewares.https-only.redirectscheme.scheme=https"
- "traefik.http.middlewares.known-ips.ipallowlist.sourceRange=192.168.1.7,127.0.0.1/32"
- "traefik.http.services.service1.loadbalancer.server.port=80"
```
```json tab="Tags"
{
// ...
"Tags": [
"traefik.http.routers.router1.service=service1",
"traefik.http.routers.router1.middlewares=secured",
"traefik.http.routers.router1.rule=Host(`mydomain`)",
"traefik.http.middlewares.secured.chain.middlewares=https-only,known-ips,auth-users",
"traefik.http.middlewares.auth-users.basicauth.users=test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
"traefik.http.middlewares.https-only.redirectscheme.scheme=https",
"traefik.http.middlewares.known-ips.ipallowlist.sourceRange=192.168.1.7,127.0.0.1/32",
"traefik.http.services.service1.loadbalancer.server.port=80"
]
}
```
```yaml tab="Kubernetes"
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: test
namespace: default
spec:
entryPoints:
- web
routes:
- match: Host(`mydomain`)
kind: Rule
services:
- name: whoami
port: 80
middlewares:
- name: secured
---
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: secured
spec:
chain:
middlewares:
- name: https-only
- name: known-ips
- name: auth-users
---
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: auth-users
spec:
basicAuth:
users:
- test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/
---
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: https-only
spec:
redirectScheme:
scheme: https
---
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: known-ips
spec:
ipAllowList:
sourceRange:
- 192.168.1.7
- 127.0.0.1/32
```
## Configuration Options
| Field | Description | Default | Required |
|:------|:------------|:--------|:---------|
| `middlewares` | List of middlewares to chain.<br /> The middlewares have to be in the same namespace as the `chain` middleware. | [] | Yes |

143
docs/content/reference/routing-configuration/http/middlewares/circuitbreaker.md Normal file
View file

@ -0,0 +1,143 @@
---
title: "Traefik CircuitBreaker Documentation"
description: "The HTTP circuit breaker in Traefik Proxy prevents stacking requests to unhealthy Services, resulting in cascading failures. Read the technical documentation."
---
![Circuit Breaker](../../../../assets/img/middleware/circuitbreaker.png)
The HTTP circuit breaker prevents stacking requests to unhealthy Services, resulting in cascading failures.
When your system is healthy, the circuit is closed (normal operations).
When your system becomes unhealthy, the circuit opens, and the requests are no longer forwarded, but instead are handled by a fallback mechanism.
To assess if your system is healthy, the circuit breaker constantly monitors the services.
The circuit breaker only analyzes what happens *after* its position within the middleware chain. What happens *before* has no impact on its state.
Each router gets its own instance of a given circuit breaker.
One circuit breaker instance can be open while the other remains closed: their state is not shared.
This is the expected behavior, we want you to be able to define what makes a service healthy without having to declare a circuit breaker for each route.
## Configuration Examples
```yaml tab="Structured (YAML)"
# Latency Check
http:
middlewares:
latency-check:
circuitBreaker:
expression: "LatencyAtQuantileMS(50.0) > 100"
```
```toml tab="Structured (TOML)"
# Latency Check
[http.middlewares]
[http.middlewares.latency-check.circuitBreaker]
expression = "LatencyAtQuantileMS(50.0) > 100"
```
```yaml tab="Labels"
# Latency Check
labels:
- "traefik.http.middlewares.latency-check.circuitbreaker.expression=LatencyAtQuantileMS(50.0) > 100"
```
```json tab="Tags"
{
//..
"Tags" : [
"traefik.http.middlewares.latency-check.circuitbreaker.expression=LatencyAtQuantileMS(50.0) > 100"
]
}
```
```yaml tab="Kubernetes"
# Latency Check
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: latency-check
spec:
circuitBreaker:
expression: LatencyAtQuantileMS(50.0) > 100
```
## Configuration Options
| Field | Description | Default | Required |
|:------|:------------|:--------|:---------|
| `expression` | Condition to open the circuit breaker and applies the fallback mechanism instead of calling your services.<br />More information [here](#expression) | 100ms | No |
| `checkPeriod` | The interval between successive checks of the circuit breaker condition (when in standby state). | 100ms | No |
| `fallbackDuration` | The duration for which the circuit breaker will wait before trying to recover (from a tripped state). | 10s | No |
| `recoveryDuration` | The duration for which the circuit breaker will try to recover (as soon as it is in recovering state). | 10s | No |
| `responseCode` | The status code that the circuit breaker will return while it is in the open state. | 503 | No |
### expression
The `expression` option can check three different metrics:
| Metrics | Description | Example |
|:------|:------------|:--------|
| `NetworkErrorRatio` | The network error ratio to open the circuit breaker. | `NetworkErrorRatio() > 0.30` opens the circuit breaker at a 30% ratio of network errors |
| `ResponseCodeRatio` | The status code ratio to open the circuit breaker.<br />More information [below](#responsecoderatio) | `ResponseCodeRatio(500, 600, 0, 600) > 0.25` opens the circuit breaker if 25% of the requests returned a 5XX status (amongst the request that returned a status code from 0 to 5XX) |
| `LatencyAtQuantileMS` | The latency at a quantile in milliseconds to open the circuit breaker when a given proportion of your requests become too slow.<br /> Only floating point number (with the trailing .0) for the quantile value. | `LatencyAtQuantileMS(50.0) > 100` opens the circuit breaker when the median latency (quantile 50) reaches 100ms. |
#### ResponseCodeRatio
- It accepts four parameters, `from`, `to`, `dividedByFrom`, `dividedByTo`.
- The operation that will be computed is sum(`to` -> `from`) / sum (`dividedByFrom` -> `dividedByTo`). If sum (`dividedByFrom` -> `dividedByTo`) equals 0, then `ResponseCodeRatio` returns 0.
- `from` is inclusive, `to` is exclusive.
#### Using Multiple Metrics
You can combine multiple metrics using operators in your `expression`.
Supported operators are:
- AND (`&&`)
- OR (`||`)
For example, `ResponseCodeRatio(500, 600, 0, 600) > 0.30 || NetworkErrorRatio() > 0.10` triggers the circuit breaker when 30% of the requests return a 5XX status code, or when the ratio of network errors reaches 10%.
#### Operators
Here is the list of supported operators:
- Greater than (`>`)
- Greater or equal than (`>=`)
- Lesser than (`<`)
- Lesser or equal than (`<=`)
- Equal (`==`)
- Not Equal (`!=`)
### Fallback mechanism
The fallback mechanism returns a `HTTP 503 Service Unavailable` to the client instead of calling the target service.
This behavior cannot be configured.
## State
There are three possible states for your circuit breaker:
- `Closed` (your service operates normally).
- `Open` (the fallback mechanism takes over your service).
- `Recovering` (the circuit breaker tries to resume normal operations by progressively sending requests to your service).
### Closed
While the circuit is closed, the circuit breaker only collects metrics to analyze the behavior of the requests.
At specified intervals (`checkPeriod`), the circuit breaker evaluates `expression` to decide if its state must change.
### Open
While open, the fallback mechanism takes over the normal service calls for a duration of `FallbackDuration`.
The fallback mechanism returns a `HTTP 503` (or `ResponseCode`) to the client.
After this duration, it enters the recovering state.
### Recovering
While recovering, the circuit breaker sends linearly increasing amounts of requests to your service (for `RecoveryDuration`).
If your service fails during recovery, the circuit breaker opens again.
If the service operates normally during the entire recovery duration, then the circuit breaker closes.

80
docs/content/reference/routing-configuration/http/middlewares/compress.md Normal file
View file

@ -0,0 +1,80 @@
---
title: "Traefik Compress Documentation"
description: "Traefik Proxy's HTTP middleware lets you compress responses before sending them to the client. Read the technical documentation."
---
The `compress` middleware compresses response. It supports Gzip, Brotli and Zstandard compression
## Configuration Examples
```yaml tab="Structured (YAML)"
# Enable compression
http:
middlewares:
test-compress:
compress: {}
```
```toml tab="Structured (TOML)"
# Enable compression
[http.middlewares]
[http.middlewares.test-compress.compress]
```
```yaml tab="Labels"
# Enable compression
labels:
- "traefik.http.middlewares.test-compress.compress=true"
```
```json tab="Tags"
// Enable compression
{
//...
"Tags": [
"traefik.http.middlewares.test-compress.compress=true"
]
}
```
```yaml tab="Kubernetes"
# Enable compression
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-compress
spec:
compress: {}
```
## Configuration Options
| Field | Description | Default | Required |
|:-----------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------|
|`excludedContentTypes` | List of content types to compare the `Content-Type` header of the incoming requests and responses before compressing. <br /> The responses with content types defined in `excludedContentTypes` are not compressed. <br /> Content types are compared in a case-insensitive, whitespace-ignored manner. <br /> **The `excludedContentTypes` and `includedContentTypes` options are mutually exclusive.** | "" | No |
|`defaultEncoding` | specifies the default encoding if the `Accept-Encoding` header is not in the request or contains a wildcard (`*`). | "" | No |
|`encodings` | Specifies the list of supported compression encodings. At least one encoding value must be specified, and valid entries are `zstd` (Zstandard), `br` (Brotli), and `gzip` (Gzip). The order of the list also sets the priority, the top entry has the highest priority. | zstd, br, gzip | No |
| `includedContentTypes` | List of content types to compare the `Content-Type` header of the responses before compressing. <br /> The responses with content types defined in `includedContentTypes` are compressed. <br /> Content types are compared in a case-insensitive, whitespace-ignored manner.<br /> **The `excludedContentTypes` and `includedContentTypes` options are mutually exclusive.** | "" | No |
| `minResponseBodyBytes` | `Minimum amount of bytes a response body must have to be compressed. <br />Responses smaller than the specified values will **not** be compressed. | 1024 | No |
## Compression activation
The activation of compression, and the compression method choice rely (among other things) on the request's `Accept-Encoding` header.
Responses are compressed when the following criteria are all met:
- The `Accept-Encoding` request header contains `gzip`, `*`, and/or `br`, and/or `zstd` with or without [quality values](https://developer.mozilla.org/en-US/docs/Glossary/Quality_values).
If the `Accept-Encoding` request header is absent, the response won't be encoded.
If it is present, but its value is the empty string, then compression is turned off.
- The response is not already compressed, that is the `Content-Encoding` response header is not already set.
- The response`Content-Type` header is not one among the `excludedContentTypes` options, or is one among the `includedContentTypes` options.
- The response body is larger than the configured minimum amount of bytes(option `minResponseBodyBytes`) (default is `1024`).
## Empty Content-Type Header
If the `Content-Type` header is not defined, or empty, the compress middleware will automatically [detect](https://mimesniff.spec.whatwg.org/) a content type.
It will also set the `Content-Type` header according to the detected MIME type.
## GRPC application
Note that `application/grpc` is never compressed.

53
docs/content/reference/routing-configuration/http/middlewares/contenttype.md Normal file
View file

@ -0,0 +1,53 @@
---
title: "Traefik ContentType Documentation"
description: "Traefik Proxy's HTTP middleware automatically sets the `Content-Type` header value when it is not set by the backend. Read the technical documentation."
---
The `contentType` middleware sets the `Content-Type` header value to the media type detected from the response content,
when it is not set by the backend.
!!! info
The `contentType` middleware only applies when Traefik detects the MIME type. If any middleware (such as Headers or Compress) sets the `contentType` header at any point in the chain, the `contentType` middleware has no effect.
## Configuration Examples
```yaml tab="Structured (YAML)"
# Enable auto-detection
http:
middlewares:
autodetect:
contentType: {}
```
```toml tab="Structured (TOML)"
# Enable auto-detection
[http.middlewares]
[http.middlewares.autodetect.contentType]
```
```yaml tab="Labels"
# Enable auto-detection
labels:
- "traefik.http.middlewares.autodetect.contenttype=true"
```
```json tab="Tags"
// Enable auto-detection
{
// ...
"Tags": [
"traefik.http.middlewares.autodetect.contenttype=true"
]
}
```
```yaml tab="Kubernetes"
# Enable auto-detection
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: autodetect
spec:
contentType: {}
```

87
docs/content/reference/routing-configuration/http/middlewares/digestauth.md Normal file
View file

@ -0,0 +1,87 @@
---
title: "Traefik DigestAuth Documentation"
description: "Traefik Proxy's HTTP DigestAuth middleware restricts access to your services to known users. Read the technical documentation."
---
![DigestAuth](../../../../assets/img/middleware/digestauth.png)
The `DigestAuth` middleware grants access to services to authorized users only.
## Configuration Examples
```yaml tab="Structured (YAML)"
# Declaring the user list
http:
middlewares:
test-auth:
digestAuth:
users:
- "test:traefik:a2688e031edb4be6a3797f3882655c05"
- "test2:traefik:518845800f9e2bfb1f1f740ec24f074e"
```
```toml tab="Structured (TOML)"
# Declaring the user list
[http.middlewares]
[http.middlewares.test-auth.digestAuth]
users = [
"test:traefik:a2688e031edb4be6a3797f3882655c05",
"test2:traefik:518845800f9e2bfb1f1f740ec24f074e",
]
```
```yaml tab="Labels"
# Declaring the user list
labels:
- "traefik.http.middlewares.test-auth.digestauth.users=test:traefik:a2688e031edb4be6a3797f3882655c05,test2:traefik:518845800f9e2bfb1f1f740ec24f074e"
```
```json tab="Tags"
// Declaring the user list
{
//...
"Tags" : [
"traefik.http.middlewares.test-auth.digestauth.users=test:traefik:a2688e031edb4be6a3797f3882655c05,test2:traefik:518845800f9e2bfb1f1f740ec24f074e"
]
}
```
```yaml tab="Kubernetes"
# Declaring the user list
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-auth
spec:
digestAuth:
secret: userssecret
```
## Configuration Options
| Field | Description | Default | Required |
|:-----------|:---------------------------------------------------------------------------------|:--------|:---------|
| `users` | Array of authorized users. Each user must be declared using the `name:realm:encoded-password` format.<br /> The option `users` supports Kubernetes secrets.<br />(More information [here](#users--usersfile))| [] | No |
| `usersFile` | Path to an external file that contains the authorized users for the middleware. <br />The file content is a list of `name:realm:encoded-password`. (More information [here](#users--usersfile)) | "" | No |
| `realm` | Allow customizing the realm for the authentication.| "traefik" | No |
| `headerField` | Allow defining a header field to store the authenticated user.| "" | No |
| `removeHeader` | Allow removing the authorization header before forwarding the request to your service. | false | No |
### Passwords format
Passwords must be hashed using MD5, SHA1, or BCrypt.
Use `htpasswd` to generate the passwords.
### users & usersFile
- If both `users` and `usersFile` are provided, they are merged. The contents of `usersFile` have precedence over the values in users.
- Because referencing a file path isn’t feasible on Kubernetes, the `users` & `usersFile` field isn’t used in Kubernetes IngressRoute. Instead, use the `secret` field.
### Kubernetes Secrets
On Kubernetes, you don’t use the `users` or `usersFile` fields. Instead, you reference a Kubernetes secret using the `secret` field in your Middleware resource. This secret can be one of two types:
- `kubernetes.io/basic-auth secret`: This secret type contains two keys—`username` and `password`—but is generally suited for a smaller number of users. Please note that these keys are not hashed or encrypted in any way, and therefore is less secure than the other method.
- Opaque secret with a users field: Here, the secret contains a single string field (often called `users`) where each line represents a user. This approach allows you to store multiple users in one secret.
{!traefik-for-business-applications.md!}

108
docs/content/reference/routing-configuration/http/middlewares/errorpages.md Normal file
View file

@ -0,0 +1,108 @@
---
title: "Traefik Errors Documentation"
description: "In Traefik Proxy, the Errors middleware returns custom pages according to configured ranges of HTTP Status codes. Read the technical documentation."
---
![Errors](../../../../assets/img/middleware/errorpages.png)
The `errors` middleware returns a custom page in lieu of the default, according to configured ranges of HTTP Status codes.
## Configuration Examples
```yaml tab="Structured (YAML)"
# Dynamic Custom Error Page for 5XX Status Code excluding 502 and 504
http:
middlewares:
test-errors:
errors:
status:
- "500"
- "501"
- "503"
- "505-599"
service: error-handler-service
query: "/{status}.html"
services:
# ... definition of the error-handler-service
```
```toml tab="Structured (TOML)"
# Dynamic Custom Error Page for 5XX Status Code excluding 502 and 504
[http.middlewares]
[http.middlewares.test-errors.errors]
status = ["500","501","503","505-599"]
service = "error-handler-service"
query = "/{status}.html"
[http.services]
# ... definition of the error-handler-service
```
```yaml tab="Labels"
# Dynamic Custom Error Page for 5XX Status Code
labels:
- "traefik.http.middlewares.test-errors.errors.status=500,501,503,505-599"
- "traefik.http.middlewares.test-errors.errors.service=error-handler-service"
- "traefik.http.middlewares.test-errors.errors.query=/{status}.html"
```
```json tab="Tags"
// Dynamic Custom Error Page for 5XX Status Code excluding 502 and 504
{
// ...
"Tags": [
"traefik.http.middlewares.test-errors.errors.status=500,501,503,505-599",
"traefik.http.middlewares.test-errors.errors.service=error-handler-service",
"traefik.http.middlewares.test-errors.errors.query=/{status}.html"
]
}
```
```yaml tab="Kubernetes"
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-errors
spec:
errors:
status:
- "500"
- "501"
- "503"
- "505-599"
query: /{status}.html
service:
name: error-handler-service
port: 80
```
## Configuration Options
| Field | Description | Default | Required |
|:-----------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------|
| `status` | Defines which status or range of statuses should result in an error page.<br/> The status code ranges are inclusive (`505-599` will trigger with every code between `505` and `599`, `505` and `599` included).<br /> You can define either a status code as a number (`500`), as multiple comma-separated numbers (`500,502`), as ranges by separating two codes with a dash (`505-599`), or a combination of the two (`404,418,505-599`). | [] | No |
| `service` | The service that will serve the new requested error page.<br /> More information [here](#service-and-hostheader). | "" | No |
| `query` | The URL for the error page (hosted by `service`).<br /> More information [here](#query) | "" | No |
### service and HostHeader
By default, the client `Host` header value is forwarded to the configured error service.
To forward the `Host` value corresponding to the configured error service URL,
the [`passHostHeader`](../../../../routing/services/index.md#pass-host-header) option must be set to `false`.
!!!info "Kubernetes"
When specifying a service in Kubernetes (e.g., in an IngressRoute), you need to reference the `name`, `namespace`, and `port` of your Kubernetes Service resource. For example, `my-service.my-namespace@kubernetescrd` (or `my-service.my-namespace@kubernetescrd:80`) ensures that requests go to the correct service and port.
### query
There are multiple variables that can be placed in the `query` option to insert values in the URL.
The table below lists all the available variables and their associated values.
| Variable | Value |
|------------|------------------------------------------------------------------|
| `{status}` | The response status code. |
| `{url}` | The [escaped](https://pkg.go.dev/net/url#QueryEscape) request URL.|

98
docs/content/reference/routing-configuration/http/middlewares/forwardauth.md Normal file
View file

@ -0,0 +1,98 @@
---
title: "Traefik ForwardAuth Documentation"
description: "In Traefik Proxy, the HTTP ForwardAuth middleware delegates authentication to an external Service. Read the technical documentation."
---
![AuthForward](../../../../assets/img/middleware/authforward.png)
The `forwardAuth` middleware delegates authentication to an external service.
If the service answers with a 2XX code, access is granted, and the original request is performed.
Otherwise, the response from the authentication server is returned.
## Configuration Example
```yaml tab="Structured (YAML)"
# Forward authentication to example.com
http:
middlewares:
test-auth:
forwardAuth:
address: "https://example.com/auth"
```
```toml tab="Structured (TOML)"
# Forward authentication to example.com
[http.middlewares]
[http.middlewares.test-auth.forwardAuth]
address = "https://example.com/auth"
```
```yaml tab="Labels"
# Forward authentication to example.com
labels:
- "traefik.http.middlewares.test-auth.forwardauth.address=https://example.com/auth"
```
```json tab="Tags"
// Forward authentication to example.com
{
"Tags" : [
"traefik.http.middlewares.test-auth.forwardauth.address=https://example.com/auth"
]
}
```
```yaml tab="Kubernetes"
# Forward authentication to example.com
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-auth
spec:
forwardAuth:
address: https://example.com/auth
```
## Configuration Options
| Field | Description | Default | Required |
|:-----------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------|
| `address` | Authentication server address. | "" | Yes |
| `trustForwardHeader` | Trust all `X-Forwarded-*` headers. | false | No |
| `authResponseHeaders` | List of headers to copy from the authentication server response and set on forwarded request, replacing any existing conflicting headers. | [] | No |
| `authResponseHeadersRegex` | Regex to match by the headers to copy from the authentication server response and set on forwarded request, after stripping all headers that match the regex.<br /> More information [here](#authresponseheadersregex). | "" | No |
| `authRequestHeaders` | List of the headers to copy from the request to the authentication server. <br /> It allows filtering headers that should not be passed to the authentication server. <br /> If not set or empty, then all request headers are passed. | [] | No |
| `addAuthCookiesToResponse` | List of cookies to copy from the authentication server to the response, replacing any existing conflicting cookie from the forwarded response.<br /> Please note that all backend cookies matching the configured list will not be added to the response. | [] | No |
| `forwardBody` | Sets the `forwardBody` option to `true` to send the Body. As body is read inside Traefik before forwarding, this breaks streaming. | false | No |
| `maxBodySize` | Set the `maxBodySize` to limit the body size in bytes. If body is bigger than this, it returns a 401 (unauthorized). | -1 | No |
| `headerField` | Defines a header field to store the authenticated user. | "" | No |
| `preserveLocationHeader` | Defines whether to forward the Location header to the client as is or prefix it with the domain name of the authentication server. | false | No |
| `PreserveRequestMethod` | Defines whether to preserve the original request method while forwarding the request to the authentication server. | false | No |
| `tls.ca` | Sets the path to the certificate authority used for the secured connection to the authentication server, it defaults to the system bundle. | "" | No |
| `tls.cert` | Sets the path to the public certificate used for the secure connection to the authentication server. When using this option, setting the key option is required. | "" | No |
| `tls.key` | Sets the path to the private key used for the secure connection to the authentication server. When using this option, setting the `cert` option is required. | "" | No |
| `tls.caSecret` | Defines the secret that contains the certificate authority used for the secured connection to the authentication server, it defaults to the system bundle. **This option is only available for the Kubernetes CRD**. | | No |
| `tls.certSecret` | Defines the secret that contains both the private and public certificates used for the secure connection to the authentication server. **This option is only available for the Kubernetes CRD**. | | No |
| `tls.insecureSkipVerify` | During TLS connections, if this option is set to `true`, the authentication server will accept any certificate presented by the server regardless of the host names it covers. | false | No |
### authResponseHeadersRegex
It allows partial matching of the regular expression against the header key.
The start of string (`^`) and end of string (`$`) anchors should be used to ensure a full match against the header key.
Regular expressions and replacements can be tested using online tools such as [Go Playground](https://play.golang.org/p/mWU9p-wk2ru) or the [Regex101](https://regex101.com/r/58sIgx/2).
## Forward-Request Headers
The following request properties are provided to the forward-auth target endpoint as `X-Forwarded-` headers.
| Property | Forward-Request Header |
|-------------------|------------------------|
| HTTP Method | X-Forwarded-Method |
| Protocol | X-Forwarded-Proto |
| Host | X-Forwarded-Host |
| Request URI | X-Forwarded-Uri |
| Source IP-Address | X-Forwarded-For |
{!traefik-for-business-applications.md!}

67
docs/content/reference/routing-configuration/http/middlewares/grpcweb.md Normal file
View file

@ -0,0 +1,67 @@
---
title: "Traefik GrpcWeb Documentation"
description: "In Traefik Proxy's HTTP middleware, GrpcWeb converts a gRPC Web requests to HTTP/2 gRPC requests. Read the technical documentation."
---
The `grpcWeb` middleware converts gRPC Web requests to HTTP/2 gRPC requests before forwarding them to the backends.
!!! tip
Please note, that Traefik needs to communicate using gRPC with the backends (h2c or HTTP/2 over TLS).
Check out the [gRPC](../../../../user-guides/grpc.md) user guide for more details.
## Configuration Examples
```yaml tab="Structured (YAML)"
http:
middlewares:
test-grpcweb:
grpcWeb:
allowOrigins:
- "*"
```
```toml tab="Structured (TOML)"
[http.middlewares]
[http.middlewares.test-grpcweb.grpcWeb]
allowOrigins = ["*"]
```
```yaml tab="Labels"
labels:
- "traefik.http.middlewares.test-grpcweb.grpcweb.allowOrigins=*"
```
```json tab="Tags"
{
//...
"Tags" : [
"traefik.http.middlewares.test-grpcweb.grpcWeb.allowOrigins=*"
]
}
```
```yaml tab="Kubernetes"
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-grpcweb
spec:
grpcWeb:
allowOrigins:
- "*"
```
## Configuration Options
| Field | Description | Default | Required |
|:-----------------------------|:------------------------------------------|:--------|:---------|
| `allowOrigins` | List of allowed origins. <br /> A wildcard origin `*` can also be configured to match all requests.<br /> More information [here](#alloworigins). | [] | No |
### allowOrigins
More information including how to use the settings can be found at:
- [Mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin)
- [w3](https://fetch.spec.whatwg.org/#http-access-control-allow-origin)
- [IETF](https://tools.ietf.org/html/rfc6454#section-7.1)

328
docs/content/reference/routing-configuration/http/middlewares/headers.md Normal file
View file

@ -0,0 +1,328 @@
---
title: "Traefik Headers Documentation"
description: "In Traefik Proxy, the HTTP headers middleware manages the headers of requests and responses. Read the technical documentation."
---
![Headers](../../../../assets/img/middleware/headers.png)
The Headers middleware manages the headers of requests and responses.
By default, the following headers are automatically added when proxying requests:
| Property | HTTP Header |
|---------------------------|----------------------------|
| Client's IP | X-Forwarded-For, X-Real-Ip |
| Host | X-Forwarded-Host |
| Port | X-Forwarded-Port |
| Protocol | X-Forwarded-Proto |
| Proxy Server's Hostname | X-Forwarded-Server |
## Configuration Examples
### Adding Headers to the Request and the Response
The following example adds the `X-Script-Name` header to the proxied request and the `X-Custom-Response-Header` header to the response
```yaml tab="Structured (YAML)"
http:
middlewares:
testHeader:
headers:
customRequestHeaders:
X-Script-Name: "test"
customResponseHeaders:
X-Custom-Response-Header: "value"
```
```toml tab="Structured (TOML)"
[http.middlewares]
[http.middlewares.testHeader.headers]
[http.middlewares.testHeader.headers.customRequestHeaders]
X-Script-Name = "test"
[http.middlewares.testHeader.headers.customResponseHeaders]
X-Custom-Response-Header = "value"
```
```yaml tab="Labels"
labels:
- "traefik.http.middlewares.testHeader.headers.customrequestheaders.X-Script-Name=test"
- "traefik.http.middlewares.testHeader.headers.customresponseheaders.X-Custom-Response-Header=value"
```
```json tab="Tags"
{
//...
"Tags": [
"traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test",
"traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header=value"
]
}
```
```yaml tab="Kubernetes"
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-header
spec:
headers:
customRequestHeaders:
X-Script-Name: "test"
customResponseHeaders:
X-Custom-Response-Header: "value"
```
### Adding and Removing Headers
In the following example, requests are proxied with an extra `X-Script-Name` header while their `X-Custom-Request-Header` header gets stripped,
and responses are stripped of their `X-Custom-Response-Header` header.
```yaml tab="Structured (YAML)"
http:
middlewares:
testHeader:
headers:
customRequestHeaders:
X-Script-Name: "test" # Adds
X-Custom-Request-Header: "" # Removes
customResponseHeaders:
X-Custom-Response-Header: "" # Removes
```
```toml tab="Structured (TOML)"
[http.middlewares]
[http.middlewares.testHeader.headers]
[http.middlewares.testHeader.headers.customRequestHeaders]
X-Script-Name = "test" # Adds
X-Custom-Request-Header = "" # Removes
[http.middlewares.testHeader.headers.customResponseHeaders]
X-Custom-Response-Header = "" # Removes
```
```yaml tab="Labels"
labels:
- "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test"
- "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Custom-Request-Header="
- "traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header="
```
```json tab="Tags"
{
"Tags" : [
"traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test",
"traefik.http.middlewares.testheader.headers.customrequestheaders.X-Custom-Request-Header=",
"traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header="
]
}
```
```yaml tab="Kubernetes"
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-header
spec:
headers:
customRequestHeaders:
X-Script-Name: "test" # Adds
X-Custom-Request-Header: "" # Removes
customResponseHeaders:
X-Custom-Response-Header: "" # Removes
```
### Using Security Headers
Security-related headers (HSTS headers, Browser XSS filter, etc) can be managed similarly to custom headers as shown above.
This functionality makes it possible to easily use security features by adding headers.
```yaml tab="Structured (YAML)"
http:
middlewares:
testHeader:
headers:
frameDeny: true
browserXssFilter: true
```
```toml tab="Structured (TOML)"
[http.middlewares]
[http.middlewares.testHeader.headers]
frameDeny = true
browserXssFilter = true
```
```yaml tab="Labels"
labels:
- "traefik.http.middlewares.testHeader.headers.framedeny=true"
- "traefik.http.middlewares.testHeader.headers.browserxssfilter=true"
```
```json tab="Tags"
{
"Tags" : [
"traefik.http.middlewares.testheader.headers.framedeny=true",
"traefik.http.middlewares.testheader.headers.browserxssfilter=true"
]
}
```
```yaml tab="Kubernetes"
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-header
spec:
headers:
frameDeny: true
browserXssFilter: true
```
### CORS Headers
CORS (Cross-Origin Resource Sharing) headers can be added and configured in a manner similar to the custom headers above.
This functionality allows for more advanced security features to quickly be set.
If CORS headers are set, then the middleware does not pass preflight requests to any service,
instead the response will be generated and sent back to the client directly.
Please note that the example below is by no means authoritative or exhaustive,
and should not be used as is for production.
```yaml tab="Structured (YAML)"
http:
middlewares:
testHeader:
headers:
accessControlAllowMethods:
- GET
- OPTIONS
- PUT
accessControlAllowHeaders: "*"
accessControlAllowOriginList:
- https://foo.bar.org
- https://example.org
accessControlMaxAge: 100
addVaryHeader: true
```
```toml tab="Structured (TOML)"
[http.middlewares]
[http.middlewares.testHeader.headers]
accessControlAllowMethods = ["GET", "OPTIONS", "PUT"]
accessControlAllowHeaders = [ "*" ]
accessControlAllowOriginList = ["https://foo.bar.org","https://example.org"]
accessControlMaxAge = 100
addVaryHeader = true
```
```yaml tab="Labels"
labels:
- "traefik.http.middlewares.testheader.headers.accesscontrolallowmethods=GET,OPTIONS,PUT"
- "traefik.http.middlewares.testheader.headers.accesscontrolallowheaders=*"
- "traefik.http.middlewares.testheader.headers.accesscontrolalloworiginlist=https://foo.bar.org,https://example.org"
- "traefik.http.middlewares.testheader.headers.accesscontrolmaxage=100"
- "traefik.http.middlewares.testheader.headers.addvaryheader=true"
```
```json tab="Tags"
{
"Tags" : [
"traefik.http.middlewares.testheader.headers.accesscontrolallowmethods=GET,OPTIONS,PUT",
"traefik.http.middlewares.testheader.headers.accesscontrolallowheaders=*",
"traefik.http.middlewares.testheader.headers.accesscontrolalloworiginlist=https://foo.bar.org,https://example.org",
"traefik.http.middlewares.testheader.headers.accesscontrolmaxage=100",
"traefik.http.middlewares.testheader.headers.addvaryheader=true"
]
}
```
```yaml tab="Kubernetes"
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-header
spec:
headers:
accessControlAllowMethods:
- "GET"
- "OPTIONS"
- "PUT"
accessControlAllowHeaders:
- "*"
accessControlAllowOriginList:
- "https://foo.bar.org"
- "https://example.org"
accessControlMaxAge: 100
addVaryHeader: true
```
## Configuration Options
!!! warning
Custom headers will overwrite existing headers if they have identical names.
!!! note ""
The detailed documentation for security headers can be found in [unrolled/secure](https://github.com/unrolled/secure#available-options).
| Field | Description | Default | Required |
| ----------------------------- | ------------------------------------------------- | --------- | -------- |
| `customRequestHeaders` | Lists the header names and values for requests. | [] | No |
| `customResponseHeaders` | Lists the header names and values for responses. | [] | No |
| `accessControlAllowCredentials` | Indicates if the request can include user credentials.| false | No |
| `accessControlAllowHeaders` | Specifies allowed request header names. | [] | No |
| `accessControlAllowMethods` | Specifies allowed request methods. | [] | No |
| `accessControlAllowOriginList` | Specifies allowed origins. More information [here](#accesscontrolalloworiginlist) | [] | No |
| `accessControlAllowOriginListRegex` | Allows origins matching regex. More information [here](#accesscontrolalloworiginlistregex) | [] | No |
| `accessControlExposeHeaders` | Specifies which headers are safe to expose to the API of a CORS API specification. | [] | No |
| `accessControlMaxAge` | Time (in seconds) to cache preflight requests. | 0 | No |
| `addVaryHeader` | Used in conjunction with `accessControlAllowOriginList` to determine whether the `Vary` header should be added or modified to demonstrate that server responses can differ based on the value of the origin header. | false | No |
| `allowedHosts` | Lists allowed domain names. | [] | No |
| `hostsProxyHeaders` | Specifies header keys for proxied hostname. | [] | No |
| `sslProxyHeaders` | Defines a set of header keys with associated values that would indicate a valid HTTPS request. It can be useful when using other proxies (example: `"X-Forwarded-Proto": "https"`). | {} | No |
| `stsSeconds` | Max age for `Strict-Transport-Security` header. | 0 | No |
| `stsIncludeSubdomains` | If set to `true`, the `includeSubDomains` directive is appended to the `Strict-Transport-Security` header. | false | No |
| `stsPreload` | Adds preload flag to STS header. | false | No |
| `forceSTSHeader` | Adds STS header for HTTP connections. | false | No |
| `frameDeny` | Set `frameDeny` to `true` to add the `X-Frame-Options` header with the value of `DENY`. | false | No |
| `customFrameOptionsValue` | allows the `X-Frame-Options` header value to be set with a custom value. This overrides the `FrameDeny` option. | "" | No |
| `contentTypeNosniff` | Set `contentTypeNosniff` to true to add the `X-Content-Type-Options` header with the value `nosniff`. | false | No |
| `browserXssFilter` | Set `browserXssFilter` to true to add the `X-XSS-Protection` header with the value `1; mode=block`. | false | No |
| `customBrowserXSSValue` | allows the `X-XSS-Protection` header value to be set with a custom value. This overrides the `BrowserXssFilter` option. | false | No |
| `contentSecurityPolicy` | allows the `Content-Security-Policy` header value to be set with a custom value. | false | No |
| `contentSecurityPolicyReportOnly` | allows the `Content-Security-Policy-Report-Only` header value to be set with a custom value. | "" | No |
| `publicKey` | Implements HPKP for certificate pinning. | "" | No |
| `referrerPolicy` | Controls forwarding of `Referer` header. | "" | No |
| `permissionsPolicy` | allows sites to control browser features. | "" | No |
| `isDevelopment` | Set `true` when developing to mitigate the unwanted effects of the `AllowedHosts`, SSL, and STS options. Usually testing takes place using HTTP, not HTTPS, and on `localhost`, not your production domain. | false | No |
### `accessControlAllowOriginList`
The `accessControlAllowOriginList` indicates whether a resource can be shared by returning different values.
A wildcard origin `*` can also be configured, and matches all requests.
If this value is set by a backend service, it will be overwritten by Traefik.
This value can contain a list of allowed origins.
More information including how to use the settings can be found at:
- [Mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin)
- [w3](https://fetch.spec.whatwg.org/#http-access-control-allow-origin)
- [IETF](https://tools.ietf.org/html/rfc6454#section-7.1)
Traefik no longer supports the `null` value, as it is [no longer recommended as a return value](https://w3c.github.io/webappsec-cors-for-developers/#avoid-returning-access-control-allow-origin-null).
### `accessControlAllowOriginListRegex`
The `accessControlAllowOriginListRegex` option is the counterpart of the `accessControlAllowOriginList` option with regular expressions instead of origin values.
It allows all origins that contain any match of a regular expression in the `accessControlAllowOriginList`.
!!! tip
Regular expressions and replacements can be tested using online tools such as [Go Playground](https://play.golang.org/p/mWU9p-wk2ru) or the [Regex101](https://regex101.com/r/58sIgx/2).
When defining a regular expression within YAML, any escaped character needs to be escaped twice: `example\.com` needs to be written as `example\\.com`.
{!traefik-for-business-applications.md!}

115
docs/content/reference/routing-configuration/http/middlewares/inflightreq.md Normal file
View file

@ -0,0 +1,115 @@
---
title: "Traefik InFlightReq Documentation"
description: "Traefik Proxy's HTTP middleware lets you limit the number of simultaneous in-flight requests. Read the technical documentation."
---
The `inFlightReq` middleware proactively prevents services from being overwhelmed with high load.
## Configuration Examples
```yaml tab="Structured (YAML)"
# Limiting to 10 simultaneous connections
http:
middlewares:
test-inflightreq:
inFlightReq:
amount: 10
```
```toml tab="Structured (TOML)"
# Limiting to 10 simultaneous connections
[http.middlewares]
[http.middlewares.test-inflightreq.inFlightReq]
amount = 10
```
```yaml tab="Labels"
labels:
- "traefik.http.middlewares.test-inflightreq.inflightreq.amount=10"
```
```json tab="Consul Catalog"
// Limiting to 10 simultaneous connections
{
"Tags" : [
"traefik.http.middlewares.test-inflightreq.inflightreq.amount=10"
]
}
```
```yaml tab="Kubernetes"
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-inflightreq
spec:
inFlightReq:
amount: 10
```
## Configuration Options
<!-- markdownlint-disable MD013 -->
| Field | Description | Default | Required |
|:-----------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------|
| `amount` | The `amount` option defines the maximum amount of allowed simultaneous in-flight request. <br /> The middleware responds with `HTTP 429 Too Many Requests` if there are already `amount` requests in progress (based on the same `sourceCriterion` strategy). | 0 | No |
| `sourceCriterion.requestHost` | Whether to consider the request host as the source.<br /> More information about `sourceCriterion`[here](#sourcecriterion). | false | No |
| `sourceCriterion.requestHeaderName` | Name of the header used to group incoming requests.<br /> More information about `sourceCriterion`[here](#sourcecriterion). | "" | No |
| `sourceCriterion.ipStrategy.depth` | Depth position of the IP to select in the `X-Forwarded-For` header (starting from the right).<br />0 means no depth.<br />If greater than the total number of IPs in `X-Forwarded-For`, then the client IP is empty<br />If higher than 0, the `excludedIPs` options is not evaluated.<br /> More information about [`sourceCriterion`](#sourcecriterion), [`ipStrategy](#ipstrategy), and [`depth`](#example-of-depth--x-forwarded-for) below. | 0 | No |
| `sourceCriterion.ipStrategy.excludedIPs` | Allows Traefik to scan the `X-Forwarded-For` header and select the first IP not in the list.<br />If `depth` is specified, `excludedIPs` is ignored.<br /> More information about [`sourceCriterion`](#sourcecriterion), [`ipStrategy](#ipstrategy), and [`excludedIPs`](#example-of-excludedips--x-forwarded-for) below. | | No |
| `sourceCriterion.ipStrategy.ipv6Subnet` | If `ipv6Subnet` is provided and the selected IP is IPv6, the IP is transformed into the first IP of the subnet it belongs to. <br /> More information about [`sourceCriterion`](#sourcecriterion), [`ipStrategy.ipv6Subnet`](#ipstrategyipv6subnet), and [`excludedIPs`](#example-of-excludedips--x-forwarded-for) below. | | No |
### sourceCriterion
The `sourceCriterion` option defines what criterion is used to group requests as originating from a common source.
If several strategies are defined at the same time, an error will be raised.
If none are set, the default is to use the `requestHost`.
### ipStrategy
The `ipStrategy` option defines three parameters that configures how Traefik determines the client IP: `depth`, `excludedIPs` and `ipv6Subnet`.
As a middleware, `inFlightReq` happens before the actual proxying to the backend takes place.
In addition, the previous network hop only gets appended to `X-Forwarded-For` during the last stages of proxying, that is after it has already passed through the middleware.
Therefore, during InFlightReq, as the previous network hop is not yet present in `X-Forwarded-For`, it cannot be used and/or relied upon.
### `ipStrategy.ipv6Subnet`
This strategy applies to `Depth` and `RemoteAddr` strategy only.
If `ipv6Subnet` is provided and the selected IP is IPv6, the IP is transformed into the first IP of the subnet it belongs to.
This is useful for grouping IPv6 addresses into subnets to prevent bypassing this middleware by obtaining a new IPv6.
- `ipv6Subnet` is ignored if its value is outside 0-128 interval
#### Example of ipv6Subnet
If `ipv6Subnet` is provided, the IP is transformed in the following way.
| IP | ipv6Subnet | clientIP |
|---------------------------|--------------|-----------------------|
| `"::abcd:1111:2222:3333"` | `64` | `"::0:0:0:0"` |
| `"::abcd:1111:2222:3333"` | `80` | `"::abcd:0:0:0:0"` |
| `"::abcd:1111:2222:3333"` | `96` | `"::abcd:1111:0:0:0"` |
### Example of Depth & X-Forwarded-For
If `depth` is set to 2, and the request `X-Forwarded-For` header is `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` then the "real" client IP is `"10.0.0.1"` (at depth 4) but the IP used as the criterion is `"12.0.0.1"` (`depth=2`).
| X-Forwarded-For | depth | clientIP |
|-----------------------------------------|---------|--------------|
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `1` | `"13.0.0.1"` |
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `3` | `"11.0.0.1"` |
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `5` | `""` |
### Example of ExcludedIPs & X-Forwarded-For
| X-Forwarded-For | excludedIPs | clientIP |
|-----------------------------------------|-----------------------|--------------|
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `"12.0.0.1,13.0.0.1"` | `"11.0.0.1"` |
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `"15.0.0.1,13.0.0.1"` | `"12.0.0.1"` |
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `"10.0.0.1,13.0.0.1"` | `"12.0.0.1"` |
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `"15.0.0.1,16.0.0.1"` | `"13.0.0.1"` |
| `"10.0.0.1,11.0.0.1"` | `"10.0.0.1,11.0.0.1"` | `""` |

120
docs/content/reference/routing-configuration/http/middlewares/ipallowlist.md Normal file
View file

@ -0,0 +1,120 @@
---
title: "Traefik HTTP Middlewares IPAllowList"
description: "Learn how to use IPAllowList in HTTP middleware for limiting clients to specific IPs in Traefik Proxy. Read the technical documentation."
---
`ipAllowList` accepts / refuses requests based on the client IP.
## Configuration Example
```yaml tab="Structured (YAML)"
# Accepts request from defined IP
http:
middlewares:
test-ipallowlist:
ipAllowList:
sourceRange:
- "127.0.0.1/32"
- "192.168.1.7"
```
```toml tab="Structured (TOML)"
# Accepts request from defined IP
[http.middlewares]
[http.middlewares.test-ipallowlist.ipAllowList]
sourceRange = ["127.0.0.1/32", "192.168.1.7"]
```
```yaml tab="Labels"
# Accepts request from defined IP
labels:
- "traefik.http.middlewares.test-ipallowlist.ipallowlist.sourcerange=127.0.0.1/32, 192.168.1.7"
```
```json tab="Tags"
// Accepts request from defined IP
{
"Tags" : [
"traefik.http.middlewares.test-ipallowlist.ipallowlist.sourcerange=127.0.0.1/32, 192.168.1.7"
]
}
```
```yaml tab="Kubernetes"
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-ipallowlist
spec:
ipAllowList:
sourceRange:
- 127.0.0.1/32
- 192.168.1.7
```
## Configuration Options
| Field | Description | Default | Required |
|:-----------|:------------------------------|:--------|:---------|
| `sourceRange` | List of allowed IPs (or ranges of allowed IPs by using CIDR notation). | | Yes |
| `ipStrategy.depth` | Depth position of the IP to select in the `X-Forwarded-For` header (starting from the right).<br />0 means no depth.<br />If greater than the total number of IPs in `X-Forwarded-For`, then the client IP is empty<br /> If higher than 0, the `excludedIPs` options is not evaluated.<br /> More information about [`ipStrategy](#ipstrategy), and [`depth`](#example-of-depth--x-forwarded-for) below. | 0 | No |
| `ipStrategy.excludedIPs` | Allows Traefik to scan the `X-Forwarded-For` header and select the first IP not in the list.<br />If `depth` is specified, `excludedIPs` is ignored.<br /> More information about [`ipStrategy](#ipstrategy), and [`excludedIPs`](#example-of-excludedips--x-forwarded-for) below. | | No |
| `ipStrategy.ipv6Subnet` | If `ipv6Subnet` is provided and the selected IP is IPv6, the IP is transformed into the first IP of the subnet it belongs to. <br />More information about [`ipStrategy.ipv6Subnet`](#ipstrategyipv6subnet), and [`excludedIPs`](#example-of-excludedips--x-forwarded-for) below. | | No |
### ipStrategy
The `ipStrategy` option defines two parameters that configures how Traefik determines the client IP: `depth`, and `excludedIPs`.
If no strategy is set, the default behavior is to match `sourceRange` against the Remote address found in the request.
As a middleware, passlisting happens before the actual proxying to the backend takes place.
In addition, the previous network hop only gets appended to `X-Forwarded-For` during the last stages of proxying, that is after it has already passed through passlisting.
Therefore, during passlisting, as the previous network hop is not yet present in `X-Forwarded-For`, it cannot be matched against `sourceRange`.
#### `ipStrategy.depth`
The `depth` option tells Traefik to use the `X-Forwarded-For` header and take the IP located at the `depth` position (starting from the right).
- If `depth` is greater than the total number of IPs in `X-Forwarded-For`, then the client IP will be empty.
- `depth` is ignored if its value is less than or equal to 0.
If `ipStrategy.ipv6Subnet` is provided and the selected IP is IPv6, the IP is transformed into the first IP of the subnet it belongs to.
### `ipStrategy.ipv6Subnet`
This strategy applies to `Depth` and `RemoteAddr` strategy only.
If `ipv6Subnet` is provided and the selected IP is IPv6, the IP is transformed into the first IP of the subnet it belongs to.
This is useful for grouping IPv6 addresses into subnets to prevent bypassing this middleware by obtaining a new IPv6.
- `ipv6Subnet` is ignored if its value is outside 0-128 interval
#### Example of ipv6Subnet
If `ipv6Subnet` is provided, the IP is transformed in the following way.
| IP | ipv6Subnet | clientIP |
|---------------------------|--------------|-----------------------|
| `"::abcd:1111:2222:3333"` | `64` | `"::0:0:0:0"` |
| `"::abcd:1111:2222:3333"` | `80` | `"::abcd:0:0:0:0"` |
| `"::abcd:1111:2222:3333"` | `96` | `"::abcd:1111:0:0:0"` |
### Example of Depth & X-Forwarded-For
If `depth` is set to 2, and the request `X-Forwarded-For` header is `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` then the "real" client IP is `"10.0.0.1"` (at depth 4) but the IP used as the criterion is `"12.0.0.1"` (`depth=2`).
| X-Forwarded-For | depth | clientIP |
|-----------------------------------------|---------|--------------|
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `1` | `"13.0.0.1"` |
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `3` | `"11.0.0.1"` |
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `5` | `""` |
### Example of ExcludedIPs & X-Forwarded-For
| X-Forwarded-For | excludedIPs | clientIP |
|-----------------------------------------|-----------------------|--------------|
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `"12.0.0.1,13.0.0.1"` | `"11.0.0.1"` |
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `"15.0.0.1,13.0.0.1"` | `"12.0.0.1"` |
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `"10.0.0.1,13.0.0.1"` | `"12.0.0.1"` |
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `"15.0.0.1,16.0.0.1"` | `"13.0.0.1"` |
| `"10.0.0.1,11.0.0.1"` | `"10.0.0.1,11.0.0.1"` | `""` |

51
docs/content/reference/routing-configuration/http/middlewares/overview.md Normal file
View file

@ -0,0 +1,51 @@
---
title: "Traefik Proxy Middleware Overview"
description: "There are several available middleware in Traefik Proxy used to modify requests or headers, take charge of redirections, add authentication, and so on."
---
# HTTP Middleware Overview
Attached to the routers, pieces of middleware are a means of tweaking the requests before they are sent to your service (or before the answer from the services are sent to the clients).
There are several available middlewares in Traefik, some can modify the request, the headers, some are in charge of redirections, some add authentication, and so on.
Middlewares that use the same protocol can be combined into chains to fit every scenario.
!!! warning "Provider Namespace"
Be aware of the concept of Providers Namespace described in the [Configuration Discovery](../../../install-configuration/providers/overview.md#provider-namespace) section.
It also applies to Middlewares.
## Available HTTP Middlewares
| Middleware | Purpose | Area |
|-------------------------------------------|---------------------------------------------------|-----------------------------|
| [AddPrefix](addprefix.md) | Adds a Path Prefix | Path Modifier |
| [BasicAuth](basicauth.md) | Adds Basic Authentication | Security, Authentication |
| [Buffering](buffering.md) | Buffers the request/response | Request Lifecycle |
| [Chain](chain.md) | Combines multiple pieces of middleware | Misc |
| [CircuitBreaker](circuitbreaker.md) | Prevents calling unhealthy services | Request Lifecycle |
| [Compress](compress.md) | Compresses the response | Content Modifier |
| [ContentType](contenttype.md) | Handles Content-Type auto-detection | Misc |
| [DigestAuth](digestauth.md) | Adds Digest Authentication | Security, Authentication |
| [Errors](errorpages.md) | Defines custom error pages | Request Lifecycle |
| [ForwardAuth](forwardauth.md) | Delegates Authentication | Security, Authentication |
| [GrpcWeb](grpcweb.md) | Converts gRPC Web requests to HTTP/2 gRPC requests. | Request |
| [Headers](headers.md) | Adds / Updates headers | Security |
| [IPAllowList](ipallowlist.md) | Limits the allowed client IPs | Security, Request lifecycle |
| [InFlightReq](inflightreq.md) | Limits the number of simultaneous connections | Security, Request lifecycle |
| [PassTLSClientCert](passtlsclientcert.md) | Adds Client Certificates in a Header | Security |
| [RateLimit](ratelimit.md) | Limits the call frequency | Security, Request lifecycle |
| [RedirectScheme](redirectscheme.md) | Redirects based on scheme | Request lifecycle |
| [RedirectRegex](redirectregex.md) | Redirects based on regex | Request lifecycle |
| [ReplacePath](replacepath.md) | Changes the path of the request | Path Modifier |
| [ReplacePathRegex](replacepathregex.md) | Changes the path of the request | Path Modifier |
| [Retry](retry.md) | Automatically retries in case of error | Request lifecycle |
| [StripPrefix](stripprefix.md) | Changes the path of the request | Path Modifier |
| [StripPrefixRegex](stripprefixregex.md) | Changes the path of the request | Path Modifier |
## Community Middlewares
Please take a look at the community-contributed plugins in the [plugin catalog](https://plugins.traefik.io/plugins).
{!traefik-for-business-applications.md!}

366
docs/content/reference/routing-configuration/http/middlewares/passtlsclientcert.md Normal file
View file

@ -0,0 +1,366 @@
---
title: "Traefik PassTLSClientCert Documentation"
description: "In Traefik Proxy's HTTP middleware, the PassTLSClientCert adds selected data from passed client TLS certificates to headers. Read the technical documentation."
---
The `passTLSClientCert` middleware adds the selected data from the passed client TLS certificate to a header.
## Configuration Examples
Pass the pem in the `X-Forwarded-Tls-Client-Cert` header:
```yaml tab="Structured (YAML)"
# Pass the pem in the `X-Forwarded-Tls-Client-Cert` header.
http:
middlewares:
test-passtlsclientcert:
passTLSClientCert:
pem: true
```
```toml tab="Structured (TOML)"
# Pass the pem in the `X-Forwarded-Tls-Client-Cert` header.
[http.middlewares]
[http.middlewares.test-passtlsclientcert.passTLSClientCert]
pem = true
```
```yaml tab="Labels"
# Pass the pem in the `X-Forwarded-Tls-Client-Cert` header.
labels:
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.pem=true"
```
```json tab="Tags"
// Pass the pem in the `X-Forwarded-Tls-Client-Cert` header
{
"Tags": [
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.pem=true"
]
}
```
```yaml tab="Kubernetes"
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-passtlsclientcert
spec:
passTLSClientCert:
pem: true
```
??? example "Pass the pem in the `X-Forwarded-Tls-Client-Cert` header"
```yaml tab="Structured (YAML)"
# Pass all the available info in the `X-Forwarded-Tls-Client-Cert-Info` header
http:
middlewares:
test-passtlsclientcert:
passTLSClientCert:
info:
notAfter: true
notBefore: true
sans: true
subject:
country: true
province: true
locality: true
organization: true
organizationalUnit: true
commonName: true
serialNumber: true
domainComponent: true
issuer:
country: true
province: true
locality: true
organization: true
commonName: true
serialNumber: true
domainComponent: true
```
```toml tab="Structured (TOML)"
# Pass all the available info in the `X-Forwarded-Tls-Client-Cert-Info` header
[http.middlewares]
[http.middlewares.test-passtlsclientcert.passTLSClientCert]
[http.middlewares.test-passtlsclientcert.passTLSClientCert.info]
notAfter = true
notBefore = true
sans = true
[http.middlewares.test-passtlsclientcert.passTLSClientCert.info.subject]
country = true
province = true
locality = true
organization = true
organizationalUnit = true
commonName = true
serialNumber = true
domainComponent = true
[http.middlewares.test-passtlsclientcert.passTLSClientCert.info.issuer]
country = true
province = true
locality = true
organization = true
commonName = true
serialNumber = true
domainComponent = true
```
```yaml tab="Labels"
# Pass all the available info in the `X-Forwarded-Tls-Client-Cert-Info` header
labels:
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.notafter=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.notbefore=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.sans=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.serialnumber=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.commonname=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.country=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.domaincomponent=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.locality=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.organization=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.organizationalunit=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.province=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.serialnumber=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.commonname=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.country=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.domaincomponent=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.locality=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.organization=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.province=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.serialnumber=true"
```
```json tab="Tags"
// Pass all the available info in the `X-Forwarded-Tls-Client-Cert-Info` header
{
//...
"Tags" : [
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.notafter=true",
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.notbefore=true",
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.sans=true",
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.commonname=true",
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.country=true",
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.domaincomponent=true",
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.locality=true",
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.organization=true",
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.organizationalunit=true",
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.province=true",
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.serialnumber=true",
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.commonname=true",
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.country=true",
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.domaincomponent=true",
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.locality=true",
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.organization=true",
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.province=true",
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.serialnumber=true"
]
}
```
```yaml tab="Kubernetes"
# Pass all the available info in the `X-Forwarded-Tls-Client-Cert-Info` header
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-passtlsclientcert
spec:
passTLSClientCert:
info:
notAfter: true
notBefore: true
sans: true
subject:
country: true
province: true
locality: true
organization: true
organizationalUnit: true
commonName: true
serialNumber: true
domainComponent: true
issuer:
country: true
province: true
locality: true
organization: true
commonName: true
serialNumber: true
domainComponent: true
```
## General Information
`passTLSClientCert` can add two headers to the request:
- `X-Forwarded-Tls-Client-Cert` that contains the pem.
- `X-Forwarded-Tls-Client-Cert-Info` that contains all the selected certificate information in an escaped string.
!!! info
- `X-Forwarded-Tls-Client-Cert-Info` header value is a string that has been escaped in order to be a valid URL query.
- These options only work accordingly to the MutualTLS configuration. i.e, only the certificates that match the `clientAuth.clientAuthType` policy are passed.
??? example "Example of a complete certificate and explaining each of the middleware options"
```txt
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 1 (0x1)
Signature Algorithm: sha1WithRSAEncryption
Issuer: DC=org, DC=cheese, O=Cheese, O=Cheese 2, OU=Simple Signing Section, OU=Simple Signing Section 2, CN=Simple Signing CA, CN=Simple Signing CA 2, C=FR, C=US, L=TOULOUSE, L=LYON, ST=Signing State, ST=Signing State 2/emailAddress=simple@signing.com/emailAddress=simple2@signing.com
Validity
Not Before: Dec 6 11:10:16 2018 GMT
Not After : Dec 5 11:10:16 2020 GMT
Subject: DC=org, DC=cheese, O=Cheese, O=Cheese 2, OU=Simple Signing Section, OU=Simple Signing Section 2, CN=*.example.org, CN=*.example.com, C=FR, C=US, L=TOULOUSE, L=LYON, ST=Cheese org state, ST=Cheese com statemailAddress=cert@example.org/emailAddress=cert@sexample.com
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
RSA Public-Key: (2048 bit)
Modulus:
00:de:77:fa:8d:03:70:30:39:dd:51:1b:cc:60:db:
a9:5a:13:b1:af:fe:2c:c6:38:9b:88:0a:0f:8e:d9:
1b:a1:1d:af:0d:66:e4:13:5b:bc:5d:36:92:d7:5e:
d0:fa:88:29:d3:78:e1:81:de:98:b2:a9:22:3f:bf:
8a:af:12:92:63:d4:a9:c3:f2:e4:7e:d2:dc:a2:c5:
39:1c:7a:eb:d7:12:70:63:2e:41:47:e0:f0:08:e8:
dc:be:09:01:ec:28:09:af:35:d7:79:9c:50:35:d1:
6b:e5:87:7b:34:f6:d2:31:65:1d:18:42:69:6c:04:
11:83:fe:44:ae:90:92:2d:0b:75:39:57:62:e6:17:
2f:47:2b:c7:53:dd:10:2d:c9:e3:06:13:d2:b9:ba:
63:2e:3c:7d:83:6b:d6:89:c9:cc:9d:4d:bf:9f:e8:
a3:7b:da:c8:99:2b:ba:66:d6:8e:f8:41:41:a0:c9:
d0:5e:c8:11:a4:55:4a:93:83:87:63:04:63:41:9c:
fb:68:04:67:c2:71:2f:f2:65:1d:02:5d:15:db:2c:
d9:04:69:85:c2:7d:0d:ea:3b:ac:85:f8:d4:8f:0f:
c5:70:b2:45:e1:ec:b2:54:0b:e9:f7:82:b4:9b:1b:
2d:b9:25:d4:ab:ca:8f:5b:44:3e:15:dd:b8:7f:b7:
ee:f9
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Key Usage: critical
Digital Signature, Key Encipherment
X509v3 Basic Constraints:
CA:FALSE
X509v3 Extended Key Usage:
TLS Web Server Authentication, TLS Web Client Authentication
X509v3 Subject Key Identifier:
94:BA:73:78:A2:87:FB:58:28:28:CF:98:3B:C2:45:70:16:6E:29:2F
X509v3 Authority Key Identifier:
keyid:1E:52:A2:E8:54:D5:37:EB:D5:A8:1D:E4:C2:04:1D:37:E2:F7:70:03
X509v3 Subject Alternative Name:
DNS:*.example.org, DNS:*.example.net, DNS:*.example.com, IP Address:10.0.1.0, IP Address:10.0.1.2, email:test@example.org, email:test@example.net
Signature Algorithm: sha1WithRSAEncryption
76:6b:05:b0:0e:34:11:b1:83:99:91:dc:ae:1b:e2:08:15:8b:
16:b2:9b:27:1c:02:ac:b5:df:1b:d0:d0:75:a4:2b:2c:5c:65:
ed:99:ab:f7:cd:fe:38:3f:c3:9a:22:31:1b:ac:8c:1c:c2:f9:
5d:d4:75:7a:2e:72:c7:85:a9:04:af:9f:2a:cc:d3:96:75:f0:
8e:c7:c6:76:48:ac:45:a4:b9:02:1e:2f:c0:15:c4:07:08:92:
cb:27:50:67:a1:c8:05:c5:3a:b3:a6:48:be:eb:d5:59:ab:a2:
1b:95:30:71:13:5b:0a:9a:73:3b:60:cc:10:d0:6a:c7:e5:d7:
8b:2f:f9:2e:98:f2:ff:81:14:24:09:e3:4b:55:57:09:1a:22:
74:f1:f6:40:13:31:43:89:71:0a:96:1a:05:82:1f:83:3a:87:
9b:17:25:ef:5a:55:f2:2d:cd:0d:4d:e4:81:58:b6:e3:8d:09:
62:9a:0c:bd:e4:e5:5c:f0:95:da:cb:c7:34:2c:34:5f:6d:fc:
60:7b:12:5b:86:fd:df:21:89:3b:48:08:30:bf:67:ff:8c:e6:
9b:53:cc:87:36:47:70:40:3b:d9:90:2a:d2:d2:82:c6:9c:f5:
d1:d8:e0:e6:fd:aa:2f:95:7e:39:ac:fc:4e:d4:ce:65:b3:ec:
c6:98:8a:31
-----BEGIN CERTIFICATE-----
MIIGWjCCBUKgAwIBAgIBATANBgkqhkiG9w0BAQUFADCCAYQxEzARBgoJkiaJk/Is
ZAEZFgNvcmcxFjAUBgoJkiaJk/IsZAEZFgZjaGVlc2UxDzANBgNVBAoMBkNoZWVz
ZTERMA8GA1UECgwIQ2hlZXNlIDIxHzAdBgNVBAsMFlNpbXBsZSBTaWduaW5nIFNl
Y3Rpb24xITAfBgNVBAsMGFNpbXBsZSBTaWduaW5nIFNlY3Rpb24gMjEaMBgGA1UE
AwwRU2ltcGxlIFNpZ25pbmcgQ0ExHDAaBgNVBAMME1NpbXBsZSBTaWduaW5nIENB
IDIxCzAJBgNVBAYTAkZSMQswCQYDVQQGEwJVUzERMA8GA1UEBwwIVE9VTE9VU0Ux
DTALBgNVBAcMBExZT04xFjAUBgNVBAgMDVNpZ25pbmcgU3RhdGUxGDAWBgNVBAgM
D1NpZ25pbmcgU3RhdGUgMjEhMB8GCSqGSIb3DQEJARYSc2ltcGxlQHNpZ25pbmcu
Y29tMSIwIAYJKoZIhvcNAQkBFhNzaW1wbGUyQHNpZ25pbmcuY29tMB4XDTE4MTIw
NjExMTAxNloXDTIwMTIwNTExMTAxNlowggF2MRMwEQYKCZImiZPyLGQBGRYDb3Jn
MRYwFAYKCZImiZPyLGQBGRYGY2hlZXNlMQ8wDQYDVQQKDAZDaGVlc2UxETAPBgNV
BAoMCENoZWVzZSAyMR8wHQYDVQQLDBZTaW1wbGUgU2lnbmluZyBTZWN0aW9uMSEw
HwYDVQQLDBhTaW1wbGUgU2lnbmluZyBTZWN0aW9uIDIxFTATBgNVBAMMDCouY2hl
ZXNlLm9yZzEVMBMGA1UEAwwMKi5jaGVlc2UuY29tMQswCQYDVQQGEwJGUjELMAkG
A1UEBhMCVVMxETAPBgNVBAcMCFRPVUxPVVNFMQ0wCwYDVQQHDARMWU9OMRkwFwYD
VQQIDBBDaGVlc2Ugb3JnIHN0YXRlMRkwFwYDVQQIDBBDaGVlc2UgY29tIHN0YXRl
MR4wHAYJKoZIhvcNAQkBFg9jZXJ0QGNoZWVzZS5vcmcxHzAdBgkqhkiG9w0BCQEW
EGNlcnRAc2NoZWVzZS5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB
AQDed/qNA3AwOd1RG8xg26laE7Gv/izGOJuICg+O2RuhHa8NZuQTW7xdNpLXXtD6
iCnTeOGB3piyqSI/v4qvEpJj1KnD8uR+0tyixTkceuvXEnBjLkFH4PAI6Ny+CQHs
KAmvNdd5nFA10Wvlh3s09tIxZR0YQmlsBBGD/kSukJItC3U5V2LmFy9HK8dT3RAt
yeMGE9K5umMuPH2Da9aJycydTb+f6KN72siZK7pm1o74QUGgydBeyBGkVUqTg4dj
BGNBnPtoBGfCcS/yZR0CXRXbLNkEaYXCfQ3qO6yF+NSPD8VwskXh7LJUC+n3grSb
Gy25JdSryo9bRD4V3bh/t+75AgMBAAGjgeAwgd0wDgYDVR0PAQH/BAQDAgWgMAkG
A1UdEwQCMAAwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMB0GA1UdDgQW
BBSUunN4oof7WCgoz5g7wkVwFm4pLzAfBgNVHSMEGDAWgBQeUqLoVNU369WoHeTC
BB034vdwAzBhBgNVHREEWjBYggwqLmNoZWVzZS5vcmeCDCouY2hlZXNlLm5ldIIM
Ki5jaGVlc2UuY29thwQKAAEAhwQKAAECgQ90ZXN0QGNoZWVzZS5vcmeBD3Rlc3RA
Y2hlZXNlLm5ldDANBgkqhkiG9w0BAQUFAAOCAQEAdmsFsA40EbGDmZHcrhviCBWL
FrKbJxwCrLXfG9DQdaQrLFxl7Zmr983+OD/DmiIxG6yMHML5XdR1ei5yx4WpBK+f
KszTlnXwjsfGdkisRaS5Ah4vwBXEBwiSyydQZ6HIBcU6s6ZIvuvVWauiG5UwcRNb
CppzO2DMENBqx+XXiy/5Lpjy/4EUJAnjS1VXCRoidPH2QBMxQ4lxCpYaBYIfgzqH
mxcl71pV8i3NDU3kgVi2440JYpoMveTlXPCV2svHNCw0X238YHsSW4b93yGJO0gI
-----END CERTIFICATE-----
```
## Configuration Options
| Field | Description | Default | Required |
|:-----------|:------------------------------------------------------------|:--------|:---------|
| `pem` | Fills the `X-Forwarded-Tls-Client-Cert` header with the certificate information.<br /> More information [here](#pem). | false | No |
| `info.serialNumber` | Add the `Serial Number` of the certificate.<br /> More information about `info` [here](#info). | false | No |
| `info.notAfter` | Add the `Not After` information from the `Validity` part. <br /> More information about `info` [here](#info). | false | No |
| `info.notBefore` | Add the `Not Before` information from the `Validity` part. <br />More information about `info` [here](#info). | false | No |
| `info.sans` | Add the `Subject Alternative Name` information from the `Subject Alternative Name` part. <br /> More information about `info` [here](#info). | false | No |
| `info.subject` | The `info.subject` selects the specific client certificate subject details you want to add to the `X-Forwarded-Tls-Client-Cert-Info` header. <br />More information about `info` [here](#info). | false | No |
| `info.subject.country` | Add the `country` information into the subject.<br /> The data is taken from the subject part with the `C` key. <br />More information about `info` [here](#info). | false | No |
| `info.subject.province` | Add the `province` information into the subject.<br /> The data is taken from the subject part with the `ST` key. <br />More information about `info` [here](#info). | false | No |
| `info.subject.locality` | Add the `locality` information into the subject.<br /> The data is taken from the subject part with the `L` key. <br />More information about `info` [here](#info). | false | No |
| `info.subject.organization` | Add the `organization` information into the subject.<br /> The data is taken from the subject part with the `O` key. <br />More information about `info` [here](#info). | false | No |
| `info.subject.organizationalUnit` | Add the `organizationalUnit` information into the subject.<br /> The data is taken from the subject part with the `OU` key. <br />More information about `info` [here](#info). | false | No |
| `info.subject.commonName` | Add the `commonName` information into the subject.<br /> The data is taken from the subject part with the `CN` key.| false | No |
| `info.subject.serialNumber` | Add the `serialNumber` information into the subject.<br /> The data is taken from the subject part with the `SN` key.| false | No |
| `info.subject.domainComponent` | Add the `domainComponent` information into the subject.<br />The data is taken from the subject part with the `DC` key. <br />More information about `info` [here](#info). | false | No |
| `info.issuer` | The `info.issuer` selects the specific client certificate issuer details you want to add to the `X-Forwarded-Tls-Client-Cert-Info` header. <br />More information about `info` [here](#info). | false | No |
| `info.issuer.country` | Add the `country` information into the issuer.<br /> The data is taken from the issuer part with the `C` key. <br />More information about `info` [here](#info). | false | No |
| `info.issuer.province` | Add the `province` information into the issuer.<br />The data is taken from the issuer part with the `ST` key. <br />More information about `info` [here](#info). | false | No |
| `info.issuer.locality` | Add the `locality` information into the issuer.<br /> The data is taken from the issuer part with the `L` key. <br />More information about `info` [here](#info). | false | No |
| `info.issuer.organization` | Add the `organization` information into the issuer.<br /> The data is taken from the issuer part with the `O` key. <br />More information about `info` [here](#info). | false | No |
| `info.issuer.commonName` |Add the `commonName` information into the issuer.<br /> The data is taken from the issuer part with the `CN` key. <br />More information about `info` [here](#info). | false | No |
| `info.issuer.serialNumber` |Add the `serialNumber` information into the issuer.<br /> The data is taken from the issuer part with the `SN` key. <br />More information about `info` [here](#info). | false | No |
| `info.issuer.domainComponent` | Add the `domainComponent` information into the issuer.<br /> The data is taken from the issuer part with the `DC` key. <br />More information about `info` [here](#info). | false | No |
### pem
#### Data Format
The delimiters and `\n` will be removed.
If there are more than one certificate, they are separated by a "`,`".
#### Header size
The `X-Forwarded-Tls-Client-Cert` header value could exceed the web server header size limit
The header size limit of web servers is commonly between 4kb and 8kb.
If that turns out to be a problem, and if reconfiguring the server to allow larger headers is not an option,
one can alleviate the problem by selecting only the interesting parts of the cert,
through the use of the `info` options described below. (And by setting `pem` to false).
### info
The `info` option selects the specific client certificate details you want to add to the `X-Forwarded-Tls-Client-Cert-Info` header.
#### Data Format
The value of the header is an escaped concatenation of all the selected certificate details.
Unless specified otherwise, all the header values examples are shown unescaped, for readability.
If there are more than one certificate, they are separated by a `,`.
The following example shows such a concatenation, when all the available fields are selected:
```text
Subject="DC=org,DC=cheese,C=FR,C=US,ST=Cheese org state,ST=Cheese com state,L=TOULOUSE,L=LYON,O=Cheese,O=Cheese 2,CN=*.example.com";Issuer="DC=org,DC=cheese,C=FR,C=US,ST=Signing State,ST=Signing State 2,L=TOULOUSE,L=LYON,O=Cheese,O=Cheese 2,CN=Simple Signing CA 2";NB="1544094616";NA="1607166616";SAN="*.example.org,*.example.net,*.example.com,test@example.org,test@example.net,10.0.1.0,10.0.1.2"
```

150
docs/content/reference/routing-configuration/http/middlewares/ratelimit.md Normal file
View file

@ -0,0 +1,150 @@
---
title: "Traefik RateLimit Documentation"
description: "Traefik Proxy's HTTP RateLimit middleware ensures Services receive fair amounts of requests. Read the technical documentation."
---
The `rateLimit` middleware ensures that services will receive a *fair* amount of requests, and allows you to define what fair is.
It is based on a [token bucket](https://en.wikipedia.org/wiki/Token_bucket) implementation.
In this analogy, the `average` and `period` parameters define the **rate** at which the bucket refills, and the `burst` is the size (volume) of the bucket
## Rate and Burst
The rate is defined by dividing `average` by `period`.
For a rate below 1 req/s, define a `period` larger than a second
## Configuration Example
```yaml tab="Structured (YAML)"
# Here, an average of 100 requests per second is allowed.
# In addition, a burst of 200 requests is allowed.
http:
middlewares:
test-ratelimit:
rateLimit:
average: 100
burst: 200
```
```toml tab="Structured (TOML)"
# Here, an average of 100 requests per second is allowed.
# In addition, a burst of 200 requests is allowed.
[http.middlewares]
[http.middlewares.test-ratelimit.rateLimit]
average = 100
burst = 200
```
```yaml tab="Labels"
# Here, an average of 100 requests per second is allowed.
# In addition, a burst of 200 requests is allowed.
labels:
- "traefik.http.middlewares.test-ratelimit.ratelimit.average=100"
- "traefik.http.middlewares.test-ratelimit.ratelimit.burst=200"
```
```json tab="Tags"
// Here, an average of 100 requests per second is allowed.
// In addition, a burst of 200 requests is allowed.
{
"Tags": [
"traefik.http.middlewares.test-ratelimit.ratelimit.average=100",
"traefik.http.middlewares.test-ratelimit.ratelimit.burst=50"
]
}
```
```yaml tab="Kubernetes"
# Here, an average of 100 requests per second is allowed.
# In addition, a burst of 200 requests is allowed.
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-ratelimit
spec:
rateLimit:
average: 100
burst: 200
```
## Configuration Options
| Field | Description | Default | Required |
|:-----------|:-------------------------------------------------------|:--------|:---------|
| `average` | Number of requests used to define the rate using the `period`.<br /> 0 means **no rate limiting**.<br />More information [here](#rate-and-burst). | 0 | No |
| `period` | Period of time used to define the rate.<br />More information [here](#rate-and-burst). | 1s | No |
| `burst` | Maximum number of requests allowed to go through at the very same moment.<br />More information [here](#rate-and-burst).| 1 | No |
| `sourceCriterion.requestHost` | Whether to consider the request host as the source.<br />More information about `sourceCriterion`[here](#sourcecriterion). | false | No |
| `sourceCriterion.requestHeaderName` | Name of the header used to group incoming requests.<br />More information about `sourceCriterion`[here](#sourcecriterion). | "" | No |
| `sourceCriterion.ipStrategy.depth` | Depth position of the IP to select in the `X-Forwarded-For` header (starting from the right).<br />0 means no depth.<br />If greater than the total number of IPs in `X-Forwarded-For`, then the client IP is empty<br />If higher than 0, the `excludedIPs` options is not evaluated.<br />More information about [`sourceCriterion`](#sourcecriterion), [`ipStrategy`](#ipstrategy), and [`depth`](#sourcecriterionipstrategydepth) below. | 0 | No |
| `sourceCriterion.ipStrategy.excludedIPs` | Allows scanning the `X-Forwarded-For` header and select the first IP not in the list.<br />If `depth` is specified, `excludedIPs` is ignored.<br />More information about [`sourceCriterion`](#sourcecriterion), [`ipStrategy`](#ipstrategy), and [`excludedIPs`](#sourcecriterionipstrategyexcludedips) below. | | No |
| `sourceCriterion.ipStrategy.ipv6Subnet` | If `ipv6Subnet` is provided and the selected IP is IPv6, the IP is transformed into the first IP of the subnet it belongs to. <br />More information about [`sourceCriterion`](#sourcecriterion), [`ipStrategy.ipv6Subnet`](#sourcecriterionipstrategyipv6subnet) below. | | No |
### sourceCriterion
The `sourceCriterion` option defines what criterion is used to group requests as originating from a common source.
If several strategies are defined at the same time, an error will be raised.
If none are set, the default is to use the request's remote address field (as an `ipStrategy`).
### ipStrategy
The `ipStrategy` option defines three parameters that configures how Traefik determines the client IP: `depth`, `excludedIPs` and `ipv6Subnet`.
As a middleware, rate-limiting happens before the actual proxying to the backend takes place.
In addition, the previous network hop only gets appended to `X-Forwarded-For` during the last stages of proxying, that is after it has already passed through rate-limiting.
Therefore, during rate-limiting, as the previous network hop is not yet present in `X-Forwarded-For`, it cannot be found and/or relied upon.
### `sourceCriterion.ipStrategy.ipv6Subnet`
This strategy applies to `Depth` and `RemoteAddr` strategy only.
If `ipv6Subnet` is provided and the selected IP is IPv6, the IP is transformed into the first IP of the subnet it belongs to.
This is useful for grouping IPv6 addresses into subnets to prevent bypassing this middleware by obtaining a new IPv6.
- `ipv6Subnet` is ignored if its value is outside of 0-128 interval
#### Example of ipv6Subnet
If `ipv6Subnet` is provided, the IP is transformed in the following way.
| `IP` | `ipv6Subnet` | clientIP |
|---------------------------|--------------|-----------------------|
| `"::abcd:1111:2222:3333"` | `64` | `"::0:0:0:0"` |
| `"::abcd:1111:2222:3333"` | `80` | `"::abcd:0:0:0:0"` |
| `"::abcd:1111:2222:3333"` | `96` | `"::abcd:1111:0:0:0"` |
### sourceCriterion.ipStrategy.depth
If `depth` is set to 2, and the request `X-Forwarded-For` header is `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` then the "real" client IP is `"10.0.0.1"` (at depth 4) but the IP used as the criterion is `"12.0.0.1"` (`depth=2`).
| `X-Forwarded-For` | `depth` | clientIP |
|-----------------------------------------|---------|--------------|
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `1` | `"13.0.0.1"` |
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `3` | `"11.0.0.1"` |
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `5` | `""` |
### sourceCriterion.ipStrategy.excludedIPs
Contrary to what the name might suggest, this option is *not* about excluding an IP from the rate limiter, and therefore cannot be used to deactivate rate limiting for some IPs.
`excludedIPs` is meant to address two classes of somewhat distinct use-cases:
1. Distinguish IPs which are behind the same (set of) reverse-proxies so that each of them contributes, independently to the others, to its own rate-limit "bucket" (cf the [token bucket](https://en.wikipedia.org/wiki/Token_bucket)).
In this case, `excludedIPs` should be set to match the list of `X-Forwarded-For IPs` that are to be excluded, in order to find the actual clientIP.
Example to use each IP as a distinct source:
| X-Forwarded-For | excludedIPs | clientIP |
|--------------------------------|-----------------------|--------------|
| `"10.0.0.1,11.0.0.1,12.0.0.1"` | `"11.0.0.1,12.0.0.1"` | `"10.0.0.1"` |
| `"10.0.0.2,11.0.0.1,12.0.0.1"` | `"11.0.0.1,12.0.0.1"` | `"10.0.0.2"` |
2. Group together a set of IPs (also behind a common set of reverse-proxies) so that they are considered the same source, and all contribute to the same rate-limit bucket.
Example to group IPs together as same source:
| X-Forwarded-For | excludedIPs | clientIP |
|--------------------------------|--------------|--------------|
| `"10.0.0.1,11.0.0.1,12.0.0.1"` | `"12.0.0.1"` | `"11.0.0.1"` |
| `"10.0.0.2,11.0.0.1,12.0.0.1"` | `"12.0.0.1"` | `"11.0.0.1"` |
| `"10.0.0.3,11.0.0.1,12.0.0.1"` | `"12.0.0.1"` | `"11.0.0.1"` |

88
docs/content/reference/routing-configuration/http/middlewares/redirectregex.md Normal file
View file

@ -0,0 +1,88 @@
---
title: "Traefik RedirectRegex Documentation"
description: "In Traefik Proxy's HTTP middleware, RedirectRegex redirecting clients to different locations. Read the technical documentation."
---
The `RedirectRegex` redirects a request using regex matching and replacement.
## Configuration Examples
```yaml tab="Structured (YAML)"
# Redirect with domain replacement
http:
middlewares:
test-redirectregex:
redirectRegex:
regex: "^http://localhost/(.*)"
replacement: "http://mydomain/${1}"
```
```toml tab="Structured (TOML)"
# Redirect with domain replacement
[http.middlewares]
[http.middlewares.test-redirectregex.redirectRegex]
regex = "^http://localhost/(.*)"
replacement = "http://mydomain/${1}"
```
```yaml tab="Labels"
# Redirect with domain replacement
# Note: all dollar signs need to be doubled for escaping.
labels:
- "traefik.http.middlewares.test-redirectregex.redirectregex.regex=^http://localhost/(.*)"
- "traefik.http.middlewares.test-redirectregex.redirectregex.replacement=http://mydomain/$${1}"
```
```json tab="Tags"
// Redirect with domain replacement
// Note: all dollar signs need to be doubled for escaping.
{
// ...
"Tags" : [
"traefik.http.middlewares.test-redirectregex.redirectregex.regex=^http://localhost/(.*)"
"traefik.http.middlewares.test-redirectregex.redirectregex.replacement=http://mydomain/$${1}"
]
}
```
```yaml tab="Kubernetes"
# Redirect with domain replacement
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-redirectregex
spec:
redirectRegex:
regex: ^http://localhost/(.*)
replacement: http://mydomain/${1}
```
## Configuration Options
<!-- markdownlint-disable MD013 -->
| Field | Description | Default | Required |
|:-----------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------|
| `regex` | The `regex` option is the regular expression to match and capture elements from the request URL.| "" | Yes |
| `permanent` | Enable a permanent redirection. | false | No |
| `replacement` | The `replacement` option defines how to modify the URL to have the new target URL..<br /> `$1x` is equivalent to `${1x}`, not `${1}x` (see [Regexp.Expand](https://golang.org/pkg/regexp/#Regexp.Expand)), so use `${1}` syntax. | "" | No |
### `regex`
The `regex` option is the regular expression to match and capture elements from the request URL.
!!! tip
Regular expressions and replacements can be tested using online tools such as [Go Playground](https://play.golang.org/p/mWU9p-wk2ru) or the [Regex101](https://regex101.com/r/58sIgx/2).
When defining a regular expression within YAML, any escaped character needs to be escaped twice: `example\.com` needs to be written as `example\\.com`.
### `replacement`
The `replacement` option defines how to modify the URL to have the new target URL.
!!! warning
Care should be taken when defining replacement expand variables: `$1x` is equivalent to `${1x}`, not `${1}x` (see [Regexp.Expand](https://golang.org/pkg/regexp/#Regexp.Expand)), so use `${1}` syntax.
{!traefik-for-business-applications.md!}

74
docs/content/reference/routing-configuration/http/middlewares/redirectscheme.md Normal file
View file

@ -0,0 +1,74 @@
---
title: "Traefik RedirectScheme Documentation"
description: "In Traefik Proxy's HTTP middleware, RedirectScheme redirects clients to different schemes/ports. Read the technical documentation."
---
The `RedirectScheme` middleware redirects the request if the request scheme is different from the configured scheme.
!!! warning "When behind another reverse-proxy"
When there is at least one other reverse-proxy between the client and Traefik,
the other reverse-proxy (i.e. the last hop) needs to be a [trusted](../../../install-configuration/entrypoints.md#configuration-options) one.
Otherwise, Traefik would clean up the X-Forwarded headers coming from this last hop,
and as the RedirectScheme middleware relies on them to determine the scheme used,
it would not function as intended.
## Configuration Examples
```yaml tab="Structured (YAML)"
# Redirect to https
http:
middlewares:
test-redirectscheme:
redirectScheme:
scheme: https
permanent: true
```
```toml tab="Structured (TOML)"
# Redirect to https
[http.middlewares]
[http.middlewares.test-redirectscheme.redirectScheme]
scheme = "https"
permanent = true
```
```yaml tab="Labels"
# Redirect to https
labels:
- "traefik.http.middlewares.test-redirectscheme.redirectscheme.scheme=https"
- "traefik.http.middlewares.test-redirectscheme.redirectscheme.permanent=true"
```
```json tab="Tags"
// Redirect to https
{
// ...
"Tags": [
"traefik.http.middlewares.test-redirectscheme.redirectscheme.scheme=https"
"traefik.http.middlewares.test-redirectscheme.redirectscheme.permanent=true"
]
}
```
```yaml tab="Kubernetes"
# Redirect to https
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-redirectscheme
spec:
redirectScheme:
scheme: https
permanent: true
```
## Configuration Options
| Field | Description | Default | Required |
|:-----------------------------|----------------------------------------------------------|:--------|:---------|
| `scheme` | Scheme of the new URL. | "" | Yes |
| `permanent` | Enable a permanent redirection. | false | No |
| `port` | Port of the new URL.<br />Set a string, **not** a numeric value. | "" | No |

60
docs/content/reference/routing-configuration/http/middlewares/replacepath.md Normal file
View file

@ -0,0 +1,60 @@
---
title: "Traefik ReplacePath Documentation"
description: "In Traefik Proxy's HTTP middleware, ReplacePath updates paths before forwarding requests. Read the technical documentation."
---
The `replacePath` middleware will:
- Replace the actual path with the specified one.
- Store the original path in a `X-Replaced-Path` header
## Configuration Examples
```yaml tab="Structured (YAML)"
# Replace the path with /foo
http:
middlewares:
test-replacepath:
replacePath:
path: "/foo"
```
```toml tab="Structured (TOML)"
# Replace the path with /foo
[http.middlewares]
[http.middlewares.test-replacepath.replacePath]
path = "/foo"
```
```yaml tab="Labels"
# Replace the path with /foo
labels:
- "traefik.http.middlewares.test-replacepath.replacepath.path=/foo"
```
```json tab="Tags"
// Replace the path with /foo
{
// ...
"Tags" : [
"traefik.http.middlewares.test-replacepath.replacepath.path=/foo"
]
}
```
```yaml tab="Kubernetes"
# Replace the path with /foo
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-replacepath
spec:
replacePath:
path: "/foo"
```
## Configuration Options
| Field | Description |
|:------|:------------|
| `path` | The `path` option defines the path to use as replacement in the request URL. |

67
docs/content/reference/routing-configuration/http/middlewares/replacepathregex.md Normal file
View file

@ -0,0 +1,67 @@
---
title: "Traefik ReplacePathRegex Documentation"
description: "In Traefik Proxy's HTTP middleware, ReplacePathRegex updates paths before forwarding requests, using a regex. Read the technical documentation."
---
The `replacePathRegex` middleware will:
- Replace the matching path with the specified one.
- Store the original path in an `X-Replaced-Path` header
## Configuration Examples
```yaml tab="File (YAML)"
# Replace path with regex
http:
middlewares:
test-replacepathregex:
replacePathRegex:
regex: "^/foo/(.*)"
replacement: "/bar/$1"
```
```toml tab="File (TOML)"
# Replace path with regex
[http.middlewares]
[http.middlewares.test-replacepathregex.replacePathRegex]
regex = "^/foo/(.*)"
replacement = "/bar/$1"
```
```yaml tab="Kubernetes"
# Replace path with regex
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-replacepathregex
spec:
replacePathRegex:
regex: "^/foo/(.*)"
replacement: "/bar/$1"
```
```yaml tab="Docker & Swarm"
# Replace path with regex
labels:
- "traefik.http.middlewares.test-replacepathregex.replacepathregex.regex=^/foo/(.*)"
- "traefik.http.middlewares.test-replacepathregex.replacepathregex.replacement=/bar/$$1"
```
```yaml tab="Consul Catalog"
# Replace path with regex
- "traefik.http.middlewares.test-replacepathregex.replacepathregex.regex=^/foo/(.*)"
- "traefik.http.middlewares.test-replacepathregex.replacepathregex.replacement=/bar/$1"
```
## Configuration Options
| Field | Description | Default | Required |
|:-----------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------|
| `regex` | Regular expression to match and capture the path from the request URL. | | Yes |
| `replacement` | Replacement path format, which can include captured variables.<br /> `$1x` is equivalent to `${1x}`, not `${1}x` (see [Regexp.Expand](https://golang.org/pkg/regexp/#Regexp.Expand)), so use `${1}` syntax. | | No
!!! tip
Regular expressions and replacements can be tested using online tools such as [Go Playground](https://play.golang.org/p/mWU9p-wk2ru) or the [Regex101](https://regex101.com/r/58sIgx/2).
When defining a regular expression within YAML, any escaped character needs to be escaped twice: `example\.com` needs to be written as `example\\.com`.

68
docs/content/reference/routing-configuration/http/middlewares/retry.md Normal file
View file

@ -0,0 +1,68 @@
---
title: "Traefik HTTP Retry Documentation"
description: "Configure Traefik Proxy's HTTP Retry middleware, so you can retry requests to a backend server until it succeeds. Read the technical documentation."
---
The `retry` middleware retries requests a given number of times to a backend server if that server does not reply.
As soon as the server answers, the middleware stops retrying, regardless of the response status.
The Retry middleware has an optional configuration to enable an exponential backoff.
## Configuration Examples
```yaml tab="Structured (YAML)"
# Retry 4 times with exponential backoff
http:
middlewares:
test-retry:
retry:
attempts: 4
initialInterval: 100ms
```
```toml tab="Structured (TOML)"
# Retry 4 times with exponential backoff
[http.middlewares]
[http.middlewares.test-retry.retry]
attempts = 4
initialInterval = "100ms"
```
```yaml tab="Labels"
# Retry 4 times with exponential backoff
labels:
- "traefik.http.middlewares.test-retry.retry.attempts=4"
- "traefik.http.middlewares.test-retry.retry.initialinterval=100ms"
```
```json tab="Tags"
// Retry 4 times with exponential backoff
{
// ...
"Tags" : [
"traefik.http.middlewares.test-retry.retry.attempts=4",
"traefik.http.middlewares.test-retry.retry.initialinterval=100ms"
]
}
```
```yaml tab="Kubernetes"
# Retry 4 times with exponential backoff
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-retry
spec:
retry:
attempts: 4
initialInterval: 100ms
```
## Configuration Options
| Field | Description | Default | Required |
|:------|:------------|:--------|:---------|
| `attempts` | number of times the request should be retried. | | Yes |
| `initialInterval` | First wait time in the exponential backoff series. <br />The maximum interval is calculated as twice the `initialInterval`. <br /> If unspecified, requests will be retried immediately.<br /> Defined in seconds or as a valid duration format, see [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration). | 0 | No |

66
docs/content/reference/routing-configuration/http/middlewares/stripprefix.md Normal file
View file

@ -0,0 +1,66 @@
---
title: "Traefik StripPrefix Documentation"
description: "In Traefik Proxy's HTTP middleware, StripPrefix removes prefixes from paths before forwarding requests. Read the technical documentation."
---
The `stripPrefix` middleware strips the matching path prefix and stores it in an `X-Forwarded-Prefix` header.
!!! tip
Use a `StripPrefix` middleware if your backend listens on the root path (`/`) but should be exposed on a specific prefix.
## Configuration Examples
```yaml tab="Structured (YAML)"
# Strip prefix /foobar and /fiibar
http:
middlewares:
test-stripprefix:
stripPrefix:
prefixes:
- "/foobar"
- "/fiibar"
```
```toml tab="Structured (TOML)"
# Strip prefix /foobar and /fiibar
[http.middlewares]
[http.middlewares.test-stripprefix.stripPrefix]
prefixes = ["/foobar", "/fiibar"]
```
```yaml tab="Labels"
# Strip prefix /foobar and /fiibar
labels:
- "traefik.http.middlewares.test-stripprefix.stripprefix.prefixes=/foobar,/fiibar"
```
```json tab="Tags"
// Strip prefix /foobar and /fiibar
{
"Tags" : [
"traefik.http.middlewares.test-stripprefix.stripprefix.prefixes=/foobar,/fiibar"
]
}
```
```yaml tab="Kubernetes"
# Strip prefix /foobar and /fiibar
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-stripprefix
spec:
stripPrefix:
prefixes:
- /foobar
- /fiibar
```
## Configuration Options
| Field | Description | Default | Required |
|:-----------------------------|:--------------------------------------------------------------|:--------|:---------|
| `prefixes` | List of prefixes to strip from the request URL.<br />If your backend is serving assets (for example, images or JavaScript files), it can use the `X-Forwarded-Prefix` header to construct relative URLs. | [] | No |
{!traefik-for-business-applications.md!}

70
docs/content/reference/routing-configuration/http/middlewares/stripprefixregex.md Normal file
View file

@ -0,0 +1,70 @@
---
title: "Traefik StripPrefixRegex Documentation"
description: "In Traefik Proxy's HTTP middleware, StripPrefixRegex removes prefixes from paths before forwarding requests, using regex. Read the technical documentation."
---
The `stripPrefixRegex` middleware strips the matching path prefix and stores it in an `X-Forwarded-Prefix` header.
!!! tip
Use a `stripPrefixRegex` middleware if your backend listens on the root path (`/`) but should be exposed on a specific prefix.
## Configuration Example
```yaml tab="Structured (YAML)"
http:
middlewares:
test-stripprefixregex:
stripPrefixRegex:
regex:
- "/foo/[a-z0-9]+/[0-9]+/"
```
```toml tab="Structured (TOML)"
[http.middlewares]
[http.middlewares.test-stripprefixregex.stripPrefixRegex]
regex = ["/foo/[a-z0-9]+/[0-9]+/"]
```
```yaml tab="Labels"
labels:
- "traefik.http.middlewares.test-stripprefixregex.stripprefixregex.regex=/foo/[a-z0-9]+/[0-9]+/"
```
```yaml tab="Tags"
{
//..
"Tags" : [
"traefik.http.middlewares.test-stripprefixregex.stripprefixregex.regex=/foo/[a-z0-9]+/[0-9]+/"
]
}
-
```
```yaml tab="Kubernetes"
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-stripprefixregex
spec:
stripPrefixRegex:
regex:
- "/foo/[a-z0-9]+/[0-9]+/"
```
## Configuration Options
| Field | Description | Default | Required |
|:-----------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------|
| `regex` | List of regular expressions to match the path prefix from the request URL.<br /> For instance, `/products` also matches `/products/shoes` and `/products/shirts`.<br />More information [here](#regex). | | No |
### regex
If your backend is serving assets (for example, images or JavaScript files), it can use the `X-Forwarded-Prefix` header to construct relative URLs.
Using the previous example, the backend should return `/products/shoes/image.png` (and not `/images.png`, which Traefik would likely not be able to associate with the same backend).
!!! tip
Regular expressions and replacements can be tested using online tools such as [Go Playground](https://play.golang.org/p/mWU9p-wk2ru) or the [Regex101](https://regex101.com/r/58sIgx/2).
When defining a regular expression within YAML, any escaped character needs to be escaped twice: `example\.com` needs to be written as `example\\.com`.

80
docs/content/reference/routing-configuration/http/router/observability.md Normal file
View file

@ -0,0 +1,80 @@
---
title: "Per-Router Observability"
description: "You can disable access logs, metrics, and tracing for a specific entrypoint attached to a HTTP Router. Read the technical documentation."
---
Traefik's observability features include logs, access logs, metrics, and tracing. You can configure these options globally or at more specific levels, such as per router or per entry point.
By default, the router observability configuration is inherited from the attached EntryPoints and can be configured with the observability [options](../../../install-configuration/entrypoints.md#configuration-options)).
However, a router defining its own observability configuration will opt-out from these defaults.
!!! info
To enable router-level observability, you must first enable access-logs, tracing, and metrics.
When metrics layers are not enabled with the `addEntryPointsLabels`, `addRoutersLabels` and/or `addServicesLabels` options,
enabling metrics for a router will not enable them.
!!! warning "AddInternals option"
By default, and for any type of signal (access-logs, metrics and tracing),
Traefik disables observability for internal resources.
The observability options described below cannot interfere with the `AddInternals` ones,
and will be ignored.
For instance, if a router exposes the `api@internal` service and `metrics.AddInternals` is false,
it will never produces metrics, even if the router observability configuration enables metrics.
## Configuration Example
```yaml tab="Structured (YAML)"
http:
routers:
my-router:
rule: "Path(`/foo`)"
service: service-foo
observability:
metrics: false
accessLogs: false
tracing: false
```
```yaml tab="Structured (TOML)"
[http.routers.my-router]
rule = "Path(`/foo`)"
service = "service-foo"
[http.routers.my-router.observability]
metrics = false
accessLogs = false
tracing = false
```
```yaml tab="Labels"
labels:
- "traefik.http.routers.my-router.rule=Path(`/foo`)"
- "traefik.http.routers.my-router.service=service-foo"
- "traefik.http.routers.my-router.observability.metrics=false"
- "traefik.http.routers.my-router.observability.accessLogs=false"
- "traefik.http.routers.my-router.observability.tracing=false"
```
```json tab="Tags"
{
// ...
"Tags": [
"traefik.http.routers.my-router.rule=Path(`/foo`)",
"traefik.http.routers.my-router.service=service-foo",
"traefik.http.routers.my-router.observability.metrics=false",
"traefik.http.routers.my-router.observability.accessLogs=false",
"traefik.http.routers.my-router.observability.tracing=false"
]
}
```
## Configuration Options
| Field | Description | Default | Required |
|:------|:------------|:--------|:---------|
| `accessLogs` | The `accessLogs` option controls whether the router will produce access-logs. | `true` | No |
| `metrics` | The `metrics` option controls whether the router will produce metrics. | `true` | No |
| `tracing` | The `tracing` option controls whether the router will produce traces. | `true` | No |

291
docs/content/reference/routing-configuration/http/router/rules-and-priority.md Normal file
View file

@ -0,0 +1,291 @@
---
title: "Traefik HTTP Routers Rules & Priority Documentation"
description: "In Traefik Proxy, an HTTP router is in charge of connecting incoming requests to the Services that can handle them. Read the technical documentation."
---
An HTTP router is in charge of connecting incoming requests to the services that can handle them. Traefik allows you to define your matching rules and [prioritize](#priority-calculation) the routes.
## Rules
Rules are a set of matchers configured with values, that determine if a particular request matches a specific criteria.
If the rule is verified, the router becomes active, calls middlewares, and then forwards the request to the service.
- The character `@` is not authorized in the router name.
- To set the value of a rule, use [backticks](https://en.wiktionary.org/wiki/backtick) ` or escaped double-quotes ``\"``.
- Single quotes ' are not accepted since the values are [Go's String Literals](https://golang.org/ref/spec#String_literals).
- Regular Expressions:
- Matchers that accept a regexp as their value use a [Go](https://golang.org/pkg/regexp/) flavored syntax.
- The usual `AND` (&&) and `OR` (||) logical operators can be used, with the expected precedence rules, as well as parentheses to express complex rules.
- The `NOT` (!) operator allows you to invert the matcher.
The table below lists all the available matchers:
| Matcher | Description |
|-----------------------------------------------------------------|:-------------------------------------------------------------------------------|
| [```Header(`key`, `value`)```](#header-and-headerregexp) | Matches requests containing a header named `key` set to `value`. |
| [```HeaderRegexp(`key`, `regexp`)```](#header-and-headerregexp) | Matches requests containing a header named `key` matching `regexp`. |
| [```Host(`domain`)```](#host-and-hostregexp) | Matches requests host set to `domain`. |
| [```HostRegexp(`regexp`)```](#host-and-hostregexp) | Matches requests host matching `regexp`. |
| [```Method(`method`)```](#method) | Matches requests method set to `method`. |
| [```Path(`path`)```](#path-pathprefix-and-pathregexp) | Matches requests path set to `path`. |
| [```PathPrefix(`prefix`)```](#path-pathprefix-and-pathregexp) | Matches requests path prefix set to `prefix`. |
| [```PathRegexp(`regexp`)```](#path-pathprefix-and-pathregexp) | Matches request path using `regexp`. |
| [```Query(`key`, `value`)```](#query-and-queryregexp) | Matches requests query parameters named `key` set to `value`. |
| [```QueryRegexp(`key`, `regexp`)```](#query-and-queryregexp) | Matches requests query parameters named `key` matching `regexp`. |
| [```ClientIP(`ip`)```](#clientip) | Matches requests client IP using `ip`. It accepts IPv4, IPv6 and CIDR formats. |
### Header and HeaderRegexp
The `Header` and `HeaderRegexp` matchers allow matching requests that contain specific header.
| Behavior | Rule |
|-----------------------------------------------------------------|:------------------------------------------------------------------------|
| Match requests with a `Content-Type` header set to `application/yaml`.| ```Header(`Content-Type`, `application/yaml`)``` |
| Match requests with a `Content-Type` header set to either `application/json` or `application/yaml`. | ```HeaderRegexp(`Content-Type`, `^application/(json\|yaml)$`)``` |
| Match headers [case-insensitively](https://en.wikipedia.org/wiki/Case_sensitivity). | ```HeaderRegexp(`Content-Type`, `(?i)^application/(json\|yaml)$`)``` |
### Host and HostRegexp
The `Host` and `HostRegexp` matchers allow matching requests that are targeted to a given host.
These matchers do not support non-ASCII characters, use punycode encoded values ([rfc 3492](https://tools.ietf.org/html/rfc3492)) to match such domains.
If no `Host` is set in the request URL (for example, it's an IP address), these matchers will look at the `Host` header.
These matchers will match the request's host in lowercase.
| Behavior | Rule |
|-----------------------------------------------------------------|:------------------------------------------------------------------------|
| Match requests with `Host` set to `example.com`. | ```Host(`example.com`)``` |
| Match requests sent to any subdomain of `example.com`. | ```HostRegexp(`^.+\.example\.com$`)``` |
| Match requests with `Host` set to either `example.com` or `example.org`. | ```HostRegexp(`^example\.(com\|org)$`)``` |
| Match `Host` [case-insensitively](https://en.wikipedia.org/wiki/Case_sensitivity). | ```HostRegexp(`(?i)^example\.(com\|org)$`)``` |
### Method
The `Method` matchers allows matching requests sent based on their HTTP method (also known as request verb).
| Behavior | Rule |
|-----------------------------------------------------------------|:------------------------------------------------------------------------|
| Match `OPTIONS` requests. | ```Method(`OPTIONS`)``` |
### Path, PathPrefix, and PathRegexp
These matchers allow matching requests based on their URL path.
For exact matches, use `Path` and its prefixed alternative `PathPrefix`, for regexp matches, use `PathRegexp`.
Path are always starting with a `/`, except for `PathRegexp`.
| Behavior | Rule |
|-----------------------------------------------------------------|:------------------------------------------------------------------------|
| Match `/products` but neither `/products/shoes` nor `/products/`. | ```Path(`/products`)``` |
| Match `/products` as well as everything under `/products`, such as `/products/shoes`, `/products/` but also `/products-for-sale`. | ```PathPrefix(`/products`)``` |
| Match both `/products/shoes` and `/products/socks` with and ID like `/products/shoes/31`. | ```PathRegexp(`^/products/(shoes\|socks)/[0-9]+$`)``` |
| Match requests with a path ending in either `.jpeg`, `.jpg` or `.png`. | ```PathRegexp(`\.(jpeg\|jpg\|png)$`)``` |
| Match `/products` as well as everything under `/products`, such as `/products/shoes`, `/products/` but also `/products-for-sale`, [case-insensitively](https://en.wikipedia.org/wiki/Case_sensitivity). | ```HostRegexp(`(?i)^/products`)``` |
### Query and QueryRegexp
The `Query` and `QueryRegexp` matchers allow matching requests based on query parameters.
| Behavior | Rule |
|-----------------------------------------------------------------|:------------------------------------------------------------------------|
| Match requests with a `mobile` query parameter set to `true`, such as in `/search?mobile=true`. | ```Query(`mobile`, `true`)``` |
| Match requests with a query parameter `mobile` that has no value, such as in `/search?mobile`. | ```Query(`mobile`)``` |
| Match requests with a `mobile` query parameter set to either `true` or `yes`. | ```QueryRegexp(`mobile`, `^(true\|yes)$`)``` |
| Match requests with a `mobile` query parameter set to any value (including the empty value). | ```QueryRegexp(`mobile`, `^.*$`)``` |
| Match query parameters [case-insensitively](https://en.wikipedia.org/wiki/Case_sensitivity). | ```QueryRegexp(`mobile`, `(?i)^(true\|yes)$`)``` |
### ClientIP
The `ClientIP` matcher allows matching requests sent from the given client IP.
It only matches the request client IP and does not use the `X-Forwarded-For` header for matching.
| Behavior | Rule |
|-----------------------------------------------------------------|:------------------------------------------------------------------------|
| Match requests coming from a given IP (IPv4). | ```ClientIP(`10.76.105.11`)``` |
| Match requests coming from a given IP (IPv6). | ```ClientIP(`::1`)``` |
| Match requests coming from a given subnet (IPv4). | ```ClientIP(`192.168.1.0/24`)``` |
| Match requests coming from a given subnet (IPv6). | ```ClientIP(`fe80::/10`)``` |
### RuleSyntax
In Traefik v3 a new rule syntax has been introduced ([migration guide](../../../../migration/v3.md)). the `ruleSyntax` option allows to configure the rule syntax to be used for parsing the rule on a per-router basis. This allows to have heterogeneous router configurations and ease migration.
The default value of the `ruleSyntax` option is inherited from the `defaultRuleSyntax` option in the install configuration (formerly known as static configuration). By default, the `defaultRuleSyntax` static option is v3, meaning that the default rule syntax is also v3
#### Configuration Example
The configuration below uses the [File Provider (Structured)](../../../install-configuration/providers/others/file.md) to configure the `ruleSyntax` to allow `Router-v2` to use v2 syntax, while for `Router-v3` it is configured to use v3 syntax.
```yaml tab="Structured (YAML)"
## Dynamic configuration
http:
routers:
Router-v3:
rule: HostRegexp(`[a-z]+\\.traefik\\.com`)
ruleSyntax: v3
Router-v2:
rule: HostRegexp(`{subdomain:[a-z]+}.traefik.com`)
ruleSyntax: v2
```
```toml tab="Structured (TOML)"
## Dynamic configuration
[http.routers]
[http.routers.Router-v3]
rule = "HostRegexp(`[a-z]+\\.traefik\\.com`)"
ruleSyntax = v3
[http.routers.Router-v2]
rule = "HostRegexp(`{subdomain:[a-z]+}.traefik.com`)"
ruleSyntax = v2
```
```yaml tab="Labels"
labels:
- "traefik.http.routers.Router-v3.rule=HostRegexp(`[a-z]+\\.traefik\\.com`)"
- "traefik.http.routers.Router-v3.ruleSyntax=v3"
- "traefik.http.routers.Router-v2.rule=HostRegexp(`{subdomain:[a-z]+}.traefik.com`)"
- "traefik.http.routers.Router-v2.ruleSyntax=v2"
```
```json tab="Tags"
{
// ...
"Tags": [
"traefik.http.routers.Router-v3.rule=HostRegexp(`[a-z]+\\.traefik\\.com`)",
"traefik.http.routers.Router-v3.ruleSyntax=v3"
"traefik.http.routers.Router-v2.rule=HostRegexp(`{subdomain:[a-z]+}.traefik.com`)",
"traefik.http.routers.Router-v2.ruleSyntax=v2"
]
},
```
## Priority Calculation
??? info "How default priorities are computed"
```yaml tab="Structured (YAML)"
http:
routers:
Router-1:
rule: "HostRegexp(`[a-z]+\.traefik\.com`)"
# ...
Router-2:
rule: "Host(`foobar.traefik.com`)"
# ...
```
```toml tab="Structured (TOML)"
[http.routers]
[http.routers.Router-1]
rule = "HostRegexp(`[a-z]+\\.traefik\\.com`)"
# ...
[http.routers.Router-2]
rule = "Host(`foobar.traefik.com`)"
# ...
```
```yaml tab="Labels"
labels:
- "traefik.http.routers.Router-1.rule=HostRegexp(`[a-z]+\\.traefik\\.com`)"
- "traefik.http.routers.Router-2.rule=Host(`foobar.traefik.com`)"
```
```json tab="Tags"
{
// ...
"Tags": [
"traefik.http.routers.Router-1.rule=HostRegexp(`[a-z]+\\.traefik\\.com`)",
"traefik.http.routers.Router-2.rule=Host(`foobar.traefik.com`)"
]
}
```
In this case, all requests with host `foobar.traefik.com` will be routed through `Router-1` instead of `Router-2`.
| Name | Rule | Priority |
|----------|------------------------------------------|----------|
| Router-1 | ```HostRegexp(`[a-z]+\.traefik\.com`)``` | 34 |
| Router-2 | ```Host(`foobar.traefik.com`)``` | 26 |
The previous table shows that `Router-1` has a higher priority than `Router-2`.
To solve this issue, the priority must be set.
To avoid path overlap, routes are sorted, by default, in descending order using rules length.
The priority is directly equal to the length of the rule, and so the longest length has the highest priority.
A value of `0` for the priority is ignored: `priority: 0` means that the default rules length sorting is used.
Traefik reserves a range of priorities for its internal routers, the maximum user-defined router priority value is:
- `(MaxInt32 - 1000)` for 32-bit platforms,
- `(MaxInt64 - 1000)` for 64-bit platforms.
### Example
```yaml tab="Structured (YAML)"
## Dynamic configuration
http:
routers:
Router-1:
rule: "HostRegexp(`[a-z]+\\.traefik\\.com`)"
entryPoints:
- "web"
service: service-1
priority: 1
Router-2:
rule: "Host(`foobar.traefik.com`)"
entryPoints:
- "web"
priority: 2
service: service-2
```
```toml tab="Structured (TOML)"
## Dynamic configuration
[http.routers]
[http.routers.Router-1]
rule = "HostRegexp(`[a-z]+\\.traefik\\.com`)"
entryPoints = ["web"]
service = "service-1"
priority = 1
[http.routers.Router-2]
rule = "Host(`foobar.traefik.com`)"
entryPoints = ["web"]
priority = 2
service = "service-2"
```
```yaml tab="Labels"
labels:
- "traefik.http.routers.Router-1.rule=HostRegexp(`[a-z]+\\.traefik\\.com`)"
- "traefik.http.routers.Router-1.entryPoints=web"
- "traefik.http.routers.Router-1.service=service-1"
- "traefik.http.routers.Router-1.priority=1"
- "traefik.http.routers.Router-2.rule=Host(`foobar.traefik.com`)"
- "traefik.http.routers.Router-2.entryPoints=web"
- "traefik.http.routers.Router-2.service=service-2"
- "traefik.http.routers.Router-2.priority=2"
```
```json tab="Tags"
{
// ...
"Tags": [
"traefik.http.routers.Router-1.rule=HostRegexp(`[a-z]+\\.traefik\\.com`)",
"traefik.http.routers.Router-1.entryPoints=web",
"traefik.http.routers.Router-1.service=service-1",
"traefik.http.routers.Router-1.priority=1"
"traefik.http.routers.Router-2.rule=Host(`foobar.traefik.com`)",
"traefik.http.routers.Router-2.entryPoints=web",
"traefik.http.routers.Router-2.service=service-2",
"traefik.http.routers.Router-2.priority=2"
]
}
```
In the example above, the priority is configured to allow `Router-2` to handle requests with the `foobar.traefik.com` host.

10
docs/content/reference/routing-configuration/http/tls/overview.md Normal file
View file

@ -0,0 +1,10 @@
---
title: "Traefik TLS Documentation"
description: "Learn how to configure the transport layer security (TLS) connection in Traefik Proxy. Read the technical documentation."
---
Traefik's TLS configuration defines how TLS negotiation is handled for incoming connections.
The next section of this documentation explains how to configure TLS connections through a definition in the dynamic configuration and how to configure TLS options, and certificates stores.
{!traefik-for-business-applications.md!}

158
docs/content/reference/routing-configuration/http/tls/tls-certificates.md Normal file
View file

@ -0,0 +1,158 @@
---
title: "Traefik TLS Certificates Documentation"
description: "Learn how to configure the transport layer security (TLS) connection in Traefik Proxy. Read the technical documentation."
---
!!! info
When a router has to handle HTTPS traffic, it should be specified with a `tls` field of the router definition.
## Certificates Definition
### Automated
See the [Let's Encrypt](../../../install-configuration/tls/certificate-resolvers/acme.md) page.
### User defined
To add / remove TLS certificates, even when Traefik is already running, their definition can be added to the [dynamic configuration](../../dynamic-configuration-methods.md#providing-dynamic-routing-configuration-to-traefik), in the `[[tls.certificates]]` section:
```yaml tab="Structured (YAML)"
tls:
certificates:
- certFile: /path/to/domain.cert
keyFile: /path/to/domain.key
- certFile: /path/to/other-domain.cert
keyFile: /path/to/other-domain.key
```
```toml tab="Structured (TOML)"
[[tls.certificates]]
certFile = "/path/to/domain.cert"
keyFile = "/path/to/domain.key"
[[tls.certificates]]
certFile = "/path/to/other-domain.cert"
keyFile = "/path/to/other-domain.key"
```
!!! important "Restriction"
In the above example, we've used the [file provider](../../../install-configuration/providers/others/file.md) to handle these definitions.
It is the only available method to configure the certificates (as well as the options and the stores).
However, in [Kubernetes](../../../install-configuration/providers/kubernetes/kubernetes-crd.md), the certificates can and must be provided by [secrets](https://kubernetes.io/docs/concepts/configuration/secret/).
## Certificates Stores
In Traefik, certificates are grouped together in certificates stores.
!!! important "Restriction"
Any store definition other than the default one (named `default`) will be ignored,
and there is therefore only one globally available TLS store.
In the `tls.certificates` section, a list of stores can then be specified to indicate where the certificates should be stored:
```yaml tab="Structured (YAML)"
tls:
certificates:
- certFile: /path/to/domain.cert
keyFile: /path/to/domain.key
stores:
- default
# Note that since no store is defined,
# the certificate below will be stored in the `default` store.
- certFile: /path/to/other-domain.cert
keyFile: /path/to/other-domain.key
```
```toml tab="Structured (TOML)"
[[tls.certificates]]
certFile = "/path/to/domain.cert"
keyFile = "/path/to/domain.key"
stores = ["default"]
[[tls.certificates]]
# Note that since no store is defined,
# the certificate below will be stored in the `default` store.
certFile = "/path/to/other-domain.cert"
keyFile = "/path/to/other-domain.key"
```
!!! important "Restriction"
The `stores` list will actually be ignored and automatically set to `["default"]`.
### Default Certificate
Traefik can use a default certificate for connections without a SNI, or without a matching domain.
This default certificate should be defined in a TLS store:
```yaml tab="Structured (YAML)"
tls:
stores:
default:
defaultCertificate:
certFile: path/to/cert.crt
keyFile: path/to/cert.key
```
```toml tab="Structured (TOML)"
[tls.stores]
[tls.stores.default]
[tls.stores.default.defaultCertificate]
certFile = "path/to/cert.crt"
keyFile = "path/to/cert.key"
```
If no `defaultCertificate` is provided, Traefik will use the generated one.
### ACME Default Certificate
You can configure Traefik to use an ACME provider (like Let's Encrypt) to generate the default certificate.
The configuration to resolve the default certificate should be defined in a TLS store:
!!! important "Precedence with the `defaultGeneratedCert` option"
The `defaultGeneratedCert` definition takes precedence over the ACME default certificate configuration.
```yaml tab="Structured (YAML)"
tls:
stores:
default:
defaultGeneratedCert:
resolver: myresolver
domain:
main: example.org
sans:
- foo.example.org
- bar.example.org
```
```toml tab="Structured (TOML)"
[tls.stores]
[tls.stores.default.defaultGeneratedCert]
resolver = "myresolver"
[tls.stores.default.defaultGeneratedCert.domain]
main = "example.org"
sans = ["foo.example.org", "bar.example.org"]
```
```yaml tab="Labels"
labels:
- "traefik.tls.stores.default.defaultgeneratedcert.resolver=myresolver"
- "traefik.tls.stores.default.defaultgeneratedcert.domain.main=example.org"
- "traefik.tls.stores.default.defaultgeneratedcert.domain.sans=foo.example.org, bar.example.org"
```
```json tab="Tags"
{
"Name": "default",
"Tags": [
"traefik.tls.stores.default.defaultgeneratedcert.resolver=myresolver",
"traefik.tls.stores.default.defaultgeneratedcert.domain.main=example.org",
"traefik.tls.stores.default.defaultgeneratedcert.domain.sans=foo.example.org, bar.example.org"
]
}
```
{!traefik-for-business-applications.md!}

228
docs/content/reference/routing-configuration/http/tls/tls-options.md Normal file
View file

@ -0,0 +1,228 @@
---
title: "Traefik TLS Options Documentation"
description: "Learn how to configure the transport layer security (TLS) connection in Traefik Proxy. Read the technical documentation."
---
The TLS options allow one to configure some parameters of the TLS connection.
!!! important "'default' TLS Option"
The `default` option is special.
When no tls options are specified in a tls router, the `default` option is used.
When specifying the `default` option explicitly, make sure not to specify provider namespace as the `default` option does not have one.
Conversely, for cross-provider references, for example, when referencing the file provider from a docker label,
you must specify the provider namespace, for example:
`traefik.http.routers.myrouter.tls.options=myoptions@file`
!!! important "Providers"
TLS options are not supported by label or tag-based providers. However, you can define them when using a [KV provider](../../other-providers/kv.md).
### Minimum TLS Version
```yaml tab="Structured (YAML)"
# Dynamic configuration
tls:
options:
default:
minVersion: VersionTLS12
mintls13:
minVersion: VersionTLS13
```
```toml tab="Structured (TOML)"
# Dynamic configuration
[tls.options]
[tls.options.default]
minVersion = "VersionTLS12"
[tls.options.mintls13]
minVersion = "VersionTLS13"
```
### Maximum TLS Version
We discourage the use of this setting to disable TLS1.3.
The recommended approach is to update the clients to support TLS1.3.
```yaml tab="Structured (YAML)"
# Dynamic configuration
tls:
options:
default:
maxVersion: VersionTLS13
maxtls12:
maxVersion: VersionTLS12
```
```toml tab="Structured (TOML)"
# Dynamic configuration
[tls.options]
[tls.options.default]
maxVersion = "VersionTLS13"
[tls.options.maxtls12]
maxVersion = "VersionTLS12"
```
### Cipher Suites
See [cipherSuites](https://godoc.org/crypto/tls#pkg-constants) for more information.
```yaml tab="Structured (YAML)"
# Dynamic configuration
tls:
options:
default:
cipherSuites:
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
```
```toml tab="Structured (TOML)"
# Dynamic configuration
[tls.options]
[tls.options.default]
cipherSuites = [
"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
]
```
!!! important "TLS 1.3"
Cipher suites defined for TLS 1.2 and below cannot be used in TLS 1.3, and vice versa. (<https://tools.ietf.org/html/rfc8446>)
With TLS 1.3, the cipher suites are not configurable (all supported cipher suites are safe in this case).
<https://golang.org/doc/go1.12#tls_1_3>
### Curve Preferences
This option allows to set the preferred elliptic curves in a specific order.
The names of the curves defined by [`crypto`](https://godoc.org/crypto/tls#CurveID) (e.g. `CurveP521`) and the [RFC defined names](https://tools.ietf.org/html/rfc8446#section-4.2.7) (e. g. `secp521r1`) can be used.
See [CurveID](https://godoc.org/crypto/tls#CurveID) for more information.
```yaml tab="Structured (YAML)"
# Dynamic configuration
tls:
options:
default:
curvePreferences:
- CurveP521
- CurveP384
```
```toml tab="Structured (TOML)"
# Dynamic configuration
[tls.options]
[tls.options.default]
curvePreferences = ["CurveP521", "CurveP384"]
```
### Strict SNI Checking
With strict SNI checking enabled, Traefik won't allow connections from clients that do not specify a server_name extension
or don't match any of the configured certificates.
The default certificate is irrelevant on that matter.
```yaml tab="Structured (YAML)"
# Dynamic configuration
tls:
options:
default:
sniStrict: true
```
```toml tab="Structured (TOML)"
# Dynamic configuration
[tls.options]
[tls.options.default]
sniStrict = true
```
### ALPN Protocols
_Optional, Default="h2, http/1.1, acme-tls/1"_
This option allows to specify the list of supported application level protocols for the TLS handshake,
in order of preference.
If the client supports ALPN, the selected protocol will be one from this list,
and the connection will fail if there is no mutually supported protocol.
```yaml tab="Structured (YAML)"
# Dynamic configuration
tls:
options:
default:
alpnProtocols:
- http/1.1
- h2
```
```toml tab="Structured (TOML)"
# Dynamic configuration
[tls.options]
[tls.options.default]
alpnProtocols = ["http/1.1", "h2"]
```
### Client Authentication (mTLS)
Traefik supports mutual authentication, through the `clientAuth` section.
For authentication policies that require verification of the client certificate, the certificate authority for the certificates should be set in `clientAuth.caFiles`.
In Kubernetes environment, CA certificate can be set in `clientAuth.secretNames`. See [TLSOption resource](../../kubernetes/crd/http/tlsoption.md) for more details.
The `clientAuth.clientAuthType` option governs the behaviour as follows:
| Option | Operation |
| --------- | ----------- |
| `NoClientCert` | Disregards any client certificate.|
| `RequestClientCert` | Asks for a certificate but proceeds anyway if none is provided. |
| `RequireAnyClientCert` | Requires a certificate but does not verify if it is signed by a CA listed in `clientAuth.caFiles` or in `clientAuth.secretNames`. |
| `VerifyClientCertIfGiven` | If a certificate is provided, verifies if it is signed by a CA listed in `clientAuth.caFiles` or in `clientAuth.secretNames`. Otherwise proceeds without any certificate. |
| `RequireAndVerifyClientCert` | requires a certificate, which must be signed by a CA listed in `clientAuth.caFiles` or in `clientAuth.secretNames`. |
```yaml tab="Structured (YAML)"
# Dynamic configuration
tls:
options:
default:
clientAuth:
# in PEM format. each file can contain multiple CAs.
caFiles:
- tests/clientca1.crt
- tests/clientca2.crt
clientAuthType: RequireAndVerifyClientCert
```
```toml tab="Structured (TOML)"
# Dynamic configuration
[tls.options]
[tls.options.default]
[tls.options.default.clientAuth]
# in PEM format. each file can contain multiple CAs.
caFiles = ["tests/clientca1.crt", "tests/clientca2.crt"]
clientAuthType = "RequireAndVerifyClientCert"
```
{!traefik-for-business-applications.md!}