Enhance file provider documentation.

docs/basics.md

@@ -612,6 +612,7 @@ Those data help us prioritize our developments and focus on what's more importan
 ### What ?
 
 Once a day (the first call begins 10 minutes after the start of Træfik), we collect:
+
 - the Træfik version
 - a hash of the configuration
 - an **anonymous version** of the static configuration:

docs/configuration/acme.md

@@ -142,7 +142,6 @@ entryPoint = "https"
 !!! note
     If `TLS-SNI-01` challenge is used, `acme.entryPoint` has to be reachable by Let's Encrypt through the port 443.
     If `HTTP-01` challenge is used, `acme.httpChallenge.entryPoint` has to be defined and reachable by Let's Encrypt through the port 80.
-    The redirection is fully compatible with the HTTP-01 challenge. You can use redirection with HTTP-01 challenge without problem.
     These are Let's Encrypt limitations as described on the [community forum](https://community.letsencrypt.org/t/support-for-ports-other-than-80-and-443/3419/72).
 
 ### `storage`
@@ -187,6 +186,9 @@ docker run -v "/my/host/acme:/etc/traefik/acme" traefik
 
 Use `HTTP-01` challenge to generate/renew ACME certificates.
 
+The redirection is fully compatible with the HTTP-01 challenge.
+You can use redirection with HTTP-01 challenge without problem.
+
 ```toml
 [acme]
 # ...

docs/configuration/backends/file.md

@@ -1,6 +1,140 @@
 # File Backends
 
-Like any other reverse proxy, Træfik can be configured with a file.
+Træfik can be configured with a file.
+
+## Reference
+
+```toml
+# Backends
+[backends]
+
+  [backends.backend1]
+
+    [backends.backend1.servers]
+      [backends.backend1.servers.server0]
+        url = "http://10.10.10.1:80"
+        weight = 1
+      [backends.backend1.servers.server1]
+        url = "http://10.10.10.2:80"
+        weight = 2
+      # ...
+
+    [backends.backend1.circuitBreaker]
+      expression = "NetworkErrorRatio() > 0.5"
+
+    [backends.backend1.loadBalancer]
+      method = "drr"
+      [backends.backend1.loadBalancer.stickiness]
+        cookieName = "foobar"
+
+    [backends.backend1.maxConn]
+      amount = 10
+      extractorfunc = "request.host"
+
+    [backends.backend1.healthCheck]
+      path = "/health"
+      port = 88
+      interval = "30s"
+
+  [backends.backend2]
+    # ...
+
+# Frontends
+[frontends]
+
+  [frontends.frontend1]
+    entryPoints = ["http", "https"]
+    backend = "backend1"
+    passHostHeader = true
+    passTLSCert = true
+    priority = 42
+    basicAuth = [
+      "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
+      "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0",
+    ]
+    whitelistSourceRange = ["10.42.0.0/16", "152.89.1.33/32", "afed:be44::/16"]
+
+    [frontends.frontend1.routes]
+      [frontends.frontend1.routes.route0]
+        rule = "Host:test.localhost"
+      [frontends.frontend1.routes.Route1]
+        rule = "Method:GET"
+      # ...
+
+    [frontends.frontend1.headers]
+      allowedHosts = ["foobar", "foobar"]
+      hostsProxyHeaders = ["foobar", "foobar"]
+      SSLRedirect = true
+      SSLTemporaryRedirect = true
+      SSLHost = "foobar"
+      STSSeconds = 42
+      STSIncludeSubdomains = true
+      STSPreload = true
+      forceSTSHeader = true
+      frameDeny = true
+      customFrameOptionsValue = "foobar"
+      contentTypeNosniff = true
+      browserXSSFilter = true
+      contentSecurityPolicy = "foobar"
+      publicKey = "foobar"
+      referrerPolicy = "foobar"
+      isDevelopment = true
+      [frontends.frontend1.headers.customRequestHeaders]
+        X-Foo-Bar-01 = "foobar"
+        X-Foo-Bar-02 = "foobar"
+        # ...
+      [frontends.frontend1.headers.customResponseHeaders]
+        X-Foo-Bar-03 = "foobar"
+        X-Foo-Bar-04 = "foobar"
+        # ...
+      [frontends.frontend1.headers.SSLProxyHeaders]
+        X-Foo-Bar-05 = "foobar"
+        X-Foo-Bar-06 = "foobar"
+        # ...
+
+    [frontends.frontend1.errors]
+      [frontends.frontend1.errors.errorPage0]
+        status = ["500-599"]
+        backend = "error"
+        query = "/{status}.html"
+      [frontends.frontend1.errors.errorPage1]
+        status = ["404", "403"]
+        backend = "error"
+        query = "/{status}.html"
+      # ...
+
+    [frontends.frontend1.ratelimit]
+      extractorfunc = "client.ip"
+        [frontends.frontend1.ratelimit.rateset.rateset1]
+          period = "10s"
+          average = 100
+          burst = 200
+        [frontends.frontend1.ratelimit.rateset.rateset2]
+          period = "3s"
+          average = 5
+          burst = 10
+        # ...
+
+    [frontends.frontend1.redirect]
+      entryPoint = "https"
+      regex = "^http://localhost/(.*)"
+      replacement = "http://mydomain/$1"
+
+  [frontends.frontend2]
+    # ...
+
+# HTTPS certificates
+[[tls]]
+  entryPoints = ["https"]
+  [tls.certificate]
+    certFile = "path/to/my.cert"
+    keyFile = "path/to/my.key"
+
+[[tls]]
+  # ...
+```
+
+## Configuration mode
 
 You have three choices:
 
@@ -12,7 +146,7 @@ To enable the file backend, you must either pass the `--file` option to the Træ
 
 The configuration file allows managing both backends/frontends and HTTPS certificates (which are not [Let's Encrypt](https://letsencrypt.org) certificates generated through Træfik).
 
-## Simple
+### Simple
 
 Add your configuration at the end of the global configuration file `traefik.toml`:
 
@@ -21,172 +155,93 @@ defaultEntryPoints = ["http", "https"]
 
 [entryPoints]
   [entryPoints.http]
-  address = ":80"
+    # ...
-    [entryPoints.http.redirect]
-    entryPoint = "https"
   [entryPoints.https]
-  address = ":443"
+    # ...
-    [entryPoints.https.tls]
-      [[entryPoints.https.tls.certificates]]
-      certFile = "integration/fixtures/https/snitest.org.cert"
-      keyFile = "integration/fixtures/https/snitest.org.key"
 
 [file]
 
 # rules
 [backends]
   [backends.backend1]
-    [backends.backend1.circuitbreaker]
+    # ...
-    expression = "NetworkErrorRatio() > 0.5"
-    [backends.backend1.servers.server1]
-    url = "http://172.17.0.2:80"
-    weight = 10
-    [backends.backend1.servers.server2]
-    url = "http://172.17.0.3:80"
-    weight = 1
   [backends.backend2]
-    [backends.backend2.maxconn]
+    # ...
-    amount = 10
-    extractorfunc = "request.host"
-    [backends.backend2.LoadBalancer]
-    method = "drr"
-    [backends.backend2.servers.server1]
-    url = "http://172.17.0.4:80"
-    weight = 1
-    [backends.backend2.servers.server2]
-    url = "http://172.17.0.5:80"
-    weight = 2
 
 [frontends]
   [frontends.frontend1]
-  backend = "backend2"
+  # ...
-    [frontends.frontend1.routes.test_1]
-    rule = "Host:test.localhost"
-
   [frontends.frontend2]
-  backend = "backend1"
+  # ...
-  passHostHeader = true
-  priority = 10
-
-  # restrict access to this frontend to the specified list of IPv4/IPv6 CIDR Nets
-  # an unset or empty list allows all Source-IPs to access
-  # if one of the Net-Specifications are invalid, the whole list is invalid
-  # and allows all Source-IPs to access.
-  whitelistSourceRange = ["10.42.0.0/16", "152.89.1.33/32", "afed:be44::/16"]
-
-  entrypoints = ["https"] # overrides defaultEntryPoints
-    [frontends.frontend2.routes.test_1]
-    rule = "Host:{subdomain:[a-z]+}.localhost"
-
   [frontends.frontend3]
-  entrypoints = ["http", "https"] # overrides defaultEntryPoints
+  # ...
-  backend = "backend2"
-  rule = "Path:/test"
 
 # HTTPS certificate
 [[tls]]
-  entryPoints = ["https"]
+  # ...
-  [tls.certificate]
+
-    certFile = "path/to/my.cert"
-    keyFile = "path/to/my.key"
-    
 [[tls]]
-  entryPoints = ["https"]
+  # ...
-  [tls.certificate]
-    certFile = "path/to/my/other.cert"
-    keyFile = "path/to/my/other.key"
 ```
 
 !!! note
     adding certificates directly to the entrypoint is still maintained but certificates declared in this way cannot be managed dynamically.
     It's recommended to use the file provider to declare certificates.
 
-## Rules in a Separate File
+### Rules in a Separate File
 
 Put your rules in a separate file, for example `rules.toml`:
 
 ```toml
 # traefik.toml
+defaultEntryPoints = ["http", "https"]
+
 [entryPoints]
   [entryPoints.http]
-  address = ":80"
+    # ...
-    [entryPoints.http.redirect]
-      entryPoint = "https"
   [entryPoints.https]
-  address = ":443"
+    # ...
-    [entryPoints.https.tls]
 
 [file]
-filename = "rules.toml"
+  filename = "rules.toml"
 ```
 
 ```toml
 # rules.toml
 [backends]
   [backends.backend1]
-    [backends.backend1.circuitbreaker]
+    # ...
-    expression = "NetworkErrorRatio() > 0.5"
-    [backends.backend1.servers.server1]
-    url = "http://172.17.0.2:80"
-    weight = 10
-    [backends.backend1.servers.server2]
-    url = "http://172.17.0.3:80"
-    weight = 1
   [backends.backend2]
-    [backends.backend2.maxconn]
+    # ...
-    amount = 10
-    extractorfunc = "request.host"
-    [backends.backend2.LoadBalancer]
-    method = "drr"
-    [backends.backend2.servers.server1]
-    url = "http://172.17.0.4:80"
-    weight = 1
-    [backends.backend2.servers.server2]
-    url = "http://172.17.0.5:80"
-    weight = 2
 
 [frontends]
   [frontends.frontend1]
-  backend = "backend2"
+  # ...
-    [frontends.frontend1.routes.test_1]
-    rule = "Host:test.localhost"
   [frontends.frontend2]
-  backend = "backend1"
+  # ...
-  passHostHeader = true
-  priority = 10
-  entrypoints = ["https"] # overrides defaultEntryPoints
-    [frontends.frontend2.routes.test_1]
-    rule = "Host:{subdomain:[a-z]+}.localhost"
   [frontends.frontend3]
-  entrypoints = ["http", "https"] # overrides defaultEntryPoints
+  # ...
-  backend = "backend2"
+
-  rule = "Path:/test"
-  
 # HTTPS certificate
 [[tls]]
-  entryPoints = ["https"]
+  # ...
-  [tls.certificate]
-    certFile = "path/to/my.cert"
-    keyFile = "path/to/my.key"
-    
-[[tls]]
-  entryPoints = ["https"]
-  [tls.certificate]
-    certFile = "path/to/my/other.cert"
-    keyFile = "path/to/my/other.key"
 
-## Multiple `.toml` Files
+[[tls]]
+  # ...
+```
+
+### Multiple `.toml` Files
 
 You could have multiple `.toml` files in a directory (and recursively in its sub-directories):
 
 ```toml
 [file]
-directory = "/path/to/config/"
+  directory = "/path/to/config/"
 ```
 
 If you want Træfik to watch file changes automatically, just add:
 
 ```toml
 [file]
-watch = true
+  watch = true
 ```

docs/configuration/commons.md

@@ -285,21 +285,17 @@ Multiple sets of rates can be added to each frontend, but the time periods must
 ```toml
 [frontends]
     [frontends.frontend1]
-    passHostHeader = true
+      # ...
-    entrypoints = ["http"]
+      [frontends.frontend1.ratelimit]
-    backend = "backend1"
+        extractorfunc = "client.ip"
-        [frontends.frontend1.routes.test_1]
+          [frontends.frontend1.ratelimit.rateset.rateset1]
-        rule = "Path:/"
+            period = "10s"
-    [frontends.frontend1.ratelimit]
+            average = 100
-    extractorfunc = "client.ip"
+            burst = 200
-        [frontends.frontend1.ratelimit.rateset.rateset1]
+          [frontends.frontend1.ratelimit.rateset.rateset2]
-        period = "10s"
+            period = "3s"
-        average = 100
+            average = 5
-        burst = 200
+            burst = 10
-        [frontends.frontend1.ratelimit.rateset.rateset2]
-        period = "3s"
-        average = 5
-        burst = 10
 ```
 
 In the above example, frontend1 is configured to limit requests by the client's ip address.  

docs/configuration/entrypoints.md

@@ -1,5 +1,72 @@
 # Entry Points Definition
 
+## Reference
+
+```toml
+[entryPoints]
+  [entryPoints.http]
+    address = ":80"
+    whitelistSourceRange = ["10.42.0.0/16", "152.89.1.33/32", "afed:be44::/16"]
+    compress = true
+
+    [entryPoints.http.tls]
+      minVersion = "VersionTLS12"
+      cipherSuites = ["TLS_RSA_WITH_AES_256_GCM_SHA384"]
+      [[entryPoints.http.tls.certificates]]
+        certFile = "path/to/my.cert"
+        keyFile = "path/to/my.key"
+      [[entryPoints.http.tls.certificates]]
+        certFile = "path/to/other.cert"
+        keyFile = "path/to/other.key"
+      # ...
+      [entryPoints.http.tls.clientCA]
+        files = ["path/to/ca1.crt", "path/to/ca2.crt"]
+        optional = false
+
+    [entryPoints.http.redirect]
+      entryPoint = "https"
+      regex = "^http://localhost/(.*)"
+      replacement = "http://mydomain/$1"
+      permanent = true
+
+    [entryPoints.http.auth]
+      headerField = "X-WebAuth-User"
+      [entryPoints.http.auth.basic]
+        users = [
+          "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
+          "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0",
+        ]
+        usersFile = "/path/to/.htpasswd"
+      [entryPoints.http.auth.digest]
+        users = [
+          "test:traefik:a2688e031edb4be6a3797f3882655c05",
+          "test2:traefik:518845800f9e2bfb1f1f740ec24f074e",
+        ]
+        usersFile = "/path/to/.htdigest"
+      [entryPoints.http.auth.forward]
+        address = "https://authserver.com/auth"
+        trustForwardHeader = true
+        [entryPoints.http.auth.forward.tls]
+          ca =  [ "path/to/local.crt"]
+          caOptional = true
+          cert = "path/to/foo.cert"
+          key = "path/to/foo.key"
+          insecureSkipVerify = true
+
+    [entryPoints.http.proxyProtocol]
+      insecure = true
+      trustedIPs = ["10.10.10.1", "10.10.10.2"]
+
+    [entryPoints.http.forwardedHeaders]
+      trustedIPs = ["10.10.10.1", "10.10.10.2"]
+
+  [entryPoints.https]
+    # ...
+```
+
+
+## Basic
+
 ```toml
 # Entrypoints definition
 #
@@ -71,7 +138,7 @@ Define an entrypoint with SNI support.
 
 !!! note
     If an empty TLS configuration is done, default self-signed certificates are generated.
-    
+
 
 ### Dynamic Certificates
 
@@ -162,7 +229,7 @@ Otherwise, the response from the auth server is returned.
     # To enable forward auth on an entrypoint
     [entryPoints.http.auth.forward]
     address = "https://authserver.com/auth"
-    
+
     # Trust existing X-Forwarded-* headers.
     # Useful with another reverse proxy in front of Traefik.
     #
@@ -170,7 +237,7 @@ Otherwise, the response from the auth server is returned.
     # Default: false
     #
     trustForwardHeader = true
-    
+
     # Enable forward auth TLS connection.
     #
     # Optional
@@ -234,7 +301,7 @@ Only IPs in `trustedIPs` will lead to remote client address replacement: you sho
 
 !!! danger
     When queuing Træfik behind another load-balancer, be sure to carefully configure Proxy Protocol on both sides.
-    Otherwise, it could introduce a security risk in your system by forging requests. 
+    Otherwise, it could introduce a security risk in your system by forging requests.
 
 ```toml
 [entryPoints]