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

Middleware documentation fixes

Browse source
This commit is contained in:
Brendan Le Glaunec 2021-02-11 14:34:04 +01:00 committed by GitHub
parent 5ef6297daa
commit 502c88ee3f
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
24 changed files with 536 additions and 490 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
docs/content/middlewares/addprefix.md
View file

@ -5,7 +5,7 @@ Prefixing the Path
![AddPrefix](../assets/img/middleware/addprefix.png)
The AddPrefix middleware updates the URL Path of the request before forwarding it.
The AddPrefix middleware updates the path of a request before forwarding it.
## Configuration Examples
@ -64,4 +64,4 @@ http:
### `prefix`
`prefix` is the string to add before the current path in the requested URL.
It should include the leading slash (`/`).
It should include a leading slash (`/`).

4
docs/content/middlewares/basicauth.md
View file

@ -5,7 +5,7 @@ Adding Basic Authentication
![BasicAuth](../assets/img/middleware/basicauth.png)
The BasicAuth middleware is a quick way to restrict access to your services to known users.
The BasicAuth middleware restricts access to your services to known users.
## Configuration Examples
@ -81,7 +81,7 @@ Passwords must be hashed using MD5, SHA1, or BCrypt.
### `users`
The `users` option is an array of authorized users. Each user will be declared using the `name:hashed-password` format.
The `users` option is an array of authorized users. Each user must be declared using the `name:hashed-password` format.
!!! note ""

34
docs/content/middlewares/buffering.md
View file

@ -5,22 +5,22 @@ How to Read the Request before Forwarding It
![Buffering](../assets/img/middleware/buffering.png)
The Buffering middleware gives you control on how you want to read the requests before sending them to services.
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 limit.
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 deal with large data (multipart/form-data for example), and can minimize time spent sending data to a service.
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="Docker"
# Sets the maximum request body to 2Mb
# Sets the maximum request body to 2MB
labels:
- "traefik.http.middlewares.limit.buffering.maxRequestBodyBytes=2000000"
```
```yaml tab="Kubernetes"
# Sets the maximum request body to 2Mb
# Sets the maximum request body to 2MB
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
@ -31,7 +31,7 @@ spec:
```
```yaml tab="Consul Catalog"
# Sets the maximum request body to 2Mb
# Sets the maximum request body to 2MB
- "traefik.http.middlewares.limit.buffering.maxRequestBodyBytes=2000000"
```
@ -42,20 +42,20 @@ spec:
```
```yaml tab="Rancher"
# Sets the maximum request body to 2Mb
# Sets the maximum request body to 2MB
labels:
- "traefik.http.middlewares.limit.buffering.maxRequestBodyBytes=2000000"
```
```toml tab="File (TOML)"
# Sets the maximum request body to 2Mb
# Sets the maximum request body to 2MB
[http.middlewares]
[http.middlewares.limit.buffering]
maxRequestBodyBytes = 2000000
```
```yaml tab="File (YAML)"
# Sets the maximum request body to 2Mb
# Sets the maximum request body to 2MB
http:
middlewares:
limit:
@ -67,9 +67,9 @@ http:
### `maxRequestBodyBytes`
With the `maxRequestBodyBytes` option, you can configure the maximum allowed body size for the request (in Bytes).
The `maxRequestBodyBytes` option configures the maximum allowed body size for the request (in bytes).
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.
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.
```yaml tab="Docker"
labels:
@ -117,7 +117,7 @@ http:
### `memRequestBodyBytes`
You can configure a threshold (in Bytes) from which the request will be buffered on disk instead of in memory with the `memRequestBodyBytes` option.
You can configure a threshold (in bytes) from which the request will be buffered on disk instead of in memory with the `memRequestBodyBytes` option.
```yaml tab="Docker"
labels:
@ -165,7 +165,7 @@ http:
### `maxResponseBodyBytes`
With the `maxResponseBodyBytes` option, you can configure the maximum allowed response size from the service (in Bytes).
The `maxResponseBodyBytes` option configures the maximum allowed response size from the service (in bytes).
If the response exceeds the allowed size, it is not forwarded to the client. The client gets a `413 (Request Entity Too Large) response` instead.
@ -215,7 +215,7 @@ http:
### `memResponseBodyBytes`
You can configure a threshold (in Bytes) from which the response will be buffered on disk instead of in memory with the `memResponseBodyBytes` option.
You can configure a threshold (in bytes) from which the response will be buffered on disk instead of in memory with the `memResponseBodyBytes` option.
```yaml tab="Docker"
labels:
@ -263,9 +263,9 @@ http:
### `retryExpression`
You can have the Buffering middleware replay the request with the help of the `retryExpression` option.
You can have the Buffering middleware replay the request using `retryExpression`.
??? example "Retries once in case of a network error"
??? example "Retries once in the case of a network error"
```yaml tab="Docker"
labels:
@ -315,4 +315,4 @@ The retry expression is defined as a logical combination of the functions below
- `Attempts()` number of attempts (the first one counts)
- `ResponseCode()` response code of the service
- `IsNetworkError()` - if the response code is related to networking error
- `IsNetworkError()` whether the response code is related to networking error

8
docs/content/middlewares/chain.md
View file

@ -5,12 +5,12 @@ When One Isn't Enough
![Chain](../assets/img/middleware/chain.png)
The Chain middleware enables you to define reusable combinations of other pieces of middleware.
The Chain middleware enables you to define reusable combinations of other pieces of middleware.
It makes reusing the same groups easier.
## Configuration Example
Example "A Chain for WhiteList, BasicAuth, and HTTPS"
Below is an example of a Chain containing `WhiteList`, `BasicAuth`, and `RedirectScheme`.
```yaml tab="Docker"
labels:
@ -30,11 +30,9 @@ kind: IngressRoute
metadata:
name: test
namespace: default
spec:
entryPoints:
- web
routes:
- match: Host(`mydomain`)
kind: Rule
@ -148,7 +146,7 @@ labels:
```
```yaml tab="File (YAML)"
# ...
# ...
http:
routers:
router1:

70
docs/content/middlewares/circuitbreaker.md
View file

@ -3,27 +3,24 @@
Don't Waste Time Calling Unhealthy Services
{: .subtitle }
![CircuitBreaker](../assets/img/middleware/circuitbreaker.png)
![CircuitBreaker](../assets/img/middleware/circuitbreaker.png)
The circuit breaker protects your system from stacking requests to unhealthy services (resulting in cascading failures).
The circuit breaker protects your system from 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 becomes open and the requests are no longer forwarded (but handled by a fallback mechanism).
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.
To assess if your system is healthy, the circuit breaker constantly monitors the services.
!!! note ""
- The CircuitBreaker only analyses what happens _after_ it is positioned in the middleware chain. What happens _before_ has no impact on its state.
- The CircuitBreaker only affects the routers that use it. Routers that don't use the CircuitBreaker won't be affected by its state.
The CircuitBreaker only analyzes what happens _after_ its position within the middleware chain. What happens _before_ has no impact on its state.
!!! important
Each router will eventually gets its own instance of a given circuit breaker.
If two different routers refer to the same circuit breaker definition, they will get one instance each.
It means that one circuit breaker can be open while the other stays closed: their state is not shared.
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
@ -90,70 +87,71 @@ There are three possible states for your circuit breaker:
While the circuit is closed, the circuit breaker only collects metrics to analyze the behavior of the requests.
At specified intervals (`checkPeriod`), it will evaluate `expression` to decide if its state must change.
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`.
After this duration, it will enter the recovering state.
After this duration, it enters the recovering state.
### Recovering
While recovering, the circuit breaker will progressively send requests to your service again (in a linear way, for `RecoveryDuration`).
If your service fails during recovery, the circuit breaker becomes open again.
If the service operates normally during the whole recovering duration, then the circuit breaker returns to close.
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.
## Configuration Options
### Configuring the Trigger
You can specify an `expression` that, once matched, will trigger the circuit breaker (and apply the fallback mechanism instead of calling your services).
You can specify an `expression` that, once matched, opens the circuit breaker and applies the fallback mechanism instead of calling your services.
The `expression` can check three different metrics:
The `expression` option can check three different metrics:
- The network error ratio (`NetworkErrorRatio`)
- The status code ratio (`ResponseCodeRatio`)
- The latency at quantile, in milliseconds (`LatencyAtQuantileMS`)
- The latency at a quantile in milliseconds (`LatencyAtQuantileMS`)
#### `NetworkErrorRatio`
If you want the circuit breaker to trigger at a 30% ratio of network errors, the expression will be `NetworkErrorRatio() > 0.30`
If you want the circuit breaker to open at a 30% ratio of network errors, the `expression` is `NetworkErrorRatio() > 0.30`
#### `ResponseCodeRatio`
You can trigger the circuit breaker based on the ratio of a given range of status codes.
You can configure the circuit breaker to open based on the ratio of a given range of status codes.
The `ResponseCodeRatio` accepts four parameters, `from`, `to`, `dividedByFrom`, `dividedByTo`.
The operation that will be computed is sum(`to` -> `from`) / sum (`dividedByFrom` -> `dividedByTo`).
!!! note ""
If sum (`dividedByFrom` -> `dividedByTo`) equals 0, then `ResponseCodeRatio` returns 0.
`from`is inclusive, `to` is exclusive.
For example, the expression `ResponseCodeRatio(500, 600, 0, 600) > 0.25` will trigger the circuit breaker if 25% of the requests returned a 5XX status (amongst the request that returned a status code from 0 to 5XX).
If sum (`dividedByFrom` -> `dividedByTo`) equals 0, then `ResponseCodeRatio` returns 0.
`from`is inclusive, `to` is exclusive.
For example, the expression `ResponseCodeRatio(500, 600, 0, 600) > 0.25` will trigger 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`
You can trigger the circuit breaker when a given proportion of your requests become too slow.
You can configure the circuit breaker to open when a given proportion of your requests become too slow.
For example, the expression `LatencyAtQuantileMS(50.0) > 100` will trigger the circuit breaker when the median latency (quantile 50) reaches 100MS.
For example, the expression `LatencyAtQuantileMS(50.0) > 100` opens the circuit breaker when the median latency (quantile 50) reaches 100ms.
!!! note ""
You must provide a float number (with the trailing .0) for the quantile value
#### Using multiple metrics
You must provide a floating point number (with the trailing .0) for the quantile value
You can combine multiple metrics using operators in your expression.
#### 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%.
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
@ -168,8 +166,8 @@ Here is the list of supported operators:
### 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.
The fallback mechanism returns a `HTTP 503 Service Unavailable` to the client instead of calling the target service.
This behavior cannot be configured.
### `CheckPeriod`
@ -182,6 +180,6 @@ By default, `FallbackDuration` is 10 seconds. This value cannot be configured.
### `RecoveringDuration`
The duration of the recovering mode (recovering state).
The duration of the recovering mode (recovering state).
By default, `RecoveringDuration` is 10 seconds. This value cannot be configured.
By default, `RecoveringDuration` is 10 seconds. This value cannot be configured.

16
docs/content/middlewares/compress.md
View file

@ -1,11 +1,11 @@
# Compress
Compressing the Response before Sending it to the Client
Compress Responses before Sending them to the Client
{: .subtitle }
![Compress](../assets/img/middleware/compress.png)
The Compress middleware enables the gzip compression.
The Compress middleware uses gzip compression.
## Configuration Examples
@ -57,16 +57,16 @@ http:
```
!!! info
Responses are compressed when:
Responses are compressed when the following criteria are all met:
* The response body is larger than `1400` bytes.
* The `Accept-Encoding` request header contains `gzip`.
* The response is not already compressed, i.e. the `Content-Encoding` response header is not already set.
If 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 accordingly the `Content-Type` header with the detected MIME type.
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.
## Configuration Options
### `excludedContentTypes`

13
docs/content/middlewares/contenttype.md
View file

@ -1,18 +1,19 @@
# ContentType
Handling ContentType auto-detection
Handling Content-Type auto-detection
{: .subtitle }
The Content-Type middleware - or rather its unique `autoDetect` option -
The Content-Type middleware - or rather its `autoDetect` option -
specifies whether to let the `Content-Type` header,
if it has not been set by the backend,
if it has not been defined by the backend,
be automatically set to a value derived from the contents of the response.
As a proxy, the default behavior should be to leave the header alone,
regardless of what the backend did with it.
However, the historic default was to always auto-detect and set the header if it was nil,
and it is going to be kept that way in order to support users currently relying on it.
However, the historic default was to always auto-detect and set the header if it was not already defined,
and altering this behavior would be a breaking change which would impact many users.
This middleware exists to enable the correct behavior until at least the default one can be changed in a future version.
!!! info
@ -21,7 +22,7 @@ This middleware exists to enable the correct behavior until at least the default
is still to automatically set the `Content-Type` header.
Therefore, given the default value of the `autoDetect` option (false),
simply enabling this middleware for a router switches the router's behavior.
The scope of the Content-Type middleware is the MIME type detection done by the core of Traefik (the server part).
Therefore, it has no effect against any other `Content-Type` header modifications (e.g.: in another middleware such as compress).

16
docs/content/middlewares/digestauth.md
View file

@ -1,11 +1,11 @@
# DigestAuth
Adding Digest Authentication
{: .subtitle }
{: .subtitle }
![BasicAuth](../assets/img/middleware/digestauth.png)
The DigestAuth middleware is a quick way to restrict access to your services to known users.
The DigestAuth middleware restricts access to your services to known users.
## Configuration Examples
@ -66,8 +66,8 @@ http:
## Configuration Options
!!! tip
!!! tip
Use `htdigest` to generate passwords.
### `users`
@ -75,9 +75,9 @@ http:
The `users` option is an array of authorized users. Each user will be declared using the `name:realm:encoded-password` format.
!!! note ""
- If both `users` and `usersFile` are provided, the two are merged. The contents of `usersFile` have precedence over the values in `users`.
- For security reasons, the field `users` doesn't exist for Kubernetes IngressRoute, and one should use the `secret` field instead.
- For security reasons, the field `users` doesn't exist for Kubernetes IngressRoute, and one should use the `secret` field instead.
```yaml tab="Docker"
labels:
@ -146,7 +146,7 @@ The `usersFile` option is the path to an external file that contains the authori
The file content is a list of `name:realm:encoded-password`.
!!! note ""
- If both `users` and `usersFile` are provided, the two are merged. The contents of `usersFile` have precedence over the values in `users`.
- Because it does not make much sense to refer to a file path on Kubernetes, the `usersFile` field doesn't exist for Kubernetes IngressRoute, and one should use the `secret` field instead.
@ -215,7 +215,7 @@ http:
### `realm`
You can customize the realm for the authentication with the `realm` option. The default value is `traefik`.
You can customize the realm for the authentication with the `realm` option. The default value is `traefik`.
```yaml tab="Docker"
labels:

18
docs/content/middlewares/errorpages.md
View file

@ -85,28 +85,30 @@ http:
# ... definition of error-handler-service and my-service
```
!!! note ""
!!! note ""
In this example, the error page URL is based on the status code (`query=/{status}.html`).
## Configuration Options
### `status`
The `status` that will trigger the error page.
The `status` option defines which status or range of statuses should result in an error page.
The status code ranges are inclusive (`500-599` will trigger with every code between `500` and `599`, `500` and `599` included).
!!! note ""
You can define either a status code like `500` or ranges with a syntax like `500-599`.
!!! note ""
You can define either a status code as a number (`500`) or ranges by separating two codes with a dash (`500-599`).
### `service`
The service that will serve the new requested error page.
!!! note ""
In kubernetes, you need to reference a kubernetes service instead of a traefik service.
!!! note ""
In Kubernetes, you need to reference a Kubernetes Service instead of a Traefik service.
### `query`
The URL for the error page (hosted by `service`). You can use `{status}` in the query, that will be replaced by the received status code.
The URL for the error page (hosted by `service`). You can use the `{status}` variable in the `query` option in order to insert the status code in the URL.

45
docs/content/middlewares/forwardauth.md
View file

@ -1,12 +1,12 @@
# ForwardAuth
Using an External Service to Check for Credentials
Using an External Service to Forward Authentication
{: .subtitle }
![AuthForward](../assets/img/middleware/authforward.png)
The ForwardAuth middleware delegate the authentication to an external service.
If the service response code is 2XX, access is granted and the original request is performed.
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 Examples
@ -125,7 +125,7 @@ http:
### `trustForwardHeader`
Set the `trustForwardHeader` option to `true` to trust all the existing `X-Forwarded-*` headers.
Set the `trustForwardHeader` option to `true` to trust all `X-Forwarded-*` headers.
```yaml tab="Docker"
labels:
@ -176,7 +176,8 @@ http:
### `authResponseHeaders`
The `authResponseHeaders` option is the list of the headers to copy from the authentication server to the request. All incoming request's headers in this list are deleted from the request before any copy happens.
The `authResponseHeaders` option is the list of headers to copy from the authentication server response and set on
forwarded request, replacing any existing conflicting headers.
```yaml tab="Docker"
labels:
@ -231,9 +232,10 @@ http:
### `authResponseHeadersRegex`
The `authResponseHeadersRegex` option is the regex to match the headers that should be copied from the authentication server to the request. All incoming request's headers matching this regex are deleted from the request before any copy happens.
It allows partial matching of the regular expression against the header's key.
You should use start of string (`^`) and end of string (`$`) anchors to ensure a full match against the header's key.
The `authResponseHeadersRegex` option is the regex to match headers to copy from the authentication server response and
set on forwarded request, after stripping all headers that match the regex.
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.
```yaml tab="Docker"
labels:
@ -286,7 +288,7 @@ http:
The `authRequestHeaders` option is the list of the headers to copy from the request to the authentication server.
It allows filtering headers that should not be passed to the authentication server.
If not set or empty then all request headers will be passed.
If not set or empty then all request headers are passed.
```yaml tab="Docker"
labels:
@ -409,12 +411,15 @@ http:
#### `tls.caOptional`
Policy used for the secured connection with TLS Client Authentication to the authentication server.
Requires `tls.ca` to be defined.
The value of `tls.caOptional` defines which policy should be used for the secure connection with TLS Client Authentication to the authentication server.
- `true`: VerifyClientCertIfGiven
- `false`: RequireAndVerifyClientCert
- if `tls.ca` is undefined NoClientCert
!!! warning ""
If `tls.ca` is undefined, this option will be ignored, and no client certificate will be requested during the handshake. Any provided certificate will thus never be verified.
When this option is set to `true`, a client certificate is requested during the handshake but is not required. If a certificate is sent, it is required to be valid.
When this option is set to `false`, a client certificate is requested during the handshake, and at least one valid certificate should be sent by the client.
```yaml tab="Docker"
labels:
@ -468,7 +473,7 @@ http:
#### `tls.cert`
Public certificate used for the secured connection to the authentication server.
The public certificate used for the secure connection to the authentication server.
```yaml tab="Docker"
labels:
@ -538,11 +543,12 @@ http:
```
!!! info
For security reasons, the field doesn't exist for Kubernetes IngressRoute, and one should use the `secret` field instead.
For security reasons, the field does not exist for Kubernetes IngressRoute, and one should use the `secret` field instead.
#### `tls.key`
Private certificate used for the secure connection to the authentication server.
The private certificate used for the secure connection to the authentication server.
```yaml tab="Docker"
labels:
@ -612,11 +618,12 @@ http:
```
!!! info
For security reasons, the field doesn't exist for Kubernetes IngressRoute, and one should use the `secret` field instead.
For security reasons, the field does not exist for Kubernetes IngressRoute, and one should use the `secret` field instead.
#### `tls.insecureSkipVerify`
If `insecureSkipVerify` is `true`, TLS for the connection to authentication server accepts any certificate presented by the server and any host name in that certificate.
If `insecureSkipVerify` is `true`, the TLS connection to the authentication server accepts any certificate presented by the server regardless of the hostnames it covers.
```yaml tab="Docker"
labels:

112
docs/content/middlewares/headers.md
View file

@ -1,17 +1,17 @@
# Headers
# Headers
Adding Headers to the Request / Response
Managing Request/Response headers
{: .subtitle }
![Headers](../assets/img/middleware/headers.png)
The Headers middleware can manage the requests/responses headers.
The Headers middleware manages the headers of requests and responses.
## Configuration Examples
### Adding Headers to the Request and the Response
Add the `X-Script-Name` header to the proxied request and the `X-Custom-Response-Header` to 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="Docker"
labels:
@ -72,8 +72,8 @@ http:
### Adding and Removing Headers
`X-Script-Name` header added to the proxied request, the `X-Custom-Request-Header` header removed from the request,
and the `X-Custom-Response-Header` header removed from the response.
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.
Please note that it is not possible to remove headers through the use of labels (Docker, Rancher, Marathon, ...) for now.
@ -135,8 +135,8 @@ http:
### Using Security Headers
Security related headers (HSTS headers, SSL redirection, Browser XSS filter, etc) can be added and configured in a manner similar to the custom headers above.
This functionality allows for some easy security features to quickly be set.
Security-related headers (HSTS headers, SSL redirection, 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="Docker"
labels:
@ -173,14 +173,14 @@ labels:
- "traefik.http.middlewares.testheader.headers.sslredirect=true"
```
```toml tab="File (TOML)"
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.testHeader.headers]
frameDeny = true
sslRedirect = true
```
```yaml tab="File (YAML)"
```yaml tab="File (YAML)"
http:
middlewares:
testHeader:
@ -244,7 +244,7 @@ labels:
- "traefik.http.middlewares.testheader.headers.addvaryheader=true"
```
```toml tab="File (TOML)"
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.testHeader.headers]
accessControlAllowMethods= ["GET", "OPTIONS", "PUT"]
@ -274,18 +274,20 @@ http:
### General
!!! warning
If the custom header name is the same as one header name of the request or response, it will be replaced.
Custom headers will overwrite existing headers if they have identical names.
!!! note ""
The detailed documentation for the security headers can be found in [unrolled/secure](https://github.com/unrolled/secure#available-options).
The detailed documentation for security headers can be found in [unrolled/secure](https://github.com/unrolled/secure#available-options).
### `customRequestHeaders`
The `customRequestHeaders` option lists the Header names and values to apply to the request.
The `customRequestHeaders` option lists the header names and values to apply to the request.
### `customResponseHeaders`
The `customResponseHeaders` option lists the Header names and values to apply to the response.
The `customResponseHeaders` option lists the header names and values to apply to the response.
### `accessControlAllowCredentials`
@ -303,25 +305,26 @@ The `accessControlAllowMethods` indicates which methods can be used during requ
The `accessControlAllowOriginList` indicates whether a resource can be shared by returning different values.
A wildcard origin `*` can also be configured, and will match all requests.
If this value is set by a backend server, it will be overwritten by Traefik
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 on:
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).
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 will allow all origin that contains any match of a regular expression in the `accessControlAllowOriginList`.
It allows all origins that contain any match of a regular expression in the `accessControlAllowOriginList`.
!!! tip
Regular expressions 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).
### `accessControlExposeHeaders`
@ -330,66 +333,66 @@ The `accessControlExposeHeaders` indicates which headers are safe to expose to t
### `accessControlMaxAge`
The `accessControlMaxAge` indicates how long (in seconds) a preflight request can be cached.
The `accessControlMaxAge` indicates how many seconds a preflight request can be cached for.
### `addVaryHeader`
The `addVaryHeader` is 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.
The `addVaryHeader` is 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.
### `allowedHosts`
### `allowedHosts`
The `allowedHosts` option lists fully qualified domain names that are allowed.
### `hostsProxyHeaders`
### `hostsProxyHeaders`
The `hostsProxyHeaders` option is a set of header keys that may hold a proxied hostname value for the request.
### `sslRedirect`
### `sslRedirect`
The `sslRedirect` is set to true, then only allow https requests.
The `sslRedirect` only allow HTTPS requests when set to `true`.
### `sslTemporaryRedirect`
Set the `sslTemporaryRedirect` to `true` to force an SSL redirection using a 302 (instead of a 301).
### `sslHost`
Set `sslTemporaryRedirect` to `true` to force an SSL redirection using a 302 (instead of a 301).
The `sslHost` option is the host name that is used to redirect http requests to https.
### `sslHost`
### `sslProxyHeaders`
The `sslHost` option is the host name that is used to redirect HTTP requests to HTTPS.
The `sslProxyHeaders` option is set of header keys with associated values that would indicate a valid https request.
Useful when using other proxies with header like: `"X-Forwarded-Proto": "https"`.
### `sslProxyHeaders`
### `sslForceHost`
The `sslProxyHeaders` option is 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"`).
Set `sslForceHost` to true and set SSLHost to forced requests to use `SSLHost` even the ones that are already using SSL.
### `sslForceHost`
### `stsSeconds`
Set `sslForceHost` to `true` and set `sslHost` to force requests to use `SSLHost` regardless of whether they already use SSL.
The `stsSeconds` is the max-age of the Strict-Transport-Security header.
If set to 0, would NOT include the header.
### `stsSeconds`
### `stsIncludeSubdomains`
The `stsSeconds` is the max-age of the `Strict-Transport-Security` header.
If set to `0`, the header is not set.
The `stsIncludeSubdomains` is set to true, the `includeSubDomains` directive will be appended to the Strict-Transport-Security header.
### `stsIncludeSubdomains`
### `stsPreload`
If the `stsIncludeSubdomains` is set to `true`, the `includeSubDomains` directive is appended to the `Strict-Transport-Security` header.
Set `stsPreload` to true to have the `preload` flag appended to the Strict-Transport-Security header.
### `stsPreload`
Set `stsPreload` to `true` to have the `preload` flag appended to the `Strict-Transport-Security` header.
### `forceSTSHeader`
Set `forceSTSHeader` to true, to add the STS header even when the connection is HTTP.
Set `forceSTSHeader` to `true` to add the STS header even when the connection is HTTP.
### `frameDeny`
### `frameDeny`
Set `frameDeny` to true to add the `X-Frame-Options` header with the value of `DENY`.
### `customFrameOptionsValue`
Set `frameDeny` to `true` to add the `X-Frame-Options` header with the value of `DENY`.
### `customFrameOptionsValue`
The `customFrameOptionsValue` allows the `X-Frame-Options` header value to be set with a custom value.
This overrides the FrameDeny option.
This overrides the `FrameDeny` option.
### `contentTypeNosniff`
@ -402,7 +405,7 @@ Set `browserXssFilter` to true to add the `X-XSS-Protection` header with the val
### `customBrowserXSSValue`
The `customBrowserXssValue` option allows the `X-XSS-Protection` header value to be set with a custom value.
This overrides the BrowserXssFilter option.
This overrides the `BrowserXssFilter` option.
### `contentSecurityPolicy`
@ -410,11 +413,11 @@ The `contentSecurityPolicy` option allows the `Content-Security-Policy` header v
### `publicKey`
The `publicKey` implements HPKP to prevent MITM attacks with forged certificates.
The `publicKey` implements HPKP to prevent MITM attacks with forged certificates.
### `referrerPolicy`
The `referrerPolicy` allows sites to control when browsers will pass the Referer header to other sites.
The `referrerPolicy` allows sites to control whether browsers forward the `Referer` header to other sites.
### `featurePolicy`
@ -422,7 +425,6 @@ The `featurePolicy` allows sites to control browser features.
### `isDevelopment`
Set `isDevelopment` to true when developing.
The AllowedHosts, SSL, and STS options can cause some unwanted effects.
Usually testing happens on http, not https, and on localhost, not your production domain.
If you would like your development environment to mimic production with complete Host blocking, SSL redirects, and STS headers, leave this as false.
Set `isDevelopment` to `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.
If you would like your development environment to mimic production with complete Host blocking, SSL redirects, and STS headers, leave this as `false`.

32
docs/content/middlewares/inflightreq.md
View file

@ -5,7 +5,7 @@ Limiting the Number of Simultaneous In-Flight Requests
![InFlightReq](../assets/img/middleware/inflightreq.png)
To proactively prevent services from being overwhelmed with high load, a limit on the number of simultaneous in-flight requests can be applied.
To proactively prevent services from being overwhelmed with high load, the number of allowed simultaneous in-flight requests can be limited.
## Configuration Examples
@ -45,7 +45,7 @@ labels:
# Limiting to 10 simultaneous connections
[http.middlewares]
[http.middlewares.test-inflightreq.inFlightReq]
amount = 10
amount = 10
```
```yaml tab="File (YAML)"
@ -54,7 +54,7 @@ http:
middlewares:
test-inflightreq:
inFlightReq:
amount: 10
amount: 10
```
## Configuration Options
@ -62,7 +62,7 @@ http:
### `amount`
The `amount` option defines the maximum amount of allowed simultaneous in-flight request.
The middleware will return an `HTTP 429 Too Many Requests` if there are already `amount` requests in progress (based on the same `sourceCriterion` strategy).
The middleware responds with `HTTP 429 Too Many Requests` if there are already `amount` requests in progress (based on the same `sourceCriterion` strategy).
```yaml tab="Docker"
labels:
@ -100,7 +100,7 @@ labels:
# Limiting to 10 simultaneous connections
[http.middlewares]
[http.middlewares.test-inflightreq.inFlightReq]
amount = 10
amount = 10
```
```yaml tab="File (YAML)"
@ -109,29 +109,29 @@ http:
middlewares:
test-inflightreq:
inFlightReq:
amount: 10
amount: 10
```
### `sourceCriterion`
SourceCriterion defines what criterion is used to group requests as originating from a common source.
The `sourceCriterion` option defines what criterion is used to group requests as originating from a common source.
The precedence order is `ipStrategy`, then `requestHeaderName`, then `requestHost`.
If none are set, the default is to use the `requestHost`.
#### `sourceCriterion.ipStrategy`
The `ipStrategy` option defines two parameters that sets how Traefik will determine the client IP: `depth`, and `excludedIPs`.
The `ipStrategy` option defines two parameters that configures how Traefik determines the client IP: `depth`, and `excludedIPs`.
##### `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).
The `depth` option tells Traefik to use the `X-Forwarded-For` header and select 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 is empty.
- `depth` is ignored if its value is less than or equal to 0.
- 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 lesser than or equal to 0.
!!! example "Example of Depth & X-Forwarded-For"
If `depth` was equal to 2, and the request `X-Forwarded-For` header was `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` then the "real" client IP would be `"10.0.0.1"` (at depth 4) but the IP used as the criterion would be `"12.0.0.1"` (`depth=2`).
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 |
|-----------------------------------------|---------|--------------|
@ -190,7 +190,7 @@ http:
##### `ipStrategy.excludedIPs`
`excludedIPs` tells Traefik to scan the `X-Forwarded-For` header and pick the first IP not in the list.
`excludedIPs` configures Traefik to scan the `X-Forwarded-For` header and select the first IP not in the list.
!!! important "If `depth` is specified, `excludedIPs` is ignored."
@ -259,7 +259,7 @@ http:
#### `sourceCriterion.requestHeaderName`
Requests having the same value for the given header are grouped as coming from the same source.
Name of the header used to group incoming requests.
```yaml tab="Docker"
labels:

174
docs/content/middlewares/ipwhitelist.md
View file

@ -70,95 +70,105 @@ The `sourceRange` option sets the allowed IPs (or ranges of allowed IPs by using
### `ipStrategy`
The `ipStrategy` option defines two parameters that sets how Traefik will determine the client IP: `depth`, and `excludedIPs`.
The `ipStrategy` option defines two parameters that set how Traefik determines the client IP: `depth`, and `excludedIPs`.
#### `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.
!!! example "Examples of Depth & X-Forwarded-For"
```yaml tab="Docker"
# Whitelisting Based on `X-Forwarded-For` with `depth=2`
labels:
- "traefik.http.middlewares.testIPwhitelist.ipwhitelist.sourcerange=127.0.0.1/32, 192.168.1.7"
- "traefik.http.middlewares.testIPwhitelist.ipwhitelist.ipstrategy.depth=2"
```
```yaml tab="Kubernetes"
# Whitelisting Based on `X-Forwarded-For` with `depth=2`
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: testIPwhitelist
spec:
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 for the whitelisting 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` | `""` |
```yaml tab="Docker"
# Whitelisting Based on `X-Forwarded-For` with `depth=2`
labels:
- "traefik.http.middlewares.testIPwhitelist.ipwhitelist.sourcerange=127.0.0.1/32, 192.168.1.7"
- "traefik.http.middlewares.testIPwhitelist.ipwhitelist.ipstrategy.depth=2"
```
```yaml tab="Kubernetes"
# Whitelisting Based on `X-Forwarded-For` with `depth=2`
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: testIPwhitelist
spec:
ipWhiteList:
sourceRange:
- 127.0.0.1/32
- 192.168.1.7
ipStrategy:
depth: 2
```
```yaml tab="Consul Catalog"
# Whitelisting Based on `X-Forwarded-For` with `depth=2`
- "traefik.http.middlewares.testIPwhitelist.ipwhitelist.sourcerange=127.0.0.1/32, 192.168.1.7"
- "traefik.http.middlewares.testIPwhitelist.ipwhitelist.ipstrategy.depth=2"
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.testIPwhitelist.ipwhitelist.sourcerange": "127.0.0.1/32, 192.168.1.7",
"traefik.http.middlewares.testIPwhitelist.ipwhitelist.ipstrategy.depth": "2"
}
```
```yaml tab="Rancher"
# Whitelisting Based on `X-Forwarded-For` with `depth=2`
labels:
- "traefik.http.middlewares.testIPwhitelist.ipwhitelist.sourcerange=127.0.0.1/32, 192.168.1.7"
- "traefik.http.middlewares.testIPwhitelist.ipwhitelist.ipstrategy.depth=2"
```
```toml tab="File (TOML)"
# Whitelisting Based on `X-Forwarded-For` with `depth=2`
[http.middlewares]
[http.middlewares.test-ipwhitelist.ipWhiteList]
sourceRange = ["127.0.0.1/32", "192.168.1.7"]
[http.middlewares.test-ipwhitelist.ipWhiteList.ipStrategy]
depth = 2
```
```yaml tab="File (YAML)"
# Whitelisting Based on `X-Forwarded-For` with `depth=2`
http:
middlewares:
test-ipwhitelist:
ipWhiteList:
sourceRange:
- 127.0.0.1/32
- 192.168.1.7
- "127.0.0.1/32"
- "192.168.1.7"
ipStrategy:
depth: 2
```
```yaml tab="Consul Catalog"
# Whitelisting Based on `X-Forwarded-For` with `depth=2`
- "traefik.http.middlewares.testIPwhitelist.ipwhitelist.sourcerange=127.0.0.1/32, 192.168.1.7"
- "traefik.http.middlewares.testIPwhitelist.ipwhitelist.ipstrategy.depth=2"
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.testIPwhitelist.ipwhitelist.sourcerange": "127.0.0.1/32, 192.168.1.7",
"traefik.http.middlewares.testIPwhitelist.ipwhitelist.ipstrategy.depth": "2"
}
```
```yaml tab="Rancher"
# Whitelisting Based on `X-Forwarded-For` with `depth=2`
labels:
- "traefik.http.middlewares.testIPwhitelist.ipwhitelist.sourcerange=127.0.0.1/32, 192.168.1.7"
- "traefik.http.middlewares.testIPwhitelist.ipwhitelist.ipstrategy.depth=2"
```
```toml tab="File (TOML)"
# Whitelisting Based on `X-Forwarded-For` with `depth=2`
[http.middlewares]
[http.middlewares.test-ipwhitelist.ipWhiteList]
sourceRange = ["127.0.0.1/32", "192.168.1.7"]
[http.middlewares.test-ipwhitelist.ipWhiteList.ipStrategy]
depth = 2
```
```yaml tab="File (YAML)"
# Whitelisting Based on `X-Forwarded-For` with `depth=2`
http:
middlewares:
test-ipwhitelist:
ipWhiteList:
sourceRange:
- "127.0.0.1/32"
- "192.168.1.7"
ipStrategy:
depth: 2
```
If `depth` was equal to 2, and the request `X-Forwarded-For` header was `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` then the "real" client IP would be `"10.0.0.1"` (at depth 4) but the IP used for the whitelisting would be `"12.0.0.1"` (`depth=2`).
??? example "More examples"
| `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` | `""` |
!!! info
- 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 lesser than or equal to 0.
```
#### `ipStrategy.excludedIPs`
`excludedIPs` configures Traefik to scan the `X-Forwarded-For` header and select the first IP not in the list.
!!! important "If `depth` is specified, `excludedIPs` is ignored."
!!! example "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"` | `""` |
```yaml tab="Docker"
# Exclude from `X-Forwarded-For`
labels:
@ -215,17 +225,3 @@ http:
- "127.0.0.1/32"
- "192.168.1.7"
```
`excludedIPs` tells Traefik to scan the `X-Forwarded-For` header and pick the first IP not in the list.
!!! important "If `depth` is specified, `excludedIPs` is ignored."
!!! example "Examples 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"` | `""` |

2
docs/content/middlewares/overview.md
View file

@ -13,7 +13,7 @@ Pieces of middleware can be combined in chains to fit every scenario.
!!! warning "Provider Namespace"
Be aware of the concept of Providers Namespace described in the [Configuration Discovery](../providers/overview.md#provider-namespace) section.
Be aware of the concept of Providers Namespace described in the [Configuration Discovery](../providers/overview.md#provider-namespace) section.
It also applies to Middlewares.
## Configuration Example

187
docs/content/middlewares/passtlsclientcert.md
View file

@ -7,7 +7,7 @@ Adding Client Certificates in a Header
TODO: add schema
-->
PassTLSClientCert adds in header the selected data from the passed client tls certificate.
PassTLSClientCert adds the selected data from the passed client TLS certificate to a header.
## Configuration Examples
@ -86,7 +86,7 @@ http:
- "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.containo.us/v1alpha1
@ -116,7 +116,7 @@ http:
serialNumber: true
domainComponent: true
```
```yaml tab="Consul Catalog"
# Pass all the available info in the `X-Forwarded-Tls-Client-Cert-Info` header
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.notafter=true"
@ -137,7 +137,7 @@ http:
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.province=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.serialnumber=true"
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.notafter": "true",
@ -159,7 +159,7 @@ http:
"traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.serialnumber": "true"
}
```
```yaml tab="Rancher"
# Pass all the available info in the `X-Forwarded-Tls-Client-Cert-Info` header
labels:
@ -240,7 +240,7 @@ http:
### General
PassTLSClientCert can add two headers to the request:
PassTLSClientCert can add two headers to the request:
- `X-Forwarded-Tls-Client-Cert` that contains the escaped pem.
- `X-Forwarded-Tls-Client-Cert-Info` that contains all the selected certificate information in an escaped string.
@ -251,9 +251,9 @@ PassTLSClientCert can add two headers to the request:
* These options only work accordingly to the [MutualTLS configuration](../https/tls.md#client-authentication-mtls).
That is to say, only the certificates that match the `clientAuth.clientAuthType` policy are passed.
In the following example, you can see a complete certificate. We will use each part of it to explain the middleware options.
The following example shows a complete certificate and explains each of the middleware options.
??? example "A complete client tls certificate"
??? example "A complete client TLS certificate"
```
Certificate:
@ -292,16 +292,16 @@ In the following example, you can see a complete certificate. We will use each p
X509v3 extensions:
X509v3 Key Usage: critical
Digital Signature, Key Encipherment
X509v3 Basic Constraints:
X509v3 Basic Constraints:
CA:FALSE
X509v3 Extended Key Usage:
X509v3 Extended Key Usage:
TLS Web Server Authentication, TLS Web Client Authentication
X509v3 Subject Key Identifier:
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:
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:
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:
@ -359,9 +359,9 @@ In the following example, you can see a complete certificate. We will use each p
### `pem`
The `pem` option sets the `X-Forwarded-Tls-Client-Cert` header with the escape certificate.
The `pem` option sets the `X-Forwarded-Tls-Client-Cert` header with the escaped certificate.
In the example, it is the part between `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` delimiters :
In the example, it is the part between `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` delimiters:
??? example "The data used by the pem option"
@ -403,23 +403,24 @@ In the example, it is the part between `-----BEGIN CERTIFICATE-----` and `-----E
ML9n/4zmm1PMhzZHcEA72ZAq0tKCxpz10djg5v2qL5V+Oaz8TtTOZbPsxpiKMQ==
-----END CERTIFICATE-----
```
!!! info "Extracted data"
The delimiters and `\n` will be removed.
The delimiters and `\n` will be removed.
If there are more than one certificate, they are separated by a "`,`".
!!! warning "`X-Forwarded-Tls-Client-Cert` value could exceed the web server header size limit"
The header size limit of web servers is commonly between 4kb and 8kb.
The header size limit of web servers is commonly between 4kb and 8kb.
You could change the server configuration to allow bigger header or use the `info` option with the needed field(s).
### `info`
The `info` option select the specific client certificate details you want to add to the `X-Forwarded-Tls-Client-Cert-Info` header.
The value of the header will be an escaped concatenation of all the selected certificate details.
The `info` option selects the specific client certificate details you want to add to the `X-Forwarded-Tls-Client-Cert-Info` header.
The following example shows an unescaped result that uses all the available fields:
The value of the header is an escaped concatenation of all the selected certificate details.
The following example shows an unescaped result that uses all the available fields:
```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"
@ -433,14 +434,14 @@ Subject="DC=org,DC=cheese,C=FR,C=US,ST=Cheese org state,ST=Cheese com state,L=TO
Set the `info.notAfter` option to `true` to add the `Not After` information from the `Validity` part.
The data are taken from the following certificate part:
The data is taken from the following certificate part:
```text
Validity
Not After : Dec 5 11:10:16 2020 GMT
Not After : Dec 5 11:10:16 2020 GMT
```
The escape `notAfter` info part will be like:
The escaped `notAfter` info part is formatted as below:
```text
NA="1607166616"
@ -450,14 +451,14 @@ NA="1607166616"
Set the `info.notBefore` option to `true` to add the `Not Before` information from the `Validity` part.
The data are taken from the following certificate part:
The data is taken from the following certificate part:
```text
Validity
Not Before: Dec 6 11:10:16 2018 GMT
```
The escape `notBefore` info part will be like:
The escaped `notBefore` info part is formatted as below:
```text
NB="1544094616"
@ -467,28 +468,28 @@ NB="1544094616"
Set the `info.sans` option to `true` to add the `Subject Alternative Name` information from the `Subject Alternative Name` part.
The data are taken from the following certificate part:
The data is taken from the following certificate part:
```text
X509v3 Subject Alternative Name:
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
```
The escape SANs info part will be like:
The escape SANs info part is formatted as below:
```text
SAN="*.example.org,*.example.net,*.example.com,test@example.org,test@example.net,10.0.1.0,10.0.1.2"
```
!!! info "multiple values"
!!! info "Multiple values"
All the SANs data are separated by a `,`.
The SANs are separated by a `,`.
#### `info.subject`
The `info.subject` select the specific client certificate subject details you want to add to the `X-Forwarded-Tls-Client-Cert-Info` header.
The `info.subject` selects the specific client certificate subject details you want to add to the `X-Forwarded-Tls-Client-Cert-Info` header.
The data are taken from the following certificate part :
The data is taken from the following certificate part:
```text
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 state/emailAddress=cert@example.org/emailAddress=cert@sexample.com
@ -496,9 +497,11 @@ Subject: DC=org, DC=cheese, O=Cheese, O=Cheese 2, OU=Simple Signing Section, OU=
##### `info.subject.country`
Set the `info.subject.country` option to true to add the `country` information into the subject.
The data are taken from the subject part with the `C` key.
The escape country info in the subject part will be like :
Set the `info.subject.country` option to `true` to add the `country` information into the subject.
The data is taken from the subject part with the `C` key.
The escape country info in the subject part is formatted as below:
```text
C=FR,C=US
@ -506,11 +509,11 @@ C=FR,C=US
##### `info.subject.province`
Set the `info.subject.province` option to true to add the `province` information into the subject.
The data are taken from the subject part with the `ST` key.
Set the `info.subject.province` option to `true` to add the `province` information into the subject.
The escape province info in the subject part will be like :
The data is taken from the subject part with the `ST` key.
The escape province info in the subject part is formatted as below:
```text
ST=Cheese org state,ST=Cheese com state
@ -518,11 +521,11 @@ ST=Cheese org state,ST=Cheese com state
##### `info.subject.locality`
Set the `info.subject.locality` option to true to add the `locality` information into the subject.
The data are taken from the subject part with the `L` key.
Set the `info.subject.locality` option to `true` to add the `locality` information into the subject.
The escape locality info in the subject part will be like :
The data is taken from the subject part with the `L` key.
The escape locality info in the subject part is formatted as below:
```text
L=TOULOUSE,L=LYON
@ -530,11 +533,11 @@ L=TOULOUSE,L=LYON
##### `info.subject.organization`
Set the `info.subject.organization` option to true to add the `organization` information into the subject.
The data are taken from the subject part with the `O` key.
Set the `info.subject.organization` option to `true` to add the `organization` information into the subject.
The escape organization info in the subject part will be like :
The data is taken from the subject part with the `O` key.
The escape organization info in the subject part is formatted as below:
```text
O=Cheese,O=Cheese 2
@ -542,11 +545,11 @@ O=Cheese,O=Cheese 2
##### `info.subject.commonName`
Set the `info.subject.commonName` option to true to add the `commonName` information into the subject.
The data are taken from the subject part with the `CN` key.
Set the `info.subject.commonName` option to `true` to add the `commonName` information into the subject.
The escape common name info in the subject part will be like :
The data is taken from the subject part with the `CN` key.
The escape common name info in the subject part is formatted as below:
```text
CN=*.example.com
@ -554,11 +557,11 @@ CN=*.example.com
##### `info.subject.serialNumber`
Set the `info.subject.serialNumber` option to true to add the `serialNumber` information into the subject.
The data are taken from the subject part with the `SN` key.
Set the `info.subject.serialNumber` option to `true` to add the `serialNumber` information into the subject.
The escape serial number info in the subject part will be like :
The data is taken from the subject part with the `SN` key.
The escape serial number info in the subject part is formatted as below:
```text
SN=1234567890
@ -566,11 +569,11 @@ SN=1234567890
##### `info.subject.domainComponent`
Set the `info.subject.domainComponent` option to true to add the `domainComponent` information into the subject.
The data are taken from the subject part with the `DC` key.
Set the `info.subject.domainComponent` option to `true` to add the `domainComponent` information into the subject.
The escape domaincomponent info in the subject part will be like :
The data is taken from the subject part with the `DC` key.
The escape domain component info in the subject part is formatted as below:
```text
DC=org,DC=cheese
@ -578,9 +581,9 @@ DC=org,DC=cheese
#### `info.issuer`
The `info.issuer` select the specific client certificate issuer details you want to add to the `X-Forwarded-Tls-Client-Cert-Info` header.
The `info.issuer` selects the specific client certificate issuer details you want to add to the `X-Forwarded-Tls-Client-Cert-Info` header.
The data are taken from the following certificate part :
The data is taken from the following certificate part:
```text
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
@ -588,9 +591,11 @@ Issuer: DC=org, DC=cheese, O=Cheese, O=Cheese 2, OU=Simple Signing Section, OU=S
##### `info.issuer.country`
Set the `info.issuer.country` option to true to add the `country` information into the issuer.
The data are taken from the issuer part with the `C` key.
The escape country info in the issuer part will be like :
Set the `info.issuer.country` option to `true` to add the `country` information into the issuer.
The data is taken from the issuer part with the `C` key.
The escape country info in the issuer part is formatted as below:
```text
C=FR,C=US
@ -598,11 +603,11 @@ C=FR,C=US
##### `info.issuer.province`
Set the `info.issuer.province` option to true to add the `province` information into the issuer.
The data are taken from the issuer part with the `ST` key.
Set the `info.issuer.province` option to `true` to add the `province` information into the issuer.
The escape province info in the issuer part will be like :
The data is taken from the issuer part with the `ST` key.
The escape province info in the issuer part is formatted as below:
```text
ST=Signing State,ST=Signing State 2
@ -610,11 +615,11 @@ ST=Signing State,ST=Signing State 2
##### `info.issuer.locality`
Set the `info.issuer.locality` option to true to add the `locality` information into the issuer.
The data are taken from the issuer part with the `L` key.
Set the `info.issuer.locality` option to `true` to add the `locality` information into the issuer.
The escape locality info in the issuer part will be like :
The data is taken from the issuer part with the `L` key.
The escape locality info in the issuer part is formatted as below:
```text
L=TOULOUSE,L=LYON
@ -622,11 +627,11 @@ L=TOULOUSE,L=LYON
##### `info.issuer.organization`
Set the `info.issuer.organization` option to true to add the `organization` information into the issuer.
The data are taken from the issuer part with the `O` key.
Set the `info.issuer.organization` option to `true` to add the `organization` information into the issuer.
The escape organization info in the issuer part will be like :
The data is taken from the issuer part with the `O` key.
The escape organization info in the issuer part is formatted as below:
```text
O=Cheese,O=Cheese 2
@ -634,11 +639,11 @@ O=Cheese,O=Cheese 2
##### `info.issuer.commonName`
Set the `info.issuer.commonName` option to true to add the `commonName` information into the issuer.
The data are taken from the issuer part with the `CN` key.
Set the `info.issuer.commonName` option to `true` to add the `commonName` information into the issuer.
The escape common name info in the issuer part will be like :
The data is taken from the issuer part with the `CN` key.
The escape common name info in the issuer part is formatted as below:
```text
CN=Simple Signing CA 2
@ -646,11 +651,11 @@ CN=Simple Signing CA 2
##### `info.issuer.serialNumber`
Set the `info.issuer.serialNumber` option to true to add the `serialNumber` information into the issuer.
The data are taken from the issuer part with the `SN` key.
Set the `info.issuer.serialNumber` option to `true` to add the `serialNumber` information into the issuer.
The escape serial number info in the issuer part will be like :
The data is taken from the issuer part with the `SN` key.
The escape serial number info in the issuer part is formatted as below:
```text
SN=1234567890
@ -658,11 +663,11 @@ SN=1234567890
##### `info.issuer.domainComponent`
Set the `info.issuer.domainComponent` option to true to add the `domainComponent` information into the issuer.
The data are taken from the issuer part with the `DC` key.
Set the `info.issuer.domainComponent` option to `true` to add the `domainComponent` information into the issuer.
The escape domain component info in the issuer part will be like :
The data is taken from the issuer part with the `DC` key.
The escape domain component info in the issuer part is formatted as below:
```text
DC=org,DC=cheese

101
docs/content/middlewares/ratelimit.md
View file

@ -3,7 +3,7 @@
To Control the Number of Requests Going to a Service
{: .subtitle }
The RateLimit middleware ensures that services will receive a _fair_ number of requests, and allows one to define what fair is.
The RateLimit middleware ensures that services will receive a _fair_ amount of requests, and allows one to define what fair is.
## Configuration Example
@ -74,7 +74,7 @@ http:
### `average`
`average` is the maximum rate, by default in requests by second, allowed for the given source.
`average` is the maximum rate, by default in requests per second, allowed from a given source.
It defaults to `0`, which means no rate limiting.
@ -219,7 +219,7 @@ spec:
```
```yaml tab="Consul Catalog"
- "traefik.http.middlewares.test-ratelimit.ratelimit.burst=100"
- "traefik.http.middlewares.test-ratelimit.ratelimit.burst=100"
```
```json tab="Marathon"
@ -230,7 +230,7 @@ spec:
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-ratelimit.ratelimit.burst=100"
- "traefik.http.middlewares.test-ratelimit.ratelimit.burst=100"
```
```toml tab="File (TOML)"
@ -248,25 +248,25 @@ http:
```
### `sourceCriterion`
SourceCriterion defines what criterion is used to group requests as originating from a common source.
The `sourceCriterion` option defines what criterion is used to group requests as originating from a common source.
The precedence order is `ipStrategy`, then `requestHeaderName`, then `requestHost`.
If none are set, the default is to use the request's remote address field (as an `ipStrategy`).
#### `sourceCriterion.ipStrategy`
The `ipStrategy` option defines two parameters that sets how Traefik will determine the client IP: `depth`, and `excludedIPs`.
The `ipStrategy` option defines two parameters that configures how Traefik determines the client IP: `depth`, and `excludedIPs`.
##### `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).
The `depth` option tells Traefik to use the `X-Forwarded-For` header and select 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 lesser than or equal to 0.
- If `depth` is greater than the total number of IPs in `X-Forwarded-For`, then the client IP is empty.
- `depth` is ignored if its value is less than or equal to 0.
!!! example "Example of Depth & X-Forwarded-For"
If `depth` was equal to 2, and the request `X-Forwarded-For` header was `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` then the "real" client IP would be `"10.0.0.1"` (at depth 4) but the IP used as the criterion would be `"12.0.0.1"` (`depth=2`).
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 |
|-----------------------------------------|---------|--------------|
@ -274,8 +274,71 @@ The `depth` option tells Traefik to use the `X-Forwarded-For` header and take th
| `"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` | `""` |
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.ipstrategy.depth=2"
```
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: test-ratelimit
spec:
rateLimit:
sourceCriterion:
ipStrategy:
depth: 2
```
```yaml tab="Consul Catalog"
- "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.ipstrategy.depth=2"
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.ipstrategy.depth": "2"
}
```
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.ipstrategy.depth=2"
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.test-ratelimit.rateLimit]
[http.middlewares.test-ratelimit.rateLimit.sourceCriterion.ipStrategy]
depth = 2
```
```yaml tab="File (YAML)"
http:
middlewares:
test-ratelimit:
rateLimit:
sourceCriterion:
ipStrategy:
depth: 2
```
##### `ipStrategy.excludedIPs`
`excludedIPs` configures Traefik to scan the `X-Forwarded-For` header and select the first IP not in the list.
!!! important "If `depth` is specified, `excludedIPs` is ignored."
!!! example "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"` | `""` |
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.ipstrategy.excludedips=127.0.0.1/32, 192.168.1.7"
@ -329,23 +392,9 @@ http:
- "192.168.1.7"
```
`excludedIPs` tells Traefik to scan the `X-Forwarded-For` header and pick the first IP not in the list.
!!! important "If `depth` is specified, `excludedIPs` is ignored."
!!! example "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"` | `""` |
#### `sourceCriterion.requestHeaderName`
Requests having the same value for the given header are grouped as coming from the same source.
Name of the header used to group incoming requests.
```yaml tab="Docker"
labels:

18
docs/content/middlewares/redirectregex.md
View file

@ -7,7 +7,7 @@ Redirecting the Client to a Different Location
TODO: add schema
-->
RegexRedirect redirect a request from an url to another with regex matching and replacement.
The RedirectRegex redirects a request using regex matching and replacement.
## Configuration Examples
@ -73,6 +73,10 @@ http:
## Configuration Options
!!! 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).
### `permanent`
Set the `permanent` option to `true` to apply a permanent redirection.
@ -80,15 +84,11 @@ Set the `permanent` option to `true` to apply a permanent redirection.
### `regex`
The `regex` option is the regular expression to match and capture elements from the request 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.
!!! 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).
### `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.

6
docs/content/middlewares/redirectscheme.md
View file

@ -7,7 +7,7 @@ Redirecting the Client to a Different Scheme/Port
TODO: add schema
-->
RedirectScheme redirect request from a scheme to another.
RedirectScheme redirects requests from a scheme/port to another.
## Configuration Examples
@ -135,7 +135,7 @@ http:
### `scheme`
The `scheme` option defines the scheme of the new url.
The `scheme` option defines the scheme of the new URL.
```yaml tab="Docker"
# Redirect to https
@ -190,7 +190,7 @@ http:
### `port`
The `port` option defines the port of the new url.
The `port` option defines the port of the new URL.
```yaml tab="Docker"
# Redirect to https

18
docs/content/middlewares/replacepath.md
View file

@ -7,18 +7,18 @@ Updating the Path Before Forwarding the Request
TODO: add schema
-->
Replace the path of the request url.
Replace the path of the request URL.
## Configuration Examples
```yaml tab="Docker"
# Replace the path by /foo
# Replace the path with /foo
labels:
- "traefik.http.middlewares.test-replacepath.replacepath.path=/foo"
```
```yaml tab="Kubernetes"
# Replace the path by /foo
# Replace the path with /foo
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
@ -29,7 +29,7 @@ spec:
```
```yaml tab="Consul Catalog"
# Replace the path by /foo
# Replace the path with /foo
- "traefik.http.middlewares.test-replacepath.replacepath.path=/foo"
```
@ -40,20 +40,20 @@ spec:
```
```yaml tab="Rancher"
# Replace the path by /foo
# Replace the path with /foo
labels:
- "traefik.http.middlewares.test-replacepath.replacepath.path=/foo"
```
```toml tab="File (TOML)"
# Replace the path by /foo
# Replace the path with /foo
[http.middlewares]
[http.middlewares.test-replacepath.replacePath]
path = "/foo"
```
```yaml tab="File (YAML)"
# Replace the path by /foo
# Replace the path with /foo
http:
middlewares:
test-replacepath:
@ -67,9 +67,9 @@ http:
The ReplacePath middleware will:
- replace the actual path by the specified one.
- replace the actual path with the specified one.
- store the original path in a `X-Replaced-Path` header.
### `path`
The `path` option defines the path to use as replacement in the request url.
The `path` option defines the path to use as replacement in the request URL.

24
docs/content/middlewares/replacepathregex.md
View file

@ -7,7 +7,7 @@ Updating the Path Before Forwarding the Request (Using a Regex)
TODO: add schema
-->
The ReplaceRegex replace a path from an url to another with regex matching and replacement.
The ReplaceRegex replaces the path of a URL using regex matching and replacement.
## Configuration Examples
@ -51,7 +51,7 @@ labels:
```
```toml tab="File (TOML)"
# Redirect with domain replacement
# Replace path with regex
[http.middlewares]
[http.middlewares.test-replacepathregex.replacePathRegex]
regex = "^/foo/(.*)"
@ -59,7 +59,7 @@ labels:
```
```yaml tab="File (YAML)"
# Redirect with domain replacement
# Replace path with regex
http:
middlewares:
test-replacepathregex:
@ -74,21 +74,21 @@ http:
The ReplacePathRegex middleware will:
- replace the matching path by the specified one.
- replace the matching path with the specified one.
- store the original path in a `X-Replaced-Path` header.
!!! tip
Regular expressions and replacements can be tested using online tools such as [Go Playground](https://play.golang.org/p/mWU9p-wk2ru) or [Regex101](https://regex101.com/r/58sIgx/2).
### `regex`
The `regex` option is the regular expression to match and capture the path from the request URL.
### `replacement`
The `replacement` option defines the replacement path format, which can include captured variables.
!!! 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.
!!! 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).
### `replacement`
The `replacement` option defines how to modify the path to have the new target path.

23
docs/content/middlewares/retry.md
View file

@ -7,21 +7,21 @@ Retrying until it Succeeds
TODO: add schema
-->
The Retry middleware is in charge of reissuing a request a given number of times to a backend server if that server does not reply.
To be clear, as soon as the server answers, the middleware stops retrying, regardless of the response status.
The Retry middleware has an optional configuration for exponential backoff.
The Retry middleware reissues 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="Docker"
# Retry to send request 4 times with exponential backoff
# Retry 4 times with exponential backoff
labels:
- "traefik.http.middlewares.test-retry.retry.attempts=4"
- "traefik.http.middlewares.test-retry.retry.initialinterval=100ms"
```
```yaml tab="Kubernetes"
# Retry to send request 4 times with exponential backoff
# Retry 4 times with exponential backoff
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
@ -33,7 +33,7 @@ spec:
```
```yaml tab="Consul Catalog"
# Retry to send request 4 times with exponential backoff
# Retry 4 times with exponential backoff
- "traefik.http.middlewares.test-retry.retry.attempts=4"
- "traefik.http.middlewares.test-retry.retry.initialinterval=100ms"
```
@ -46,14 +46,14 @@ spec:
```
```yaml tab="Rancher"
# Retry to send request 4 times with exponential backoff
# Retry 4 times with exponential backoff
labels:
- "traefik.http.middlewares.test-retry.retry.attempts=4"
- "traefik.http.middlewares.test-retry.retry.initialinterval=100ms"
```
```toml tab="File (TOML)"
# Retry to send request 4 times
# Retry 4 times with exponential backoff
[http.middlewares]
[http.middlewares.test-retry.retry]
attempts = 4
@ -61,7 +61,7 @@ labels:
```
```yaml tab="File (YAML)"
# Retry to send request 4 times with exponential backoff
# Retry 4 times with exponential backoff
http:
middlewares:
test-retry:
@ -80,4 +80,7 @@ The `attempts` option defines how many times the request should be retried.
### `initialInterval`
The `initialInterval` option defines the first wait time in the exponential backoff series (provided in seconds or as a valid duration format, see [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration)). The maximum interval is calculated as twice the `initialInterval`. If unspecified, requests will be retried immediately.
The `initialInterval` option defines the first wait time in the exponential backoff series. The maximum interval is
calculated as twice the `initialInterval`. If unspecified, requests will be retried immediately.
The value of initialInterval should be provided in seconds or as a valid duration format, see [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration).

79
docs/content/middlewares/stripprefix.md
View file

@ -69,32 +69,55 @@ http:
### General
The StripPrefix middleware will:
- strip the matching path prefix.
- store the matching path prefix in a `X-Forwarded-Prefix` header.
The StripPrefix middleware strips the matching path prefix and stores it in a `X-Forwarded-Prefix` header.
!!! tip
Use a `StripPrefix` middleware if your backend listens on the root path (`/`) but should be routeable on a specific prefix.
Use a `StripPrefix` middleware if your backend listens on the root path (`/`) but should be exposed on a specific prefix.
### `prefixes`
The `prefixes` option defines the prefixes to strip from the request URL.
For instance, `/products` would match `/products` but also `/products/shoes` and `/products/shirts`.
For instance, `/products` also matches `/products/shoes` and `/products/shirts`.
Since the path is stripped prior to forwarding, your backend is expected to listen on `/`.
If your backend is serving assets (e.g., images or Javascript files), chances are it must return properly constructed relative URLs.
Continuing on the 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).
The `X-Forwarded-Prefix` header can be queried to build such URLs dynamically.
If your backend is serving assets (e.g., images or JavaScript files), it can use the `X-Forwarded-Prefix` header to properly 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).
### `forceSlash`
_Optional, Default=true_
The `forceSlash` option ensures the resulting stripped path is not the empty string, by replacing it with `/` when necessary.
This option was added to keep the initial (non-intuitive) behavior of this middleware, in order to avoid introducing a breaking change.
It is recommended to explicitly set `forceSlash` to `false`.
??? info "Behavior examples"
- `forceSlash=true`
| Path | Prefix to strip | Result |
|------------|-----------------|--------|
| `/` | `/` | `/` |
| `/foo` | `/foo` | `/` |
| `/foo/` | `/foo` | `/` |
| `/foo/` | `/foo/` | `/` |
| `/bar` | `/foo` | `/bar` |
| `/foo/bar` | `/foo` | `/bar` |
- `forceSlash=false`
| Path | Prefix to strip | Result |
|------------|-----------------|--------|
| `/` | `/` | empty |
| `/foo` | `/foo` | empty |
| `/foo/` | `/foo` | `/` |
| `/foo/` | `/foo/` | empty |
| `/bar` | `/foo` | `/bar` |
| `/foo/bar` | `/foo` | `/bar` |
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.example.stripprefix.prefixes=/foobar"
@ -142,33 +165,3 @@ http:
- "/foobar"
forceSlash: false
```
The `forceSlash` option makes sure that the resulting stripped path is not the empty string, by replacing it with `/` when necessary.
This option was added to keep the initial (non-intuitive) behavior of this middleware, in order to avoid introducing a breaking change.
It's recommended to explicitly set `forceSlash` to `false`.
??? info "Behavior examples"
- `forceSlash=true`
| Path | Prefix to strip | Result |
|------------|-----------------|--------|
| `/` | `/` | `/` |
| `/foo` | `/foo` | `/` |
| `/foo/` | `/foo` | `/` |
| `/foo/` | `/foo/` | `/` |
| `/bar` | `/foo` | `/bar` |
| `/foo/bar` | `/foo` | `/bar` |
- `forceSlash=false`
| Path | Prefix to strip | Result |
|------------|-----------------|--------|
| `/` | `/` | empty |
| `/foo` | `/foo` | empty |
| `/foo/` | `/foo` | `/` |
| `/foo/` | `/foo/` | empty |
| `/bar` | `/foo` | `/bar` |
| `/foo/bar` | `/foo` | `/bar` |

20
docs/content/middlewares/stripprefixregex.md
View file

@ -57,14 +57,11 @@ http:
### General
The StripPrefixRegex middleware will:
- strip the matching path prefix.
- store the matching path prefix in a `X-Forwarded-Prefix` header.
The StripPrefixRegex middleware strips the matching path prefix and stores it in a `X-Forwarded-Prefix` header.
!!! tip
Use a `stripPrefixRegex` middleware if your backend listens on the root path (`/`) but should be routeable on a specific prefix.
Use a `stripPrefixRegex` middleware if your backend listens on the root path (`/`) but should be exposed on a specific prefix.
### `regex`
@ -74,12 +71,7 @@ The `regex` option is the regular expression to match the path prefix from the r
Regular expressions 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).
For instance, `/products` would match `/products` but also `/products/shoes` and `/products/shirts`.
For instance, `/products` also matches `/products/shoes` and `/products/shirts`.
Since the path is stripped prior to forwarding, your backend is expected to listen on `/`.
If your backend is serving assets (e.g., images or Javascript files), chances are it must return properly constructed relative URLs.
Continuing on the 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).
The `X-Forwarded-Prefix` header can be queried to build such URLs dynamically.
If your backend is serving assets (e.g., images or JavaScript files), it can use the `X-Forwarded-Prefix` header to properly 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).

2
docs/content/providers/docker.md
View file

@ -155,7 +155,7 @@ You can specify which Docker API Endpoint to use with the directive [`endpoint`]
Expose the Docker socket over TCP or SSH, instead of the default Unix socket file.
It allows different implementation levels of the [AAA (Authentication, Authorization, Accounting) concepts](https://en.wikipedia.org/wiki/AAA_(computer_security)), depending on your security assessment:
- Authentication with Client Certificates as described in ["Protect the Docker daemon socket."](https://docs.docker.com/engine/security/https/)
- Authentication with Client Certificates as described in ["Protect the Docker daemon socket."](https://docs.docker.com/engine/security/protect-access/)
- Authorize and filter requests to restrict possible actions with [the TecnativaDocker Socket Proxy](https://github.com/Tecnativa/docker-socket-proxy).
- Authorization with the [Docker Authorization Plugin Mechanism](https://web.archive.org/web/20190920092526/https://docs.docker.com/engine/extend/plugins_authorization/)
- Accounting at networking level, by exposing the socket only inside a Docker private network, only available for Traefik.