File Provider

Traefik can be configured with a file.

Reference

  1. [file]
  3. # Backends
  4. [backends]
  6.   [backends.backend1]
  8.     [backends.backend1.servers]
  9.       [backends.backend1.servers.server0]
  10.         url = "http://10.10.10.1:80"
  11.         weight = 1
  12.       [backends.backend1.servers.server1]
  13.         url = "http://10.10.10.2:80"
  14.         weight = 2
  15.       # ...
  17.     [backends.backend1.circuitBreaker]
  18.       expression = "NetworkErrorRatio() > 0.5"
  20.     [backends.backend1.responseForwarding]
  21.       flushInterval = "10ms"
  23.     [backends.backend1.loadBalancer]
  24.       method = "drr"
  25.       [backends.backend1.loadBalancer.stickiness]
  26.         cookieName = "foobar"
  27.         secure = true
  28.         httpOnly = true
  29.         sameSite = "foobar"
  31.     [backends.backend1.maxConn]
  32.       amount = 10
  33.       extractorfunc = "request.host"
  35.     [backends.backend1.healthCheck]
  36.       path = "/health"
  37.       port = 88
  38.       interval = "30s"
  39.       scheme = "http"
  40.       hostname = "myhost.com"
  41.       [backends.backend1.healthcheck.headers]
  42.         My-Custom-Header = "foo"
  43.         My-Header = "bar"
  45.   [backends.backend2]
  46.     # ...
  48. # Frontends
  49. [frontends]
  51.   [frontends.frontend1]
  52.     entryPoints = ["http", "https"]
  53.     backend = "backend1"
  54.     passHostHeader = true
  55.     priority = 42
  57.     # Use frontends.frontend1.auth.basic below instead
  58.     basicAuth = [
  59.       "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
  60.       "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0",
  61.     ]
  62.     [frontends.frontend1.passTLSClientCert]
  63.         pem = true
  64.         [frontends.frontend1.passTLSClientCert.infos]
  65.             notBefore = true
  66.             notAfter = true
  67.             [frontends.frontend1.passTLSClientCert.infos.subject]
  68.                 country = true
  69.                 domainComponent = true
  70.                 province = true
  71.                 locality = true
  72.                 organization = true
  73.                 commonName = true
  74.                 serialNumber = true
  75.             [frontends.frontend1.passTLSClientCert.infos.issuer]
  76.                 country = true
  77.                 domainComponent = true
  78.                 province = true
  79.                 locality = true
  80.                 organization = true
  81.                 commonName = true
  82.                 serialNumber = true
  83.     [frontends.frontend1.auth]
  84.       headerField = "X-WebAuth-User"
  85.       [frontends.frontend1.auth.basic]
  86.         removeHeader = true
  87.         users = [
  88.           "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
  89.           "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0",
  90.         ]
  91.         usersFile = "/path/to/.htpasswd"
  92.       [frontends.frontend1.auth.digest]
  93.         removeHeader = true
  94.         users = [
  95.           "test:traefik:a2688e031edb4be6a3797f3882655c05",
  96.           "test2:traefik:518845800f9e2bfb1f1f740ec24f074e",
  97.         ]
  98.         usersFile = "/path/to/.htdigest"
  99.       [frontends.frontend1.auth.forward]
  100.         address = "https://authserver.com/auth"
  101.         trustForwardHeader = true
  102.         authResponseHeaders = ["X-Auth-User"]
  103.         [frontends.frontend1.auth.forward.tls]
  104.           ca = "path/to/local.crt"
  105.           caOptional = true
  106.           cert = "path/to/foo.cert"
  107.           key = "path/to/foo.key"
  108.           insecureSkipVerify = true
  110.     [frontends.frontend1.whiteList]
  111.       sourceRange = ["10.42.0.0/16", "152.89.1.33/32", "afed:be44::/16"]
  112.       useXForwardedFor = true
  114.     [frontends.frontend1.routes]
  115.       [frontends.frontend1.routes.route0]
  116.         rule = "Host:test.localhost"
  117.       [frontends.frontend1.routes.Route1]
  118.         rule = "Method:GET"
  119.       # ...
  121.     [frontends.frontend1.headers]
  122.       allowedHosts = ["foobar", "foobar"]
  123.       hostsProxyHeaders = ["foobar", "foobar"]
  124.       SSLRedirect = true
  125.       SSLTemporaryRedirect = true
  126.       SSLHost = "foobar"
  127.       STSSeconds = 42
  128.       STSIncludeSubdomains = true
  129.       STSPreload = true
  130.       forceSTSHeader = true
  131.       frameDeny = true
  132.       customFrameOptionsValue = "foobar"
  133.       contentTypeNosniff = true
  134.       browserXSSFilter = true
  135.       contentSecurityPolicy = "foobar"
  136.       publicKey = "foobar"
  137.       referrerPolicy = "foobar"
  138.       isDevelopment = true
  139.       [frontends.frontend1.headers.customRequestHeaders]
  140.         X-Foo-Bar-01 = "foobar"
  141.         X-Foo-Bar-02 = "foobar"
  142.         # ...
  143.       [frontends.frontend1.headers.customResponseHeaders]
  144.         X-Foo-Bar-03 = "foobar"
  145.         X-Foo-Bar-04 = "foobar"
  146.         # ...
  147.       [frontends.frontend1.headers.SSLProxyHeaders]
  148.         X-Foo-Bar-05 = "foobar"
  149.         X-Foo-Bar-06 = "foobar"
  150.         # ...
  152.     [frontends.frontend1.errors]
  153.       [frontends.frontend1.errors.errorPage0]
  154.         status = ["500-599"]
  155.         backend = "error"
  156.         query = "/{status}.html"
  157.       [frontends.frontend1.errors.errorPage1]
  158.         status = ["404", "403"]
  159.         backend = "error"
  160.         query = "/{status}.html"
  161.       # ...
  163.     [frontends.frontend1.ratelimit]
  164.       extractorfunc = "client.ip"
  165.         [frontends.frontend1.ratelimit.rateset.rateset1]
  166.           period = "10s"
  167.           average = 100
  168.           burst = 200
  169.         [frontends.frontend1.ratelimit.rateset.rateset2]
  170.           period = "3s"
  171.           average = 5
  172.           burst = 10
  173.         # ...
  175.     [frontends.frontend1.redirect]
  176.       entryPoint = "https"
  177.       regex = "^http://localhost/(.*)"
  178.       replacement = "http://mydomain/$1"
  179.       permanent = true
  181.   [frontends.frontend2]
  182.     # ...
  184. # HTTPS certificates
  185. [[tls]]
  186.   entryPoints = ["https"]
  187.   [tls.certificate]
  188.     certFile = "path/to/my.cert"
  189.     keyFile = "path/to/my.key"
  191. [[tls]]
  192.   # ...

Configuration Mode

You have two choices:

To enable the file backend, you must either pass the --file option to the Traefik binary or put the [file] section (with or without inner settings) in the configuration file.

The configuration file allows managing both backends/frontends and HTTPS certificates (which are not Let's Encrypt certificates generated through Traefik).

TOML templating can be used if rules are not defined in the Traefik configuration file.

Rules in Traefik Configuration File

Add your configuration at the end of the global configuration file traefik.toml:

  1. defaultEntryPoints = ["http", "https"]
  3. [entryPoints]
  4.   [entryPoints.http]
  5.     # ...
  6.   [entryPoints.https]
  7.     # ...
  9. [file]
  11. # rules
  12. [backends]
  13.   [backends.backend1]
  14.     # ...
  15.   [backends.backend2]
  16.     # ...
  18. [frontends]
  19.   [frontends.frontend1]
  20.   # ...
  21.   [frontends.frontend2]
  22.   # ...
  23.   [frontends.frontend3]
  24.   # ...
  26. # HTTPS certificate
  27. [[tls]]
  28.   # ...
  30. [[tls]]
  31.   # ...

Note

If tls.entryPoints is not defined, the certificate is attached to all the defaultEntryPoints with a TLS configuration.

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.

Warning

TOML templating cannot be used if rules are defined in the Traefik configuration file.

Rules in Dedicated Files

Traefik allows defining rules in one or more separate files.

One Separate File

You have to specify the file path in the file.filename option.

  1. # traefik.toml
  2. defaultEntryPoints = ["http", "https"]
  4. [entryPoints]
  5.   [entryPoints.http]
  6.     # ...
  7.   [entryPoints.https]
  8.     # ...
  10. [file]
  11.   filename = "rules.toml"
  12.   watch = true

The option file.watch allows Traefik to watch file changes automatically.

Multiple Separated Files

You could have multiple .toml files in a directory (and recursively in its sub-directories):

  1. [file]
  2.   directory = "/path/to/config/"
  3.   watch = true

The option file.watch allows Traefik to watch file changes automatically.

Separate Files Content

If you are defining rules in one or more separate files, you can use two formats.

Simple Format

Backends, Frontends and TLS certificates are defined one at time, as described in the file rules.toml:

  1. # rules.toml
  2. [backends]
  3.   [backends.backend1]
  4.     # ...
  5.   [backends.backend2]
  6.     # ...
  8. [frontends]
  9.   [frontends.frontend1]
  10.   # ...
  11.   [frontends.frontend2]
  12.   # ...
  13.   [frontends.frontend3]
  14.   # ...
  16. # HTTPS certificate
  17. [[tls]]
  18.   # ...
  20. [[tls]]
  21.   # ...
TOML Templating

Warning

TOML templating can only be used if rules are defined in one or more separate files. Templating will not work in the Traefik configuration file.

Traefik allows using TOML templating.

Thus, it's possible to define easily lot of Backends, Frontends and TLS certificates as described in the file template-rules.toml :

  1. # template-rules.toml
  2. [backends]
  3. {{ range $i, $e := until 100 }}
  4.   [backends.backend{{ $e }}]
  5.     #...
  6. {{ end }}
  8. [frontends]
  9. {{ range $i, $e := until 100 }}
  10.   [frontends.frontend{{ $e }}]
  11.     #...
  12. {{ end }}
  15. # HTTPS certificate
  16. {{ range $i, $e := until 100 }}
  17. [[tls]]
  18.     #...
  19. {{ end }}