Improve routing documentation
This commit is contained in:
Ludovic Fernandez
Traefiker Bot
parent
76263a9610
commit
bfde17b4d7
45 changed files with 2465 additions and 983 deletions
|
|
@ -77,7 +77,7 @@ Passwords must be encoded using MD5, SHA1, or BCrypt.
|
|||
|
||||
The `users` option is an array of authorized users. Each user will be declared using the `name:encoded-password` format.
|
||||
|
||||
!!! Note
|
||||
!!! 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.
|
||||
|
|
@ -154,7 +154,7 @@ The `usersFile` option is the path to an external file that contains the authori
|
|||
|
||||
The file content is a list of `name:encoded-password`.
|
||||
|
||||
!!! Note
|
||||
!!! 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.
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ This can help services deal with large data (multipart/form-data for example), a
|
|||
```yaml tab="Docker"
|
||||
# Sets the maximum request body to 2Mb
|
||||
labels:
|
||||
- "traefik.http.middlewares.limit.buffering.maxRequestBodyBytes=250000"
|
||||
- "traefik.http.middlewares.limit.buffering.maxRequestBodyBytes=2000000"
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
|
|
@ -27,26 +27,26 @@ metadata:
|
|||
name: limit
|
||||
spec:
|
||||
buffering:
|
||||
maxRequestBodyBytes: 250000
|
||||
maxRequestBodyBytes: 2000000
|
||||
```
|
||||
|
||||
```json tab="Marathon"
|
||||
"labels": {
|
||||
"traefik.http.middlewares.limit.buffering.maxRequestBodyBytes": "250000"
|
||||
"traefik.http.middlewares.limit.buffering.maxRequestBodyBytes": "2000000"
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Rancher"
|
||||
# Sets the maximum request body to 2Mb
|
||||
labels:
|
||||
- "traefik.http.middlewares.limit.buffering.maxRequestBodyBytes=250000"
|
||||
- "traefik.http.middlewares.limit.buffering.maxRequestBodyBytes=2000000"
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
# Sets the maximum request body to 2Mb
|
||||
[http.middlewares]
|
||||
[http.middlewares.limit.buffering]
|
||||
maxRequestBodyBytes = 250000
|
||||
maxRequestBodyBytes = 2000000
|
||||
```
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
|
|
@ -55,7 +55,7 @@ http:
|
|||
middlewares:
|
||||
limit:
|
||||
buffering:
|
||||
maxRequestBodyBytes: 250000
|
||||
maxRequestBodyBytes: 2000000
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
|
@ -64,11 +64,91 @@ http:
|
|||
|
||||
With the `maxRequestBodyBytes` option, you can configure the maximum allowed body size for the request (in Bytes).
|
||||
|
||||
If the request exceeds the allowed size, the request 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:
|
||||
- "traefik.http.middlewares.limit.buffering.maxRequestBodyBytes=2000000"
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
apiVersion: traefik.containo.us/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: limit
|
||||
spec:
|
||||
buffering:
|
||||
maxRequestBodyBytes: 2000000
|
||||
```
|
||||
|
||||
```json tab="Marathon"
|
||||
"labels": {
|
||||
"traefik.http.middlewares.limit.buffering.maxRequestBodyBytes": "2000000"
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Rancher"
|
||||
labels:
|
||||
- "traefik.http.middlewares.limit.buffering.maxRequestBodyBytes=2000000"
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[http.middlewares]
|
||||
[http.middlewares.limit.buffering]
|
||||
maxRequestBodyBytes = 2000000
|
||||
```
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
http:
|
||||
middlewares:
|
||||
limit:
|
||||
buffering:
|
||||
maxRequestBodyBytes: 2000000
|
||||
```
|
||||
|
||||
### `memRequestBodyBytes`
|
||||
|
||||
You can configure a thresold (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:
|
||||
- "traefik.http.middlewares.limit.buffering.memRequestBodyBytes=2000000"
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
apiVersion: traefik.containo.us/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: limit
|
||||
spec:
|
||||
buffering:
|
||||
memRequestBodyBytes: 2000000
|
||||
```
|
||||
|
||||
```json tab="Marathon"
|
||||
"labels": {
|
||||
"traefik.http.middlewares.limit.buffering.memRequestBodyBytes": "2000000"
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Rancher"
|
||||
labels:
|
||||
- "traefik.http.middlewares.limit.buffering.memRequestBodyBytes=2000000"
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[http.middlewares]
|
||||
[http.middlewares.limit.buffering]
|
||||
memRequestBodyBytes = 2000000
|
||||
```
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
http:
|
||||
middlewares:
|
||||
limit:
|
||||
buffering:
|
||||
memRequestBodyBytes: 2000000
|
||||
```
|
||||
|
||||
### `maxResponseBodyBytes`
|
||||
|
||||
|
|
@ -76,21 +156,137 @@ With the `maxReesponseBodyBytes` option, you can configure the maximum allowed r
|
|||
|
||||
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.
|
||||
|
||||
```yaml tab="Docker"
|
||||
labels:
|
||||
- "traefik.http.middlewares.limit.buffering.maxResponseBodyBytes=2000000"
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
apiVersion: traefik.containo.us/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: limit
|
||||
spec:
|
||||
buffering:
|
||||
maxResponseBodyBytes: 2000000
|
||||
```
|
||||
|
||||
```json tab="Marathon"
|
||||
"labels": {
|
||||
"traefik.http.middlewares.limit.buffering.maxResponseBodyBytes": "2000000"
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Rancher"
|
||||
labels:
|
||||
- "traefik.http.middlewares.limit.buffering.maxResponseBodyBytes=2000000"
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[http.middlewares]
|
||||
[http.middlewares.limit.buffering]
|
||||
maxResponseBodyBytes = 2000000
|
||||
```
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
http:
|
||||
middlewares:
|
||||
limit:
|
||||
buffering:
|
||||
maxResponseBodyBytes: 2000000
|
||||
```
|
||||
|
||||
### `memResponseBodyBytes`
|
||||
|
||||
You can configure a thresold (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:
|
||||
- "traefik.http.middlewares.limit.buffering.memResponseBodyBytes=2000000"
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
apiVersion: traefik.containo.us/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: limit
|
||||
spec:
|
||||
buffering:
|
||||
memResponseBodyBytes: 2000000
|
||||
```
|
||||
|
||||
```json tab="Marathon"
|
||||
"labels": {
|
||||
"traefik.http.middlewares.limit.buffering.memResponseBodyBytes": "2000000"
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Rancher"
|
||||
labels:
|
||||
- "traefik.http.middlewares.limit.buffering.memResponseBodyBytes=2000000"
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[http.middlewares]
|
||||
[http.middlewares.limit.buffering]
|
||||
memResponseBodyBytes = 2000000
|
||||
```
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
http:
|
||||
middlewares:
|
||||
limit:
|
||||
buffering:
|
||||
memResponseBodyBytes: 2000000
|
||||
```
|
||||
|
||||
### `retryExpression`
|
||||
|
||||
You can have the Buffering middleware replay the request with the help of the `retryExpression` option.
|
||||
|
||||
!!! example "Retries once in case of a network error"
|
||||
??? example "Retries once in case of a network error"
|
||||
|
||||
```toml
|
||||
retryExpression = "IsNetworkError() && Attempts() < 2"
|
||||
```yaml tab="Docker"
|
||||
labels:
|
||||
- "traefik.http.middlewares.limit.buffering.retryExpression=IsNetworkError() && Attempts() < 2"
|
||||
```
|
||||
|
||||
Available functions for the retry expression are:
|
||||
```yaml tab="Kubernetes"
|
||||
apiVersion: traefik.containo.us/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: limit
|
||||
spec:
|
||||
buffering:
|
||||
retryExpression: "IsNetworkError() && Attempts() < 2"
|
||||
```
|
||||
|
||||
```json tab="Marathon"
|
||||
"labels": {
|
||||
"traefik.http.middlewares.limit.buffering.retryExpression": "IsNetworkError() && Attempts() < 2"
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Rancher"
|
||||
labels:
|
||||
- "traefik.http.middlewares.limit.buffering.retryExpression=IsNetworkError() && Attempts() < 2"
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[http.middlewares]
|
||||
[http.middlewares.limit.buffering]
|
||||
retryExpression = "IsNetworkError() && Attempts() < 2"
|
||||
```
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
http:
|
||||
middlewares:
|
||||
limit:
|
||||
buffering:
|
||||
retryExpression: "IsNetworkError() && Attempts() < 2"
|
||||
```
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -12,14 +12,19 @@ When your system becomes unhealthy, the circuit becomes open and the requests ar
|
|||
|
||||
To assess if your system is healthy, the circuit breaker constantly monitors the services.
|
||||
|
||||
!!! Note
|
||||
!!! 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.
|
||||
|
||||
!!! 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 close: 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.
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
|
|
@ -117,7 +122,7 @@ The `ResponseCodeRatio` accepts four parameters, `from`, `to`, `dividedByFrom`,
|
|||
|
||||
The operation that will be computed is sum(`to` -> `from`) / sum (`dividedByFrom` -> `dividedByTo`).
|
||||
|
||||
!!! Note
|
||||
!!! note ""
|
||||
If sum (`dividedByFrom` -> `dividedByTo`) equals 0, then `ResponseCodeRatio` returns 0.
|
||||
|
||||
`from`is inclusive, `to` is exclusive.
|
||||
|
|
@ -130,7 +135,7 @@ You can trigger the circuit breaker when a given proportion of your requests bec
|
|||
|
||||
For example, the expression `LatencyAtQuantileMS(50.0) > 100` will trigger the circuit breaker when the median latency (quantile 50) reaches 100MS.
|
||||
|
||||
!!! Note
|
||||
!!! note ""
|
||||
|
||||
You must provide a float number (with the trailing .0) for the quantile value
|
||||
|
||||
|
|
@ -155,14 +160,16 @@ Here is the list of supported operators:
|
|||
- 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.
|
||||
The fallback mechanism returns a `HTTP 503 Service Unavailable` to the client (instead of calling the target service).
|
||||
This behavior cannot be configured.
|
||||
|
||||
### `CheckPeriod`
|
||||
|
||||
The interval used to evaluate `expression` and decide if the state of the circuit breaker must change. By default, `CheckPeriod` is 100Ms. This value cannot be configured.
|
||||
The interval used to evaluate `expression` and decide if the state of the circuit breaker must change.
|
||||
By default, `CheckPeriod` is 100ms. This value cannot be configured.
|
||||
|
||||
### `FallbackDuration`
|
||||
|
||||
|
|
|
|||
|
|
@ -51,10 +51,10 @@ http:
|
|||
compress: {}
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
Responses are compressed when:
|
||||
|
||||
* 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.
|
||||
!!! info
|
||||
|
||||
Responses are compressed when:
|
||||
|
||||
* 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.
|
||||
|
|
|
|||
|
|
@ -69,7 +69,7 @@ http:
|
|||
|
||||
The `users` option is an array of authorized users. Each user will be declared using the `name:realm:encoded-password` format.
|
||||
|
||||
!!! Note
|
||||
!!! 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.
|
||||
|
|
@ -136,7 +136,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
|
||||
!!! 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.
|
||||
|
|
|
|||
|
|
@ -78,7 +78,7 @@ 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
|
||||
|
|
@ -89,7 +89,7 @@ The `status` that will trigger the error page.
|
|||
|
||||
The status code ranges are inclusive (`500-599` will trigger with every code between `500` and `599`, `500` and `599` included).
|
||||
|
||||
!!! Note
|
||||
!!! note ""
|
||||
|
||||
You can define either a status code like `500` or ranges with a syntax like `500-599`.
|
||||
|
||||
|
|
@ -97,7 +97,7 @@ The status code ranges are inclusive (`500-599` will trigger with every code bet
|
|||
|
||||
The service that will serve the new requested error page.
|
||||
|
||||
!!! Note
|
||||
!!! note ""
|
||||
In kubernetes, you need to reference a kubernetes service instead of a traefik service.
|
||||
|
||||
### `query`
|
||||
|
|
|
|||
|
|
@ -385,7 +385,7 @@ http:
|
|||
key: "path/to/foo.key"
|
||||
```
|
||||
|
||||
!!! Note
|
||||
!!! info
|
||||
For security reasons, the field doesn't exist for Kubernetes IngressRoute, and one should use the `secret` field instead.
|
||||
|
||||
#### `tls.key`
|
||||
|
|
@ -454,7 +454,7 @@ http:
|
|||
key: "path/to/foo.key"
|
||||
```
|
||||
|
||||
!!! Note
|
||||
!!! info
|
||||
For security reasons, the field doesn't exist for Kubernetes IngressRoute, and one should use the `secret` field instead.
|
||||
|
||||
#### `tls.insecureSkipVerify`
|
||||
|
|
|
|||
|
|
@ -251,7 +251,7 @@ http:
|
|||
!!! warning
|
||||
If the custom header name is the same as one header name of the request or response, it will be replaced.
|
||||
|
||||
!!! note
|
||||
!!! note ""
|
||||
The detailed documentation for the security headers can be found in [unrolled/secure](https://github.com/unrolled/secure#available-options).
|
||||
|
||||
### `customRequestHeaders`
|
||||
|
|
|
|||
|
|
@ -59,6 +59,49 @@ http:
|
|||
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).
|
||||
|
||||
```yaml tab="Docker"
|
||||
labels:
|
||||
- "traefik.http.middlewares.test-inflightreq.inflightreq.amount=10"
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
apiVersion: traefik.containo.us/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-inflightreq
|
||||
spec:
|
||||
inFlightReq:
|
||||
amount: 10
|
||||
```
|
||||
|
||||
```json tab="Marathon"
|
||||
"labels": {
|
||||
"traefik.http.middlewares.test-inflightreq.inflightreq.amount": "10"
|
||||
}
|
||||
```
|
||||
|
||||
```yaml tab="Rancher"
|
||||
# Limiting to 10 simultaneous connections
|
||||
labels:
|
||||
- "traefik.http.middlewares.test-inflightreq.inflightreq.amount=10"
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
# Limiting to 10 simultaneous connections
|
||||
[http.middlewares]
|
||||
[http.middlewares.test-inflightreq.inFlightReq]
|
||||
amount = 10
|
||||
```
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
# Limiting to 10 simultaneous connections
|
||||
http:
|
||||
middlewares:
|
||||
test-inflightreq:
|
||||
inFlightReq:
|
||||
amount: 10
|
||||
```
|
||||
|
||||
### `sourceCriterion`
|
||||
|
||||
SourceCriterion defines what criterion is used to group requests as originating from a common source.
|
||||
|
|
@ -76,7 +119,7 @@ The `depth` option tells Traefik to use the `X-Forwarded-For` header and take th
|
|||
- 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.
|
||||
|
||||
!!! note "Example of Depth & X-Forwarded-For"
|
||||
!!! 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`).
|
||||
|
||||
|
|
@ -86,14 +129,58 @@ 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-inflightreq.inflightreq.sourcecriterion.ipstrategy.depth=2"
|
||||
```
|
||||
|
||||
```yaml tab="Kubernetes"
|
||||
apiVersion: traefik.containo.us/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: test-inflightreq
|
||||
spec:
|
||||
inFlightReq:
|
||||
sourceCriterion:
|
||||
ipStrategy:
|
||||
depth: 2
|
||||
```
|
||||
|
||||
```yaml tab="Rancher"
|
||||
labels:
|
||||
- "traefik.http.middlewares.test-inflightreq.inflightreq.sourcecriterion.ipstrategy.depth=2"
|
||||
```
|
||||
|
||||
```json tab="Marathon"
|
||||
"labels": {
|
||||
"traefik.http.middlewares.test-inflightreq.inflightreq.sourcecriterion.ipstrategy.depth": "2"
|
||||
}
|
||||
```
|
||||
|
||||
```toml tab="File (TOML)"
|
||||
[http.middlewares]
|
||||
[http.middlewares.test-inflightreq.inflightreq]
|
||||
[http.middlewares.test-inflightreq.inFlightReq.sourceCriterion.ipStrategy]
|
||||
depth = 2
|
||||
```
|
||||
|
||||
```yaml tab="File (YAML)"
|
||||
http:
|
||||
middlewares:
|
||||
test-inflightreq:
|
||||
inFlightReq:
|
||||
sourceCriterion:
|
||||
ipStrategy:
|
||||
depth: 2
|
||||
```
|
||||
|
||||
##### `ipStrategy.excludedIPs`
|
||||
|
||||
`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.
|
||||
!!! important "If `depth` is specified, `excludedIPs` is ignored."
|
||||
|
||||
!!! note "Example of ExcludedIPs & X-Forwarded-For"
|
||||
!!! example "Example of ExcludedIPs & X-Forwarded-For"
|
||||
|
||||
| `X-Forwarded-For` | `excludedIPs` | clientIP |
|
||||
|-----------------------------------------|-----------------------|--------------|
|
||||
|
|
|
|||
|
|
@ -71,18 +71,8 @@ The `ipStrategy` option defines two parameters that sets how Traefik will determ
|
|||
|
||||
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).
|
||||
|
||||
!!! note "Examples of Depth & X-Forwarded-For"
|
||||
!!! example "Examples 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 for the whitelisting would be `"12.0.0.1"` (`depth=2`).
|
||||
|
||||
??? note "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` | `""` |
|
||||
|
||||
```yaml tab="Docker"
|
||||
# Whitelisting Based on `X-Forwarded-For` with `depth=2`
|
||||
labels:
|
||||
|
|
@ -140,29 +130,24 @@ The `depth` option tells Traefik to use the `X-Forwarded-For` header and take th
|
|||
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` | `""` |
|
||||
|
||||
!!! note
|
||||
!!! 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` tells Traefik to scan the `X-Forwarded-For` header and pick the first IP not in the list.
|
||||
|
||||
!!! note "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"` | `""` |
|
||||
|
||||
!!! important
|
||||
If `depth` is specified, `excludedIPs` is ignored.
|
||||
|
||||
```yaml tab="Docker"
|
||||
# Exclude from `X-Forwarded-For`
|
||||
labels:
|
||||
|
|
@ -214,3 +199,17 @@ 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"` | `""` |
|
||||
|
|
|
|||
|
|
@ -218,7 +218,7 @@ 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.
|
||||
|
||||
!!! note
|
||||
!!! info
|
||||
The headers are filled with escaped string so it can be safely placed inside a URL query.
|
||||
|
||||
In the following example, you can see a complete certificate. We will use each part of it to explain the middleware options.
|
||||
|
|
@ -374,12 +374,12 @@ In the example, it is the part between `-----BEGIN CERTIFICATE-----` and `-----E
|
|||
-----END CERTIFICATE-----
|
||||
```
|
||||
|
||||
!!! note "Extracted data"
|
||||
!!! info "Extracted data"
|
||||
|
||||
The delimiters and `\n` will be removed.
|
||||
If there are more than one certificate, they are separated by a "`;`".
|
||||
|
||||
!!! note "`X-Forwarded-Tls-Client-Cert` value could exceed the web server header size limit"
|
||||
!!! 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.
|
||||
You could change the server configuration to allow bigger header or use the `info` option with the needed field(s).
|
||||
|
|
@ -395,7 +395,7 @@ The following example shows an unescaped result that uses all the available fiel
|
|||
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=*.cheese.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=*.cheese.org,*.cheese.net,*.cheese.com,test@cheese.org,test@cheese.net,10.0.1.0,10.0.1.2
|
||||
```
|
||||
|
||||
!!! note "Multiple certificates"
|
||||
!!! info "Multiple certificates"
|
||||
|
||||
If there are more than one certificate, they are separated by a `;`.
|
||||
|
||||
|
|
@ -450,7 +450,7 @@ The escape SANs info part will be like:
|
|||
SAN=*.cheese.org,*.cheese.net,*.cheese.com,test@cheese.org,test@cheese.net,10.0.1.0,10.0.1.2
|
||||
```
|
||||
|
||||
!!! note "multiple values"
|
||||
!!! info "multiple values"
|
||||
|
||||
All the SANs data are separated by a `,`.
|
||||
|
||||
|
|
|
|||
|
|
@ -173,7 +173,7 @@ The `depth` option tells Traefik to use the `X-Forwarded-For` header and take th
|
|||
- 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.
|
||||
|
||||
!!! note "Example of Depth & X-Forwarded-For"
|
||||
!!! 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`).
|
||||
|
||||
|
|
@ -185,21 +185,6 @@ The `depth` option tells Traefik to use the `X-Forwarded-For` header and take th
|
|||
|
||||
##### `ipStrategy.excludedIPs`
|
||||
|
||||
`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.
|
||||
|
||||
!!! note "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"
|
||||
|
|
@ -249,6 +234,20 @@ 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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue