From e2ec64947a49693a48f81ad638d4b13d1d96fb1f Mon Sep 17 00:00:00 2001
From: Jean-Baptiste Doumenjou <jb.doumenjou@gmail.com>
Date: Thu, 14 Mar 2019 16:46:05 +0100
Subject: [PATCH] Update the file provider documentation

---
 docs/content/providers/file.md           | 148 +++++++++++--
 docs/content/reference/providers/file.md | 261 +++++++++++++++++++++++
 docs/mkdocs.yml                          |   1 +
 3 files changed, 397 insertions(+), 13 deletions(-)
 create mode 100644 docs/content/reference/providers/file.md

diff --git a/docs/content/providers/file.md b/docs/content/providers/file.md
index 0b36f2cba..eed2c6b7d 100644
--- a/docs/content/providers/file.md
+++ b/docs/content/providers/file.md
@@ -1,27 +1,149 @@
-# TODO -- File
+# Traefik & File
 
 Good Old Configuration File
 {: .subtitle } 
 
-## Configuration
+The file provider lets you define the [dynamic configuration](./overview.md) in a `toml` file.
+You can write these configuration elements:
 
-### Full Example in toml
+* At the end of the main Traefik configuration file (by default: `traefik.toml`).
+* In [a dedicated file](#filename-optional)
+* In [several dedicated files](#directory-optional)
 
-`TO COMPLETE`
+!!! note
+    The file provider is the default format used throughout the documentation to show samples of the configuration for many features. 
 
-### In same file
+!!! tip
+    The file provider can be a good location for common elements you'd like to re-use from other providers; e.g. declaring whitelist middlewares, basic authentication, ...
 
-`TO COMPLETE`
+## Configuration Examples
 
-## In dedicated file
+??? example "Declaring Routers, Middlewares & Services"
 
-`TO COMPLETE`
+    ``` toml
+    # Enabling the file provider
+    [providers.files]
+    
+    [http]
+      # Add the router
+      [http.routers]
+        [http.routers.router0]
+          entrypoints = ["web"]
+          middlewares = ["my-basic-auth"]
+          service = "service-foo"
+          rule = "Path(`foo`)"
+    
+        # Add the middleware
+        [http.middlewares]    
+          [http.middlewares.my-basic-auth.BasicAuth]
+            users = ["test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/", 
+                      "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"]
+            usersFile = "etc/traefik/.htpasswd"
+        
+        # Add the service
+        [http.services]
+          [http.services.service-foo]
+            [http.services.service-foo.LoadBalancer]
+              method = "wrr"
+              [[http.services.service-foo.LoadBalancer.Servers]]
+                url = "http://foo/"
+                weight = 30
+              [[http.services.service-foo.LoadBalancer.Servers]]
+                url = "http://bar/"
+                weight = 70
+    ```
 
-### Old Content
+## Provider Configuration Options
 
-Traefik can hot-reload those rules which could be provided by multiple configuration backends.
+!!! tip "Browse the Reference"
+    If you're in a hurry, maybe you'd rather go through the [File Reference](../reference/providers/file.md).
 
-We only need to enable `watch` option to make Traefik watch configuration backend changes and generate its configuration automatically.
-Routes to services will be created and updated instantly at any changes.
+### filename (_Optional_)
 
-Please refer to the configuration backends section to get documentation on it.
+Defines the path of the configuration file.
+
+```toml
+[providers]
+  [providers.file]
+    filename = "rules.toml"
+```
+
+### directory (_Optional_)
+
+Defines the directory that contains the configuration files.
+
+```toml
+[providers]
+  [providers.file]
+    directory = "/path/to/config"
+```
+
+### watch (_Optional_)
+
+Set the `watch` option to `true` to allow Traefik to automatically watch for file changes.  
+It works with both the `filename` and the `directory` options.
+
+```toml
+[providers]
+  [providers.file]
+    filename = "rules.toml"
+    watch = true
+```
+
+### TOML Templating
+
+!!! warning
+    TOML templating only works along with dedicated configuration files. Templating does not work in the Traefik main configuration file.
+
+Traefik allows using TOML templating.  
+Thus, it's possible to define easily lot of routers, services and TLS certificates as described in the file `template-rules.toml` :
+
+??? example "Configuring Using Templating"
+
+    ```toml
+    # template-rules.toml
+    [http]
+    
+      [http.routers]
+      {{ range $i, $e := until 100 }}
+        [http.routers.router{{ $e }}]
+        # ...
+      {{ end }}  
+      
+      
+      [http.Services]
+      {{ range $i, $e := until 100 }}
+          [http.services.service{{ $e }}]
+          # ...
+      {{ end }}  
+      
+    [tcp]
+    
+      [tcp.routers]
+      {{ range $i, $e := until 100 }}
+        [tcp.routers.router{{ $e }}]
+        # ...
+      {{ end }}  
+      
+      
+      [tcp.Services]
+      {{ range $i, $e := until 100 }}
+          [http.services.service{{ $e }}]
+          # ...
+      {{ end }}  
+    
+    {{ range $i, $e := until 10 }}
+    [[TLS]]
+      Store = ["my-store-foo-{{ $e }}", "my-store-bar-{{ $e }}"]
+      [TLS.Certificate]
+        CertFile = "/etc/traefik/cert-{{ $e }}.pem"
+        KeyFile = "/etc/traefik/cert-{{ $e }}.key"
+    {{ end }}
+    
+    [TLSConfig]
+    {{ range $i, $e := until 10 }}
+      [TLSConfig.TLS{{ $e }}]
+      # ...
+    {{ end }}
+    
+    ```
diff --git a/docs/content/reference/providers/file.md b/docs/content/reference/providers/file.md
new file mode 100644
index 000000000..7c35e2754
--- /dev/null
+++ b/docs/content/reference/providers/file.md
@@ -0,0 +1,261 @@
+# File -- Reference
+
+## File
+
+```toml
+################################################################
+# File Provider
+################################################################
+
+[providers]
+
+  # Enable File Provider.
+  [providers.file]
+  
+    # Define one separated configuration file.
+    #
+    # Optional
+    #     
+    filename = "my-conf.toml"
+
+    # Define directory that contains a set of configuration files.
+    #
+    # Optional
+    #     
+    directory = "/path/to/config"
+
+    # Enable watch file changes.
+    #
+    # Optional
+    #
+    watch = true
+
+    [http]
+    
+      [http.routers]
+      
+        [http.routers.router0]
+          entrypoints = ["foo", "bar"]
+          middlewares = ["foo", "bar"]
+          service = "service-foo"
+          rule = "Path(`foo`)"
+          priority = 42
+          [http.routers.router0.tls]
+      
+      [http.middlewares]
+      
+          [http.middlewares.my-add-prefix.AddPrefix]
+            prefix = "/foo"
+      
+          [http.middlewares.my-strip-prefix.StripPrefix]
+            prefixes = ["/foo", "/bar"]
+      
+          [http.middlewares.my-strip-prefix-regex.StripPrefixRegex]
+            regex = ["/foo/api/", "/bar/{category}/{id:[0-9]+}/"]
+      
+          [http.middlewares.my-replace-path.ReplacePath]
+            path = "/foo"
+      
+          [http.middlewares.my-replace-path-regex.ReplacePathRegex]
+            regex = "foo/(.*)"
+            replacement = "/foobar/$1"
+      
+          [http.middlewares.my-chain.Chain]
+            middlewares = ["my-add-prefix", "my-basic-auth"]
+      
+          [http.middlewares.Middleware0.IPWhiteList]
+            sourceRange = ["127.0.0.1/32", "192.168.1.7"]
+            [http.middlewares.Middleware0.IPWhiteList.IPStrategy]
+              depth = 2
+              excludedIPs = ["127.0.0.1/16", "192.168.1.7"]
+      
+          [http.middlewares.my-headers.Headers]
+            allowedHosts = ["foobar", "foobar"]
+            hostsProxyHeaders = ["foobar", "foobar"]
+            sslRedirect = true
+            sslTemporaryRedirect = true
+            sslHost = "foobar"
+            sslForceHost = true
+            stsSeconds = 42
+            stsIncludeSubdomains = true
+            stsPreload = true
+            forceSTSHeader = true
+            frameDeny = true
+            customFrameOptionsValue = "foobar"
+            contentTypeNosniff = true
+            browserXSSFilter = true
+            customBrowserXSSValue = "foobar"
+            contentSecurityPolicy = "foobar"
+            publicKey = "foobar"
+            referrerPolicy = "foobar"
+            isDevelopment = true
+            [http.middlewares.my-headers.Headers.CustomRequestHeaders]
+              X-Script-Name = "foo"
+            [http.middlewares.my-headers.Headers.CustomResponseHeaders]
+              X-Custom-Response-Header = "True"
+            [http.middlewares.my-headers.Headers.SSLProxyHeaders]
+              X-Forwarded-Proto = "https"
+          
+          [http.middlewares.my-errors.Errors]
+            status = ["400-404", "500-599"]
+            service = "foo-errors-service"
+            query = "/error.html"
+          
+          [http.middlewares.my-rate-limit.RateLimit]
+            extractorFunc = "client.ip"
+            [http.middlewares.Middleware0.RateLimit.RateSet]
+            
+              [http.middlewares.Middleware0.RateLimit.RateSet.Rate0]
+                period = 10
+                average = 100
+                burst = 200
+          
+          [http.middlewares.my-redirect-regex.RedirectRegex]
+            regex = "^http://localhost/(.*)"
+            replacement = "http://mydomain/$1"
+            permanent = true
+          
+          [http.middlewares.my-redirect-scheme.RedirectScheme]
+            scheme = "https"
+            port = "8443"
+            permanent = true
+          
+          [http.middlewares.my-basic-auth.BasicAuth]
+            users = ["test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/", 
+                      "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"]
+            usersFile = "etc/traefik/.htpasswd"
+            realm = "myRealm"
+            removeHeader = true
+            headerField = "X-WebAuth-User"
+          
+          [http.middlewares.my-digest-auth.DigestAuth]
+            users = ["test:traefik:a2688e031edb4be6a3797f3882655c05", "test2:traefik:518845800f9e2bfb1f1f740ec24f074e"]
+            usersFile = "etc/traefik/.htdigest"
+            removeHeader = true
+            realm = "traefik"
+            headerField = "X-WebAuth-User"
+          
+          [http.middlewares.my-forward-auth.ForwardAuth]
+            address = "https://myauth.server:443"
+            trustForwardHeader = true
+            authResponseHeaders = ["X-Forwarded-Foo", "X-Forwarded-Bar"]
+            [http.middlewares.my-forward-auth.ForwardAuth.TLS]
+              ca = "/etc/traefik/crt/ca.pem"
+              caOptional = true
+              cert = "/etc/traefik/crt/cert.pem"
+              key = "/etc/traefik/crt/cert.key"
+              insecureSkipVerify = true
+          
+          [http.middlewares.my-maxconn.MaxConn]
+            amount = 10
+            extractorFunc = "request.host"
+          
+          [http.middlewares.my-buffering.Buffering]
+            maxRequestBodyBytes = 25000
+            memRequestBodyBytes = 25000
+            maxResponseBodyBytes = 25000
+            memResponseBodyBytes = 25000
+            retryExpression = "foobar"
+          
+          [http.middlewares.my-circuit-breaker.CircuitBreaker]
+            Expression = "LatencyAtQuantileMS(50.0) > 100"
+          
+          [http.middlewares.my-compress.Compress]
+          
+          [http.middlewares.my-pass-tls-client-cert.PassTLSClientCert]
+            pem = true
+            [http.middlewares.Middleware0.PassTLSClientCert.Info]
+              notAfter = true
+              notBefore = true
+              sans = true
+              [http.middlewares.Middleware0.PassTLSClientCert.Info.Subject]
+                country = true
+                province = true
+                locality = true
+                organization = true
+                commonName = true
+                serialNumber = true
+                domainComponent = true
+              [http.middlewares.Middleware0.PassTLSClientCert.Info.Issuer]
+                country = true
+                province = true
+                locality = true
+                organization = true
+                commonName = true
+                serialNumber = true
+                domainComponent = true
+          
+          [http.middlewares.my-retry.Retry]
+            attempts = 4
+    
+      [http.services]
+      
+        [http.services.service0]
+          [http.services.service0.LoadBalancer]
+            method = "wrr"
+            passHostHeader = true
+            [http.services.service0.LoadBalancer.Stickiness]
+              cookieName = "my-stickiness-cookie-name"
+            [[http.services.service0.LoadBalancer.Servers]]
+              url = "http://foo/"
+              weight = 30
+            [[http.services.service0.LoadBalancer.Servers]]
+              url = "http://bar/"
+              weight = 70
+            [http.services.service0.LoadBalancer.HealthCheck]
+              scheme = "https"
+              path = "/health"
+              port = 9443
+              interval = "10s"
+              timeout = "30s"
+              hostname = "foobar"
+              [http.services.service0.LoadBalancer.HealthCheck.Headers]
+                My-Custom-Header = "foobar"
+            [http.services.service0.LoadBalancer.ResponseForwarding]
+              flushInterval = "4s"
+      
+    [tcp]
+    
+      [tcp.routers]
+        [tcp.routers.tcpRouter0]
+          entryPoints = ["foobar", "foobar"]
+          service = "foobar"
+          rule = "foobar"
+          [tcp.routers.tcpRouter0.tlst]
+            passthrough = true
+    
+      [tcp.services]
+        [tcp.services.tcpService0]
+          [tcp.services.tcpService0.tcpLoadBalancer]
+            method = "foobar"
+            [[tcp.services.tcpService0.tcpLoadBalancer.Servers]]
+              address = "foobar"
+              weight = 42
+            [[tcp.services.tcpService0.tcpLoadBalancer.Servers]]
+              address = "foobar"
+              weight = 42
+    
+    [[tls]]
+      Store = ["my-store-foo", "my-store-bar"]
+      [tls.Certificate]
+        certFile = "/etc/traefik/cert.pem"
+        keyFile = "/etc/traefik/cert.key"
+    
+    
+    [tlsconfig]
+      [tlsconfig.TLS0]
+        minVersion = "VersionTLS12"
+        cipherSuites = [ "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", "TLS_RSA_WITH_AES_256_GCM_SHA384"]
+        [tlsconfig.TLS0.ClientCA]
+          files = ["/etc/traefik/ca-foo.pem", "/etc/traefik/ca-bar.pem"]
+          optional = true
+    
+    [tlsstore]
+      [tlsstore.my-store-foo]
+        sniStrict = true
+        [tlsstore.my-store-foo.DefaultCertificate]
+          certFile = "/etc/traefik/cert.pem"
+          keyFile = "/etc/traefik/cert.key"
+
+```
+
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index caea6dfc6..dc7562a01 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -66,6 +66,7 @@ markdown_extensions:
 nav:
   - '': 'reference/acme.md'
   - '': 'reference/providers/docker.md'
+  - '': 'reference/providers/file.md'
   - '': 'reference/entrypoints.md'
   - 'Welcome': 'index.md'
   - 'Getting Started':