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

Documentation Revamp

Browse source 
Co-authored-by: jbdoumenjou <jb.doumenjou@gmail.com>
This commit is contained in:
Gérald Croës 2019-02-26 05:50:07 -08:00 • committed by Traefiker Bot
parent 848e45c22c
commit ac6b11037d
174 changed files with 5858 additions and 4002 deletions
Download patch file Download diff file Expand all files Collapse all files

33
docs/content/middlewares/addprefix.md Normal file
View file

@ -0,0 +1,33 @@
# Add Prefix
Prefixing the Path
{: .subtitle }
![AddPrefix](../assets/img/middleware/addprefix.png)
The AddPrefix middleware updates the URL Path of the request before forwarding it.
## Configuration Examples
??? example "File -- Prefixing with /foo"
```toml
[Middlewares]
[Middlewares.add-foo.AddPrefix]
prefix = "/foo"
```
??? example "Docker -- Prefixing with /bar"
```yaml
a-container:
image: a-container-image
labels:
- "traefik.middlewares.add-bar.addprefix.prefix=/bar"
```
## Configuration Options
### prefix
`prefix` is the string to add before the current path in the requested URL. It should include the leading slash (`/`).

83
docs/content/middlewares/basicauth.md Normal file
View file

@ -0,0 +1,83 @@
# BasicAuth
Adding Basic Authentication
{: .subtitle }
![BasicAuth](../assets/img/middleware/basicauth.png)
The BasicAuth middleware is a quick way to restrict access to your services to known users.
## Configuration Examples
??? example "File -- Declaring the user list"
```toml
[Middlewares]
[Middlewares.test-auth.basicauth]
users = ["test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
"test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"]
```
??? example "Docker -- Using an external file for the authorized users"
```yml
a-container:
image: a-container-image
labels:
- "traefik.middlewares.declared-users-only.basicauth.usersFile=path-to-file.ext",
```
## Configuration Options
### General
Passwords must be encoded using MD5, SHA1, or BCrypt.
!!! tip
Use `htpasswd` to generate the passwords.
### users
The `users` option is an array of authorized users. Each user will be declared using the `name:encoded-password` format.
!!! Note
If both `users` and `usersFile` are provided, the two are merged. The content of `usersFile` has precedence over `users`.
### usersFile
The `usersFile` option is the path to an external file that contains the authorized users for the middleware.
The file content is a list of `name:encoded-password`.
??? example "A file containing test/test and test2/test2"
```
test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/
test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0
```
!!! Note
If both `users` and `usersFile` are provided, the two are merged. The content of `usersFile` has precedence over `users`.
### realm
You can customize the realm for the authentication with the `realm` option. The default value is `traefik`.
### headerField
You can customize the header field for the authenticated user using the `headerField`option.
??? example "File -- Passing Authenticated Users to Services Via Headers"
```toml
[Middlewares.my-auth.basicauth]
usersFile = "path-to-file.ext"
headerField = "X-WebAuth-User" # header for the authenticated user
```
### removeHeader
Set the `removeHeader` option to `true` to remove the authorization header before forwarding the request to your service. (Default value is `false`.)

69
docs/content/middlewares/buffering.md Normal file
View file

@ -0,0 +1,69 @@
# Buffering
How to Read the Request before Forwarding It
{: .subtitle }
![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.
With Buffering, Traefik reads the entire request into memory (possibly buffering large requests into disk), and rejects requests that are over a specified limit.
This can help services deal with large data (multipart/form-data for example), and can minimize time spent sending data to a service.
## Configuration Examples
??? example "File -- Sets the maximum request body to 2Mb"
```toml
[Middlewares]
[Middlewares.2Mb-limit.buffering]
maxRequestBodyBytes = 250000
```
??? example "Docker -- Buffers 1Mb of the request in memory, then writes to disk"
```yaml
a-container:
image: a-container-image
labels:
- "traefik.middlewares.1Mb-memory.buffering.memRequestBodyBytes=125000",
```
## Configuration Options
### maxRequestBodyBytes
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.
### 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.
### maxResponseBodyBytes
With the `maxReesponseBodyBytes` option, you can configure 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.
### 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.
### 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"
```
retryExpression = "IsNetworkError() && Attempts() < 2"
```
Available functions for the retry expression are:
- `Attempts()` number of attempts (the first one counts)
- `ResponseCode()` response code of the service
- `IsNetworkError()` - if the response code is related to networking error

40
docs/content/middlewares/chain.md Normal file
View file

@ -0,0 +1,40 @@
# Chain
When One Isn't Enougth
{: .subtitle }
![Chain](../assets/img/middleware/chain.png)
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"
```toml
# ...
[Routers]
[Routers.router1]
service = "service1"
middlewares = ["secured"]
rule = "Host: mydomain"
[Middlewares]
[Middlewares.secured.Chain]
middlewares = ["https-only", "known-ips", "auth-users"]
[Middlewares.auth-users.BasicAuth]
users = ["test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"]
[Middlewares.https-only.SchemeRedirect]
scheme = "https"
[Middlewares.known-ips.ipWhiteList]
sourceRange = ["192.168.1.7", "x.x.x.x", "x.x.x.x"]
[Services]
[Services.service1]
[Services.service1.LoadBalancer]
[[Services.service1.LoadBalancer.Servers]]
URL = "http://127.0.0.1:80"
Weight = 1
```

146
docs/content/middlewares/circuitbreaker.md Normal file
View file

@ -0,0 +1,146 @@
# CircuitBreaker
Don't Waste Time Calling Unhealthy Services
{: .subtitle }
![CircuitBreaker](../assets/img/middleware/circuitbreaker.png)
The circuit breaker protects your system from stacking requests to unhealthy services (resulting in cascading failures).
When your system is healthy, the circuit is close (normal operations).
When your system becomes unhealthy, the circuit becomes open and the requests are no longer forwarded (but handled by a fallback mechanism).
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.
!!! 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.
## Configuration Examples
??? example "Latency Check -- Using Toml"
```toml
[middlewares]
[middlewares.latency-check.circuitbreaker]
expression = "LatencyAtQuantileMS(50.0) > 100"
```
??? example "Latency Check -- Using Docker Labels"
```yaml
# in a docker compose file
container-definition:
image: image-name
labels:
- "traefik.middlewares.latency-check.circuitbreaker.expression=LatencyAtQuantileMS(50.0) > 100"
```
## Possible States
There are three possible states for your circuit breaker:
- Close (your service operates normally)
- Open (the fallback mechanism takes over your service)
- Recovering (the circuit breaker tries to resume normal operations by progressively sending requests to your service)
### Close
While close, 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.
### 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.
### 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.
## 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).
The `expression` can check three different metrics:
- The network error ratio (`NetworkErrorRatio`)
- The status code ratio (`ResponseCodeRatio`)
- The latency at 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`
#### ResponseCodeRatio
You can trigger the circuit breaker 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).
#### LatencyAtQuantileMS
You can trigger the circuit breaker 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 lantency (quantile 50) reaches 100MS.
!!! Note
You must provide a float number (with the leading .0) for the quantile value
#### Using multiple metrics
You can combine multiple metrics using operators in your expression.
Supported operators are:
- AND (`&&`)
- OR (`||)
For example, `ResponseCodeRatio(500, 600, 0, 600) > 0.30 || NetworkErrorRatio() > 0.10` triggers the circuit breaker when 30% of the requests return a 5XX status code, or when the ratio of network errors reaches 10%.
#### Operators
Here is the list of supported operators:
- Greater than (`>`)
- Greater or equal than (`>=`)
- Lesser than (`<`)
- Lesser or equal than (`<=`)
- Not (`!`)
- 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.
### 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.
### FallbackDuration
By default, `FallbackDuration` is 10 seconds. This value cannot be configured.
### RecoveringDuration
The duration of the recovering mode (recovering state).
By default, `RecoveringDuration` is 10 seconds. This value cannot be configured.

34
docs/content/middlewares/compress.md Normal file
View file

@ -0,0 +1,34 @@
# Compress
Compressing the Response before Sending it to the Client
{: .subtitle }
![Compress](../assets/img/middleware/compress.png)
The Compress middleware enables the gzip compression.
## Configuration Examples
??? example "File -- enable gzip compression"
```toml
[Middlewares]
[Middlewares.test-compress.Compress]
```
??? example "Docker -- enable gzip compression"
```yml
a-container:
image: a-container-image
labels:
- "traefik.middlewares.test-compress.compress=true",
```
## Notes
Responses are compressed when:
* The response body is larger than `512` 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.

78
docs/content/middlewares/digestauth.md Normal file
View file

@ -0,0 +1,78 @@
# DigestAuth
Adding Digest Authentication
{: .subtitle }
![BasicAuth](../assets/img/middleware/digestauth.png)
The DigestAuth middleware is a quick way to restrict access to your services to known users.
## Configuration Examples
??? example "File -- Declaring the user list"
```toml
[Middlewares]
[Middlewares.test-auth.digestauth]
users = ["test:traefik:a2688e031edb4be6a3797f3882655c05", "test2:traefik:518845800f9e2bfb1f1f740ec24f074e"]
```
??? example "Docker -- Using an external file for the authorized users"
```yml
a-container:
image: a-container-image
labels:
- "traefik.middlewares.declared-users-only.digestauth.usersFile=path-to-file.ext",
```
!!! tip
Use `htdigest` to generate passwords.
## Configuration Options
### Users
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 content of `usersFile` has precedence over `users`.
### UsersFile
The `usersFile` option is the path to an external file that contains the authorized users for the middleware.
The file content is a list of `name:realm:encoded-password`.
??? example "A file containing test/test and test2/test2"
```
test:traefik:a2688e031edb4be6a3797f3882655c05
test2:traefik:518845800f9e2bfb1f1f740ec24f074e
```
!!! Note
If both `users` and `usersFile` are provided, the two are merged. The content of `usersFile` has precedence over `users`.
### Realm
You can customize the realm for the authentication with the `realm` option. The default value is `traefik`.
### HeaderField
You can customize the header field for the authenticated user using the `headerField`option.
??? example "File -- Passing Authenticated Users to Services Via Headers"
```toml
[Middlewares.my-auth.digestauth]
usersFile = "path-to-file.ext"
headerField = "X-WebAuth-User" # header for the authenticated user
```
### RemoveHeader
Set the `removeHeader` option to `true` to remove the authorization header before forwarding the request to your service. (Default value is `false`.)

66
docs/content/middlewares/errorpages.md Normal file
View file

@ -0,0 +1,66 @@
# ErrorPage
It Has Never Been Easier to Say That Something Went Wrong
{: .subtitle }
![ErrorPages](../assets/img/middleware/errorpages.png)
The ErrorPage middleware returns a custom page in lieu of the default, according to configured ranges of HTTP Status codes.
!!! important
The error page itself is _not_ hosted by Traefik.
## Configuration Examples
??? example "File -- Custom Error Page for 5XX"
```toml
[Routers]
[Routers.router1]
Service = "my-service"
Rule = Host(`my-domain`)
[Middlewares]
[Middlewares.5XX-errors.Errors]
status = ["500-599"]
service = "error-handler-service"
query = "/error.html"
[Services]
# ... definition of error-handler-service and my-service
```
??? example "Docker -- Dynamic Custom Error Page for 5XX Status Code"
```yaml
a-container:
image: a-container-image
labels:
- "traefik.middlewares.test-errorpage.errors.status=500-599",
- "traefik.middlewares.test-errorpage.errors.service=serviceError",
- "traefik.middlewares.test-errorpage.errors.query=/{status}.html",
```
!!! 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 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`.
### service
The service that will serve the new requested error page.
### 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.

63
docs/content/middlewares/forwardauth.md Normal file
View file

@ -0,0 +1,63 @@
# ForwardAuth
Using an External Service to Ccheck for Credentials
{: .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.
Otherwise, the response from the authentication server is returned.
## Configuration Examples
??? example "File -- Forward authentication to authserver.com"
```toml
[Middlewares]
[Middlewares.test-auth.forwardauth]
address = "https://authserver.com/auth"
trustForwardHeader = true
authResponseHeaders = ["X-Auth-User", "X-Secret"]
[Middlewares.test-auth.forwardauth.tls]
ca = "path/to/local.crt"
caOptional = true
cert = "path/to/foo.cert"
key = "path/to/foo.key"
```
??? example "Docker -- Forward authentication to authserver.com"
```yml
a-container:
image: a-container-image
labels:
- "traefik.Middlewares.test-auth.ForwardAuth.Address=https://authserver.com/auth"
- "traefik.Middlewares.test-auth.ForwardAuth.AuthResponseHeaders=X-Auth-User, X-Secret"
- "traefik.Middlewares.test-auth.ForwardAuth.TLS.CA=path/to/local.crt"
- "traefik.Middlewares.test-auth.ForwardAuth.TLS.CAOptional=true"
- "traefik.Middlewares.test-auth.ForwardAuth.TLS.Cert=path/to/foo.cert"
- "traefik.Middlewares.test-auth.ForwardAuth.TLS.InsecureSkipVerify=true"
- "traefik.Middlewares.test-auth.ForwardAuth.TLS.Key=path/to/foo.key"
- "traefik.Middlewares.test-auth.ForwardAuth.TrustForwardHeader=true"
```
## Configuration Options
### address
The `address` option defines the authentication server address.
### trustForwardHeader
Set the `trustForwardHeader` option to true to trust all the existing X-Forwarded-* headers.
### authResponseHeaders
The `authResponseHeaders` option is the list of the headers to copy from the authentication server to the request.
### tls
The `tls` option is the tls configuration from Traefik to the authentication server.

179
docs/content/middlewares/headers.md Normal file
View file

@ -0,0 +1,179 @@
# Headers
Adding Headers to the Request / Response
{: .subtitle }
![Headers](../assets/img/middleware/headers.png)
The Headers middleware can manage the requests/responses headers.
## 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
??? example "File"
```toml
[Middlewares]
[Middlewares.testHeader.headers]
[Middlewares.testHeader.headers.CustomRequestHeaders]
X-Script-Name = "test"
[Middlewares.testHeader.headers.CustomResponseHeaders]
X-Custom-Response-Header = "True"
```
??? example "Docker"
```yml
a-container:
image: a-container-image
labels:
- "traefik.Middlewares.testHeader.Headers.CustomRequestHeaders.X-Script-Name=test",
- "traefik.Middlewares.testHeader.Headers.CustomResponseHeaders.X-Custom-Response-Header=True",
```
### 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.
??? example "File"
```toml
[Middlewares]
[Middlewares.testHeader.headers]
[Middlewares.testHeader.headers.CustomRequestHeaders]
X-Script-Name = "test"
[Middlewares.testHeader.headers.CustomResponseHeaders]
X-Custom-Response-Header = "True"
```
??? example "Docker"
```yml
a-container:
image: a-container-image
labels:
- "traefik.Middlewares.testHeader.Headers.CustomRequestHeaders.X-Script-Name=test",
- "traefik.Middlewares.testHeader.Headers.CustomResponseHeaders.X-Custom-Response-Header=True",
```
### Using Security Headers
Security related headers (HSTS headers, SSL redirection, Browser XSS filter, etc) can be added and configured per frontend in a similar manner to the custom headers above.
This functionality allows for some easy security features to quickly be set.
??? example "File"
```toml
[Middlewares]
[Middlewares.testHeader.headers]
FrameDeny = true
SSLRedirect = true
```
??? example "Docker"
```yml
a-container:
image: a-container-image
labels:
- "traefik.Middlewares.testHeader.Headers.FrameDeny=true",
- "traefik.Middlewares.testHeader.Headers.SSLRedirect=true",
```
## Configuration Options
### General
!!! warning
If the custom header name is the same as one header name of the request or response, it will be replaced.
!!! note
The detailed documentation for the 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.
### allowedHosts
The `allowedHosts` option lists fully qualified domain names that are allowed.
### hostsProxyHeaders
The `hostsProxyHeaders` option is a set of header keys that may hold a proxied hostname value for the request.
### sslRedirect
The `sslRedirect` is set to true, then only allow https requests.
### sslTemporaryRedirect
Set the `sslTemporaryRedirect` to `true` to force an SSL redirection using a 302 (instead of a 301).
### sslHost
The `SSLHost` option is the host name that is used to redirect http requests to https.
### sslProxyHeaders
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"`.
### sslForceHost
Set `sslForceHost` to true and set SSLHost to forced requests to use `SSLHost` even the ones that are already using SSL.
### stsSeconds
The `stsSeconds` is the max-age of the Strict-Transport-Security header. If set to 0, would NOT include the header.
### stsIncludeSubdomains
The `stsIncludeSubdomains` is set to true, the `includeSubdomains` will be 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.
### frameDeny
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.
### contentTypeNosniff
Set `contentTypeNosniff` to true to add the `X-Content-Type-Options` header with the value `nosniff`.
### browserXssFilter
Set `BrowserXssFilter` to true to add the `X-XSS-Protection` header with the value `1; mode=block`.
### customBrowserXSSValue
The `customBrowserXssValue` option allows the `X-XSS-Protection` header value to be set with a custom value. This overrides the BrowserXssFilter option.
### contentSecurityPolicy
The `contentSecurityPolicy` option allows the `Content-Security-Policy` header value to be set with a custom value.
### publicKey
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.
### 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.

113
docs/content/middlewares/ipwhitelist.md Normal file
View file

@ -0,0 +1,113 @@
# IPWhiteList
Limiting Clients to Specific IPs
{: .subtitle }
![IpWhiteList](../assets/img/middleware/ipwhitelist.png)
IPWhitelist accepts / refuses requests based on the client IP.
## Configuration Examples
??? example "File -- Accepts request from defined IP"
```toml
[Middlewares]
[Middlewares.test-ipwhitelist.ipWhiteList]
sourceRange = ["127.0.0.1/32", "192.168.1.7"]
```
??? example "Docker -- Accepts request from defined IP"
```yml
a-container:
image: a-container-image
labels:
- "traefik.Middlewares.Middleware9.IPWhiteList.SourceRange=127.0.0.1/32, 192.168.1.7"
```
## Configuration Options
### sourceRange
The `sourceRange` option sets the allowed IPs (or ranges of allowed IPs).
### ipStrategy
The `ipStrategy` option defines two parameters that sets how Traefik will determine 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).
!!! note "Examples of Depth & X-Forwaded-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` | `""` |
??? example "File -- Whitelisting Based on `X-Forwarded-For` with `depth=2`"
```toml
[Middlewares]
[Middlewares.test-ipwhitelist.ipWhiteList]
sourceRange = ["127.0.0.1/32", "192.168.1.7"]
[Middlewares.test-ipwhitelist.ipWhiteList.ipStrategy]
depth = 2
```
??? example "Docker -- Whitelisting Based on `X-Forwarded-For` with `depth=2`"
```yml
a-container:
image: a-container-image
labels:
- "traefik.Middlewares.testIPwhitelist.ipWhiteList.SourceRange=127.0.0.1/32, 192.168.1.7"
- "traefik.middlewares.testIPwhitelist.ipwhitelist.ipstrategy.depth=2"
```
!!! note
- 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 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-Forwaded-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.
??? example "File -- Exclude from `X-Forwarded-For`"
```toml
[Middlewares]
[Middlewares.test-ipwhitelist.ipWhiteList]
[Middlewares.test-ipwhitelist.ipWhiteList.ipStrategy]
excludedIPs = ["127.0.0.1/32", "192.168.1.7"]
```
??? example "Docker -- Exclude from `X-Forwarded-For`"
```yml
a-container:
image: a-container-image
labels:
- "traefik.middlewares.testIPwhitelist.ipwhitelist.ipstrategy.excludedIPs=127.0.0.1/32, 192.168.1.7"
```

44
docs/content/middlewares/maxconnection.md Normal file
View file

@ -0,0 +1,44 @@
# MaxConnection
Limiting the Number of Simultaneous Clients
{: .subtitle }
![MaxConnection](../assets/img/middleware/maxconnection.png)
To proactively prevent services from being overwhelmed with high load, a maximum connection limit can be applied.
## Configuration Examples
??? example "File -- Limiting to 10 simultaneous connections"
```toml
[Middlewares]
[Middlewares.test-maxconn.maxconn]
amount = 10
```
??? example "Docker -- Limiting to 10 simultaneous connections"
```yml
a-container:
image: a-container-image
labels:
- "traefik.middlewares.test-maxconn.maxconn.amount=10"
```
## Configuration Options
### amount
The `amount` option defines the maximum amount of allowed simultaneous connections.
The middleware will return an `HTTP 429 Too Many Requests` if there are already `amount` requests in progress (based on the same `extractorfunc` strategy).
### extractorfunc
The `extractorfunc` defines the strategy used to categorize requests.
The possible values are:
- `request.host` categorizes requests based on the request host.
- `client.ip` categorizes requests based on the client ip.
- `request.header.ANY_HEADER` categorizes requests based on the provided `ANY_HEADER` value.

106
docs/content/middlewares/overview.md Normal file
View file

@ -0,0 +1,106 @@
# Middlewares
Tweaking the Request
{: .subtitle }
![Overview](../assets/img/middleware/overview.png)
Attached to the routers, pieces of middleware are a mean of tweaking the requests before they are sent to your [service](../routing/services.md) (or before the answer from the services are sent to the clients).
There are many different available middlewares in Traefik, some can modify the request, the headers, some are in charge of redirections, some add authentication, and so on.
Pieces of middleware can be combined in chains to fit every scenario.
## Configuration Example
??? example "As Toml Configuration File"
```toml
[providers]
[providers.file]
[Routers]
[Routers.router1]
Service = "myService"
Middlewares = ["foo-add-prefix"]
Rule = "Host: example.com"
[Middlewares]
[Middlewares.foo-add-prefix.AddPrefix]
prefix = "/foo"
[Services]
[Services.service1]
[Services.service1.LoadBalancer]
[[Services.service1.LoadBalancer.Servers]]
URL = "http://127.0.0.1:80"
Weight = 1
```
??? example "As a Docker Label"
```yaml
# A container that exposes a simple API
whoami:
image: containous/whoami # A container that exposes an API to show its IP address
labels:
- "traefik.middlewares.foo-add-prefix.addprefix.prefix=/foo",
```
## Advanced Configuration
When you declare a middleware, it lives in its `provider` namespace.
For example, if you declare a middleware using a Docker label, under the hoods, it will reside in the docker `provider` namespace.
If you use multiple `providers` and wish to reference a middleware declared in another `provider`, then you'll have to prefix the middleware name with the `provider` name.
??? abstract "Referencing a Middleware from Another Provider"
Declaring the add-foo-prefix in the file provider.
```toml
[providers]
[providers.file]
[middlewares]
[middlewares.add-foo-prefix.AddPrefix]
prefix = "/foo"
```
Using the add-foo-prefix middleware from docker.
```yaml
your-container: #
image: your-docker-image
labels:
# Attach file.add-foo-prefix middleware (declared in file)
- "traefik.routers.middlewares=file.add-foo-prefix",
```
## Available Middlewares
| Middleware | Purpose | Area |
|-------------------------------------------|---------------------------------------------------|-----------------------------|
| [AddPrefix](addprefix.md) | Add a Path Prefix | Path Modifier |
| [BasicAuth](basicauth.md) | Basic auth mechanism | Security, Authentication |
| [Buffering](buffering.md) | Buffers the request/response | Request Lifecycle |
| [Chain](chain.md) | Combine multiple pieces of middleware | Middleware tool |
| [CircuitBreaker](circuitbreaker.md) | Stop calling unhealthy services | Request Lifecycle |
| [Compress](circuitbreaker.md) | Compress the response | Content Modifier |
| [DigestAuth](digestauth.md) | Adds Digest Authentication | Security, Authentication |
| [Errors](errorpages.md) | Define custom error pages | Request Lifecycle |
| [ForwardAuth](forwardauth.md) | Authentication delegation | Security, Authentication |
| [Headers](headers.md) | Add / Update headers | Security |
| [IPWhiteList](ipwhitelist.md) | Limit the allowed client IPs | Security, Request lifecycle |
| [MaxConnection](maxconnection.md) | Limit the number of simultaneous connections | Security, Request lifecycle |
| [PassTLSClientCert](passtlsclientcert.md) | TODO | Security |
| [RateLimit](ratelimit.md) | Limit the call frequency | Security, Request lifecycle |
| [RedirectScheme](redirectscheme.md) | Redirect easily the client elsewhere | Request lifecycle |
| [RedirectRegex](redirectregex.md) | Redirect the client elsewhere | Request lifecycle |
| [ReplacePath](replacepath.md) | Change the path of the request | Path Modifier |
| [ReplacePathRegex](replacepathregex.md) | Change the path of the request | Path Modifier |
| [Retry](retry.md) | Automatically retry the request in case of errors | Request lifecycle |
| [StripPrefix](stripprefix.md) | Change the path of the request | Path Modifier |
| [StripPrefixRegex](stripprefixregex.md) | Change the path of the request | Path Modifier |

499
docs/content/middlewares/passtlsclientcert.md Normal file
View file

@ -0,0 +1,499 @@
# TODO - PassTLSClientCert
Adding Client Certificates in a Header
{: .subtitle }
`TODO add schema`
PassTLSClientCert adds in header the selected data from the passed client tls certificate.
## Configuration Examples
??? example "File -- Pass the escaped pem in the `X-Forwarded-Tls-Client-Cert` header"
```toml
[Middlewares]
[Middlewares.test-passtlsclientcert.passtlsclientcert]
pem = true
```
??? example "Docker -- Pass the escaped pem in the `X-Forwarded-Tls-Client-Cert` header"
```yml
a-container:
image: a-container-image
labels:
- "traefik.middlewares.Middleware11.passtlsclientcert.pem=true"
```
??? example "File -- Pass all the available info in the `X-Forwarded-Tls-Client-Cert-Info` header"
```toml
[Middlewares]
[Middlewares.test-passtlsclientcert.passtlsclientcert]
[Middlewares.test-passtlsclientcert.passtlsclientcert.info]
notAfter = true
notBefore = true
sans = true
[Middlewares.test-passtlsclientcert.passtlsclientcert.info.subject]
country = true
province = true
locality = true
organization = true
commonName = true
serialNumber = true
domainComponent = true
[Middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer]
country = true
province = true
locality = true
organization = true
commonName = true
serialNumber = true
domainComponent = true
```
??? example "Docker -- Pass all the available info in the `X-Forwarded-Tls-Client-Cert-Info` header"
```yml
a-container:
image: a-container-image
labels:
- "traefik.middlewares.test-passtlsclientcert.passtlsclientcert.info.notafter=true"
- "traefik.middlewares.test-passtlsclientcert.passtlsclientcert.info.notbefore=true"
- "traefik.middlewares.test-passtlsclientcert.passtlsclientcert.info.sans=true"
- "traefik.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.commonname=true"
- "traefik.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.country=true"
- "traefik.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.domaincomponent=true"
- "traefik.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.locality=true"
- "traefik.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.organization=true"
- "traefik.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.province=true"
- "traefik.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.serialnumber=true"
- "traefik.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.commonname=true"
- "traefik.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.country=true"
- "traefik.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.domaincomponent=true"
- "traefik.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.locality=true"
- "traefik.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.organization=true"
- "traefik.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.province=true"
- "traefik.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.serialnumber=true"
```
## Configuration Options
### General
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
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 explains the middleware options.
??? example "A complete client tls certificate"
```
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 1 (0x1)
Signature Algorithm: sha1WithRSAEncryption
Issuer: DC=org, DC=cheese, O=Cheese, O=Cheese 2, OU=Simple Signing Section, OU=Simple Signing Section 2, CN=Simple Signing CA, CN=Simple Signing CA 2, C=FR, C=US, L=TOULOUSE, L=LYON, ST=Signing State, ST=Signing State 2/emailAddress=simple@signing.com/emailAddress=simple2@signing.com
Validity
Not Before: Dec 6 11:10:16 2018 GMT
Not After : Dec 5 11:10:16 2020 GMT
Subject: DC=org, DC=cheese, O=Cheese, O=Cheese 2, OU=Simple Signing Section, OU=Simple Signing Section 2, CN=*.cheese.org, CN=*.cheese.com, C=FR, C=US, L=TOULOUSE, L=LYON, ST=Cheese org state, ST=Cheese com state/emailAddress=cert@cheese.org/emailAddress=cert@scheese.com
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
RSA Public-Key: (2048 bit)
Modulus:
00:de:77:fa:8d:03:70:30:39:dd:51:1b:cc:60:db:
a9:5a:13:b1:af:fe:2c:c6:38:9b:88:0a:0f:8e:d9:
1b:a1:1d:af:0d:66:e4:13:5b:bc:5d:36:92:d7:5e:
d0:fa:88:29:d3:78:e1:81:de:98:b2:a9:22:3f:bf:
8a:af:12:92:63:d4:a9:c3:f2:e4:7e:d2:dc:a2:c5:
39:1c:7a:eb:d7:12:70:63:2e:41:47:e0:f0:08:e8:
dc:be:09:01:ec:28:09:af:35:d7:79:9c:50:35:d1:
6b:e5:87:7b:34:f6:d2:31:65:1d:18:42:69:6c:04:
11:83:fe:44:ae:90:92:2d:0b:75:39:57:62:e6:17:
2f:47:2b:c7:53:dd:10:2d:c9:e3:06:13:d2:b9:ba:
63:2e:3c:7d:83:6b:d6:89:c9:cc:9d:4d:bf:9f:e8:
a3:7b:da:c8:99:2b:ba:66:d6:8e:f8:41:41:a0:c9:
d0:5e:c8:11:a4:55:4a:93:83:87:63:04:63:41:9c:
fb:68:04:67:c2:71:2f:f2:65:1d:02:5d:15:db:2c:
d9:04:69:85:c2:7d:0d:ea:3b:ac:85:f8:d4:8f:0f:
c5:70:b2:45:e1:ec:b2:54:0b:e9:f7:82:b4:9b:1b:
2d:b9:25:d4:ab:ca:8f:5b:44:3e:15:dd:b8:7f:b7:
ee:f9
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Key Usage: critical
Digital Signature, Key Encipherment
X509v3 Basic Constraints:
CA:FALSE
X509v3 Extended Key Usage:
TLS Web Server Authentication, TLS Web Client Authentication
X509v3 Subject Key Identifier:
94:BA:73:78:A2:87:FB:58:28:28:CF:98:3B:C2:45:70:16:6E:29:2F
X509v3 Authority Key Identifier:
keyid:1E:52:A2:E8:54:D5:37:EB:D5:A8:1D:E4:C2:04:1D:37:E2:F7:70:03
X509v3 Subject Alternative Name:
DNS:*.cheese.org, DNS:*.cheese.net, DNS:*.cheese.com, IP Address:10.0.1.0, IP Address:10.0.1.2, email:test@cheese.org, email:test@cheese.net
Signature Algorithm: sha1WithRSAEncryption
76:6b:05:b0:0e:34:11:b1:83:99:91:dc:ae:1b:e2:08:15:8b:
16:b2:9b:27:1c:02:ac:b5:df:1b:d0:d0:75:a4:2b:2c:5c:65:
ed:99:ab:f7:cd:fe:38:3f:c3:9a:22:31:1b:ac:8c:1c:c2:f9:
5d:d4:75:7a:2e:72:c7:85:a9:04:af:9f:2a:cc:d3:96:75:f0:
8e:c7:c6:76:48:ac:45:a4:b9:02:1e:2f:c0:15:c4:07:08:92:
cb:27:50:67:a1:c8:05:c5:3a:b3:a6:48:be:eb:d5:59:ab:a2:
1b:95:30:71:13:5b:0a:9a:73:3b:60:cc:10:d0:6a:c7:e5:d7:
8b:2f:f9:2e:98:f2:ff:81:14:24:09:e3:4b:55:57:09:1a:22:
74:f1:f6:40:13:31:43:89:71:0a:96:1a:05:82:1f:83:3a:87:
9b:17:25:ef:5a:55:f2:2d:cd:0d:4d:e4:81:58:b6:e3:8d:09:
62:9a:0c:bd:e4:e5:5c:f0:95:da:cb:c7:34:2c:34:5f:6d:fc:
60:7b:12:5b:86:fd:df:21:89:3b:48:08:30:bf:67:ff:8c:e6:
9b:53:cc:87:36:47:70:40:3b:d9:90:2a:d2:d2:82:c6:9c:f5:
d1:d8:e0:e6:fd:aa:2f:95:7e:39:ac:fc:4e:d4:ce:65:b3:ec:
c6:98:8a:31
-----BEGIN CERTIFICATE-----
MIIGWjCCBUKgAwIBAgIBATANBgkqhkiG9w0BAQUFADCCAYQxEzARBgoJkiaJk/Is
ZAEZFgNvcmcxFjAUBgoJkiaJk/IsZAEZFgZjaGVlc2UxDzANBgNVBAoMBkNoZWVz
ZTERMA8GA1UECgwIQ2hlZXNlIDIxHzAdBgNVBAsMFlNpbXBsZSBTaWduaW5nIFNl
Y3Rpb24xITAfBgNVBAsMGFNpbXBsZSBTaWduaW5nIFNlY3Rpb24gMjEaMBgGA1UE
AwwRU2ltcGxlIFNpZ25pbmcgQ0ExHDAaBgNVBAMME1NpbXBsZSBTaWduaW5nIENB
IDIxCzAJBgNVBAYTAkZSMQswCQYDVQQGEwJVUzERMA8GA1UEBwwIVE9VTE9VU0Ux
DTALBgNVBAcMBExZT04xFjAUBgNVBAgMDVNpZ25pbmcgU3RhdGUxGDAWBgNVBAgM
D1NpZ25pbmcgU3RhdGUgMjEhMB8GCSqGSIb3DQEJARYSc2ltcGxlQHNpZ25pbmcu
Y29tMSIwIAYJKoZIhvcNAQkBFhNzaW1wbGUyQHNpZ25pbmcuY29tMB4XDTE4MTIw
NjExMTAxNloXDTIwMTIwNTExMTAxNlowggF2MRMwEQYKCZImiZPyLGQBGRYDb3Jn
MRYwFAYKCZImiZPyLGQBGRYGY2hlZXNlMQ8wDQYDVQQKDAZDaGVlc2UxETAPBgNV
BAoMCENoZWVzZSAyMR8wHQYDVQQLDBZTaW1wbGUgU2lnbmluZyBTZWN0aW9uMSEw
HwYDVQQLDBhTaW1wbGUgU2lnbmluZyBTZWN0aW9uIDIxFTATBgNVBAMMDCouY2hl
ZXNlLm9yZzEVMBMGA1UEAwwMKi5jaGVlc2UuY29tMQswCQYDVQQGEwJGUjELMAkG
A1UEBhMCVVMxETAPBgNVBAcMCFRPVUxPVVNFMQ0wCwYDVQQHDARMWU9OMRkwFwYD
VQQIDBBDaGVlc2Ugb3JnIHN0YXRlMRkwFwYDVQQIDBBDaGVlc2UgY29tIHN0YXRl
MR4wHAYJKoZIhvcNAQkBFg9jZXJ0QGNoZWVzZS5vcmcxHzAdBgkqhkiG9w0BCQEW
EGNlcnRAc2NoZWVzZS5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB
AQDed/qNA3AwOd1RG8xg26laE7Gv/izGOJuICg+O2RuhHa8NZuQTW7xdNpLXXtD6
iCnTeOGB3piyqSI/v4qvEpJj1KnD8uR+0tyixTkceuvXEnBjLkFH4PAI6Ny+CQHs
KAmvNdd5nFA10Wvlh3s09tIxZR0YQmlsBBGD/kSukJItC3U5V2LmFy9HK8dT3RAt
yeMGE9K5umMuPH2Da9aJycydTb+f6KN72siZK7pm1o74QUGgydBeyBGkVUqTg4dj
BGNBnPtoBGfCcS/yZR0CXRXbLNkEaYXCfQ3qO6yF+NSPD8VwskXh7LJUC+n3grSb
Gy25JdSryo9bRD4V3bh/t+75AgMBAAGjgeAwgd0wDgYDVR0PAQH/BAQDAgWgMAkG
A1UdEwQCMAAwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMB0GA1UdDgQW
BBSUunN4oof7WCgoz5g7wkVwFm4pLzAfBgNVHSMEGDAWgBQeUqLoVNU369WoHeTC
BB034vdwAzBhBgNVHREEWjBYggwqLmNoZWVzZS5vcmeCDCouY2hlZXNlLm5ldIIM
Ki5jaGVlc2UuY29thwQKAAEAhwQKAAECgQ90ZXN0QGNoZWVzZS5vcmeBD3Rlc3RA
Y2hlZXNlLm5ldDANBgkqhkiG9w0BAQUFAAOCAQEAdmsFsA40EbGDmZHcrhviCBWL
FrKbJxwCrLXfG9DQdaQrLFxl7Zmr983+OD/DmiIxG6yMHML5XdR1ei5yx4WpBK+f
KszTlnXwjsfGdkisRaS5Ah4vwBXEBwiSyydQZ6HIBcU6s6ZIvuvVWauiG5UwcRNb
CppzO2DMENBqx+XXiy/5Lpjy/4EUJAnjS1VXCRoidPH2QBMxQ4lxCpYaBYIfgzqH
mxcl71pV8i3NDU3kgVi2440JYpoMveTlXPCV2svHNCw0X238YHsSW4b93yGJO0gI
ML9n/4zmm1PMhzZHcEA72ZAq0tKCxpz10djg5v2qL5V+Oaz8TtTOZbPsxpiKMQ==
-----END CERTIFICATE-----
```
### pem
The `pem` option sets the `X-Forwarded-Tls-Client-Cert` header with the escape certificate.
In the example, it is the part between `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` delimiters :
??? example "The data used by the pem option"
```
-----BEGIN CERTIFICATE-----
MIIGWjCCBUKgAwIBAgIBATANBgkqhkiG9w0BAQUFADCCAYQxEzARBgoJkiaJk/Is
ZAEZFgNvcmcxFjAUBgoJkiaJk/IsZAEZFgZjaGVlc2UxDzANBgNVBAoMBkNoZWVz
ZTERMA8GA1UECgwIQ2hlZXNlIDIxHzAdBgNVBAsMFlNpbXBsZSBTaWduaW5nIFNl
Y3Rpb24xITAfBgNVBAsMGFNpbXBsZSBTaWduaW5nIFNlY3Rpb24gMjEaMBgGA1UE
AwwRU2ltcGxlIFNpZ25pbmcgQ0ExHDAaBgNVBAMME1NpbXBsZSBTaWduaW5nIENB
IDIxCzAJBgNVBAYTAkZSMQswCQYDVQQGEwJVUzERMA8GA1UEBwwIVE9VTE9VU0Ux
DTALBgNVBAcMBExZT04xFjAUBgNVBAgMDVNpZ25pbmcgU3RhdGUxGDAWBgNVBAgM
D1NpZ25pbmcgU3RhdGUgMjEhMB8GCSqGSIb3DQEJARYSc2ltcGxlQHNpZ25pbmcu
Y29tMSIwIAYJKoZIhvcNAQkBFhNzaW1wbGUyQHNpZ25pbmcuY29tMB4XDTE4MTIw
NjExMTAxNloXDTIwMTIwNTExMTAxNlowggF2MRMwEQYKCZImiZPyLGQBGRYDb3Jn
MRYwFAYKCZImiZPyLGQBGRYGY2hlZXNlMQ8wDQYDVQQKDAZDaGVlc2UxETAPBgNV
BAoMCENoZWVzZSAyMR8wHQYDVQQLDBZTaW1wbGUgU2lnbmluZyBTZWN0aW9uMSEw
HwYDVQQLDBhTaW1wbGUgU2lnbmluZyBTZWN0aW9uIDIxFTATBgNVBAMMDCouY2hl
ZXNlLm9yZzEVMBMGA1UEAwwMKi5jaGVlc2UuY29tMQswCQYDVQQGEwJGUjELMAkG
A1UEBhMCVVMxETAPBgNVBAcMCFRPVUxPVVNFMQ0wCwYDVQQHDARMWU9OMRkwFwYD
VQQIDBBDaGVlc2Ugb3JnIHN0YXRlMRkwFwYDVQQIDBBDaGVlc2UgY29tIHN0YXRl
MR4wHAYJKoZIhvcNAQkBFg9jZXJ0QGNoZWVzZS5vcmcxHzAdBgkqhkiG9w0BCQEW
EGNlcnRAc2NoZWVzZS5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB
AQDed/qNA3AwOd1RG8xg26laE7Gv/izGOJuICg+O2RuhHa8NZuQTW7xdNpLXXtD6
iCnTeOGB3piyqSI/v4qvEpJj1KnD8uR+0tyixTkceuvXEnBjLkFH4PAI6Ny+CQHs
KAmvNdd5nFA10Wvlh3s09tIxZR0YQmlsBBGD/kSukJItC3U5V2LmFy9HK8dT3RAt
yeMGE9K5umMuPH2Da9aJycydTb+f6KN72siZK7pm1o74QUGgydBeyBGkVUqTg4dj
BGNBnPtoBGfCcS/yZR0CXRXbLNkEaYXCfQ3qO6yF+NSPD8VwskXh7LJUC+n3grSb
Gy25JdSryo9bRD4V3bh/t+75AgMBAAGjgeAwgd0wDgYDVR0PAQH/BAQDAgWgMAkG
A1UdEwQCMAAwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMB0GA1UdDgQW
BBSUunN4oof7WCgoz5g7wkVwFm4pLzAfBgNVHSMEGDAWgBQeUqLoVNU369WoHeTC
BB034vdwAzBhBgNVHREEWjBYggwqLmNoZWVzZS5vcmeCDCouY2hlZXNlLm5ldIIM
Ki5jaGVlc2UuY29thwQKAAEAhwQKAAECgQ90ZXN0QGNoZWVzZS5vcmeBD3Rlc3RA
Y2hlZXNlLm5ldDANBgkqhkiG9w0BAQUFAAOCAQEAdmsFsA40EbGDmZHcrhviCBWL
FrKbJxwCrLXfG9DQdaQrLFxl7Zmr983+OD/DmiIxG6yMHML5XdR1ei5yx4WpBK+f
KszTlnXwjsfGdkisRaS5Ah4vwBXEBwiSyydQZ6HIBcU6s6ZIvuvVWauiG5UwcRNb
CppzO2DMENBqx+XXiy/5Lpjy/4EUJAnjS1VXCRoidPH2QBMxQ4lxCpYaBYIfgzqH
mxcl71pV8i3NDU3kgVi2440JYpoMveTlXPCV2svHNCw0X238YHsSW4b93yGJO0gI
ML9n/4zmm1PMhzZHcEA72ZAq0tKCxpz10djg5v2qL5V+Oaz8TtTOZbPsxpiKMQ==
-----END CERTIFICATE-----
```
!!! note "Extracted data"
The delimiters and `\n` will be removed.
If there are more than one certificate, they are separated by a "`;`".
### 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 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=*.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"
If there are more than one certificate, they are separated by a `;`.
#### info.notafter
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:
```text
Validity
Not After : Dec 5 11:10:16 2020 GMT
```
The escape `notafter` info part will be like:
```text
NA=1607166616
```
#### info.notbefore
Set the `info.notafter` option to `true` to add the `Not Before` information from the `Validity` part.
The data are taken from the following certificate part:
```text
Validity
Not Before: Dec 6 11:10:16 2018 GMT
```
The escape `notafter` info part will be like:
```text
NB=1544094616
```
#### info.sans
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:
```text
X509v3 Subject Alternative Name:
DNS:*.cheese.org, DNS:*.cheese.net, DNS:*.cheese.com, IP Address:10.0.1.0, IP Address:10.0.1.2, email:test@cheese.org, email:test@cheese.net
```
The escape SANs info part will be like:
```text
SAN=*.cheese.org,*.cheese.net,*.cheese.com,test@cheese.org,test@cheese.net,10.0.1.0,10.0.1.2
```
!!! note "multiple values"
All the SANs data 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 data are 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=*.cheese.org, CN=*.cheese.com, C=FR, C=US, L=TOULOUSE, L=LYON, ST=Cheese org state, ST=Cheese com state/emailAddress=cert@cheese.org/emailAddress=cert@scheese.com
```
##### 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 :
```text
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.
The escape province info in the subject part will be like :
```text
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.
The escape locality info in the subject part will be like :
```text
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.
The escape organization info in the subject part will be like :
```text
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.
The escape commonname info in the subject part will be like :
```text
CN=*.cheese.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.
The escape serialnumber info in the subject part will be like :
```text
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.
The escape domaincomponent info in the subject part will be like :
```text
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 data are 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
```
##### 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 :
```text
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.
The escape province info in the issuer part will be like :
```text
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.
The escape locality info in the issuer part will be like :
```text
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.
The escape organization info in the issuer part will be like :
```text
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.
The escape commonname info in the issuer part will be like :
```text
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.
The escape serialnumber info in the issuer part will be like :
```text
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.
The escape domaincomponent info in the issuer part will be like :
```text
DC=org,DC=cheese
```

68
docs/content/middlewares/ratelimit.md Normal file
View file

@ -0,0 +1,68 @@
# TODO -- RateLimit
Protection from Too Many Calls
{: .subtitle }
![RateLimit](../assets/img/middleware/ratelimit.png)
The RateLimit middleware ensures that services will receive a _fair_ number of requests, and allows you define what is fair.
## Configuration Example
??? example "Limit to 100 requests every 10 seconds (with a possible burst of 200)"
```toml
[middlewares]
[middlewares.fair-ratelimit.ratelimit]
extractorfunc = "client.ip"
[middlewares.fair-ratelimit.ratelimit.rateset1]
period = "10s"
average = 100
burst = 200
```
??? example "Combine multiple limits"
```toml
[middlewares]
[middlewares.fair-ratelimit.ratelimit]
extractorfunc = "client.ip"
[middlewares.fair-ratelimit.ratelimit.rateset1]
period = "10s"
average = 100
burst = 200
[middlewares.fair-ratelimit.ratelimit.rateset2]
period = "3s"
average = 5
burst = 10
```
Here, an average of 5 requests every 3 seconds is allowed and an average of 100 requests every 10 seconds. These can "burst" up to 10 and 200 in each period, respectively.
## Configuration Options
### extractorfunc
The `extractorfunc` option defines the strategy used to categorize requests.
The possible values are:
- `request.host` categorizes requests based on the request host.
- `client.ip` categorizes requests based on the client ip.
- `request.header.ANY_HEADER` categorizes requests based on the provided `ANY_HEADER` value.
### ratelimit (multiple values)
You can combine multiple ratelimit.
The ratelimit will trigger with the first reached limit.
Each ratelimit has 3 options, `period`, `average`, and `burst`.
The rate limit will allow an average of `average` requests every `period`, with a maximum of `burst` request on that period.
!!! note "Period Format"
Period is to be given in a format understood by [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration).

52
docs/content/middlewares/redirectregex.md Normal file
View file

@ -0,0 +1,52 @@
# TODO - RedirectRegex
Redirecting the Client to a Different Location
{: .subtitle }
`TODO: add schema`
RegexRedirect redirect a request from an url to another with regex matching and replacement.
## Configuration Examples
??? example "File -- Redirect with domain replacement"
```toml
[Middlewares]
[Middlewares.test-redirectregex.redirectregex]
regex = "^http://localhost/(.*)"
replacement = "http://mydomain/$1"
```
??? example "Docker -- Redirect with domain replacement"
```yml
a-container:
image: a-container-image
labels:
- "traefik.Middlewares.test-redirectregex.redirectregex.regex=^http://localhost/(.*)"
- "traefik.Middlewares.test-redirectregex.redirectregex.replacement=http://mydomain/$1"
```
## Configuration Options
### permanent
Set the `permanent` option to `true` to apply a permanent redirection.
### regex
The `Regex` option is the regular expression to match and capture elements form 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.

41
docs/content/middlewares/redirectscheme.md Normal file
View file

@ -0,0 +1,41 @@
# TODO - RedirectScheme
Redirecting the Client to a Different Scheme/Port
{: .subtitle }
`TODO: add schema`
RegexRedirect redirect request from a scheme to another.
## Configuration Examples
??? example "File -- Redirect to https"
```toml
[Middlewares]
[Middlewares.test-redirectscheme.redirectscheme]
scheme = "https"
```
??? example "Docker -- Redirect to https"
```yml
a-container:
image: a-container-image
labels:
- "traefik.Middlewares.test-redirectscheme.redirectscheme.scheme=https"
```
## Configuration Options
### permanent
Set the `permanent` option to `true` to apply a permanent redirection.
### scheme
The `scheme` option defines the scheme of the new url.
### port
The `port` option defines the port of the new url.

40
docs/content/middlewares/replacepath.md Normal file
View file

@ -0,0 +1,40 @@
# TODO -- ReplacePath
Updating the Path Before Forwarding the Request
{: .subtitle }
`TODO: add schema`
Replace the path of the request url.
## Configuration Examples
??? example "File -- Replace the path by /foo"
```toml
[Middlewares]
[Middlewares.test-replacepath.ReplacePath]
path = "/foo"
```
??? example "Docker --Replace the path by /foo"
```yaml
a-container:
image: a-container-image
labels:
- "traefik.middlewares.test-replacepath.replacepath.path=/foo"
```
## Configuration Options
### General
The ReplacePath middleware will:
* replace the actual path by 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.

4
docs/content/middlewares/replacepathregex.md Normal file
View file

@ -0,0 +1,4 @@
# TODO -- ReplacePathRegex
Updating the Path Before Forwarding the Request (Using a Regex)
{: .subtitle }

20
docs/content/middlewares/retry.md Normal file
View file

@ -0,0 +1,20 @@
# TODO -- Retry
Retrying until it Succeeds
{: .subtitle }
## Old Content
## Retry Configuration
```toml
# Enable retry sending request if network error
[retry]
# Number of attempts
#
# Optional
# Default: (number servers in backend) -1
#
# attempts = 3
```

13
docs/content/middlewares/stripprefix.md Normal file
View file

@ -0,0 +1,13 @@
# TODO -- StripPrefix
Removing Prefixes From the Path Before Forwarding the Request
{: .subtitle }
## OldContent
Use a `*Strip` matcher if your backend listens on the root path (`/`) but should be routeable on a specific prefix.
For instance, `PathPrefixStrip: /products` would match `/products` but also `/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 (available since Traefik 1.3) can be queried to build such URLs dynamically.

13
docs/content/middlewares/stripprefixregex.md Normal file
View file

@ -0,0 +1,13 @@
# TODO -- StripPrefix
Removing Prefixes From the Path Before Forwarding the Request (Using a Regex)
{: .subtitle }
## OldContent
Use a `*Strip` matcher if your backend listens on the root path (`/`) but should be routeable on a specific prefix.
For instance, `PathPrefixStrip: /products` would match `/products` but also `/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 (available since Traefik 1.3) can be queried to build such URLs dynamically.