Entry Points Definition¶

Reference¶

TOML¶

[entryPoints]
  [entryPoints.http]
    address = ":80"
    compress = true

    [entryPoints.http.whitelist]
      sourceRange = ["10.42.0.0/16", "152.89.1.33/32", "afed:be44::/16"]
      useXForwardedFor = true

    [entryPoints.http.tls]
      minVersion = "VersionTLS12"
      cipherSuites = [
        "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
        "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]
    # ...

CLI¶

For more information about the CLI, see the documentation about Traefik command.

--entryPoints='Name:http Address::80'
--entryPoints='Name:https Address::443 TLS'

Note

Whitespace is used as option separator and , is used as value separator for the list.
The names of the options are case-insensitive.

In compose file the entrypoint syntax is different:

traefik:
    image: traefik
    command:
        - --defaultentrypoints=powpow
        - "--entryPoints=Name:powpow Address::42 Compress:true"

or

traefik:
    image: traefik
    command: --defaultentrypoints=powpow --entryPoints='Name:powpow Address::42 Compress:true'

All available options:¶

Name:foo
Address::80
TLS:/my/path/foo.cert,/my/path/foo.key;/my/path/goo.cert,/my/path/goo.key;/my/path/hoo.cert,/my/path/hoo.key
TLS
CA:car
CA.Optional:true
Redirect.EntryPoint:https
Redirect.Regex:http://localhost/(.*)
Redirect.Replacement:http://mydomain/$1
Redirect.Permanent:true
Compress:true
WhiteList.SourceRange:10.42.0.0/16,152.89.1.33/32,afed:be44::/16
WhiteList.UseXForwardedFor:true
ProxyProtocol.TrustedIPs:192.168.0.1
ProxyProtocol.Insecure:true
ForwardedHeaders.TrustedIPs:10.0.0.3/24,20.0.0.3/24
Auth.Basic.Users:test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/,test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0
Auth.Digest.Users:test:traefik:a2688e031edb4be6a3797f3882655c05,test2:traefik:518845800f9e2bfb1f1f740ec24f074e
Auth.HeaderField:X-WebAuth-User
Auth.Forward.Address:https://authserver.com/auth
Auth.Forward.TrustForwardHeader:true
Auth.Forward.TLS.CA:path/to/local.crt
Auth.Forward.TLS.CAOptional:true
Auth.Forward.TLS.Cert:path/to/foo.cert
Auth.Forward.TLS.Key:path/to/foo.key
Auth.Forward.TLS.InsecureSkipVerify:true

Basic¶

# Entrypoints definition
#
# Default:
# [entryPoints]
#   [entryPoints.http]
#   address = ":80"
#
[entryPoints]
  [entryPoints.http]
  address = ":80"

Redirect HTTP to HTTPS¶

To redirect an http entrypoint to an https entrypoint (with SNI support).

[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.com.cert"
      keyFile = "integration/fixtures/https/snitest.com.key"
      [[entryPoints.https.tls.certificates]]
      certFile = "integration/fixtures/https/snitest.org.cert"
      keyFile = "integration/fixtures/https/snitest.org.key"

Note

Please note that regex and replacement do not have to be set in the redirect structure if an entrypoint is defined for the redirection (they will not be used in this case).

Rewriting URL¶

To redirect an entrypoint rewriting the URL.

[entryPoints]
  [entryPoints.http]
  address = ":80"
    [entryPoints.http.redirect]
    regex = "^http://localhost/(.*)"
    replacement = "http://mydomain/$1"

Note

Please note that regex and replacement do not have to be set in the redirect structure if an entrypoint is defined for the redirection (they will not be used in this case).

Care should be taken when defining replacement expand variables: $1x is equivalent to ${1x}, not ${1}x (see Regexp.Expand), so use ${1} syntax.

Regular expressions and replacements can be tested using online tools such as Go Playground or the Regex101.

TLS¶

Static Certificates¶

Define an entrypoint with SNI support.

[entryPoints]
  [entryPoints.https]
  address = ":443"
    [entryPoints.https.tls]
      [[entryPoints.https.tls.certificates]]
      certFile = "integration/fixtures/https/snitest.com.cert"
      keyFile = "integration/fixtures/https/snitest.com.key"

Note

If an empty TLS configuration is done, default self-signed certificates are generated.

Dynamic Certificates¶

If you need to add or remove TLS certificates while Traefik is started, Dynamic TLS certificates are supported using the file provider.

TLS Mutual Authentication¶

TLS Mutual Authentication can be optional or not. If it's optional, Træfik will authorize connection with certificates not signed by a specified Certificate Authority (CA). Otherwise, Træfik will only accept clients that present a certificate signed by a specified Certificate Authority (CA). ClientCAFiles can be configured with multiple CA:s in the same file or use multiple files containing one or several CA:s. The CA:s has to be in PEM format.

By default, ClientCAFiles is not optional, all clients will be required to present a valid cert. The requirement will apply to all server certs in the entrypoint.

In the example below both snitest.com and snitest.org will require client certs

[entryPoints]
  [entryPoints.https]
  address = ":443"
  [entryPoints.https.tls]
    [entryPoints.https.tls.ClientCA]
    files = ["tests/clientca1.crt", "tests/clientca2.crt"]
    optional = false
    [[entryPoints.https.tls.certificates]]
    certFile = "integration/fixtures/https/snitest.com.cert"
    keyFile = "integration/fixtures/https/snitest.com.key"
    [[entryPoints.https.tls.certificates]]
    certFile = "integration/fixtures/https/snitest.org.cert"
    keyFile = "integration/fixtures/https/snitest.org.key"

Note

The deprecated argument ClientCAFiles allows adding Client CA files which are mandatory. If this parameter exists, the new ones are not checked.

Authentication¶

Basic Authentication¶

Passwords can be encoded in MD5, SHA1 and BCrypt: you can use htpasswd to generate them.

Users can be specified directly in the TOML file, or indirectly by referencing an external file; if both are provided, the two are merged, with external file contents having precedence.

# To enable basic auth on an entrypoint with 2 user/pass: test:test and test2:test2
[entryPoints]
  [entryPoints.http]
  address = ":80"
  [entryPoints.http.auth.basic]
  users = ["test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/", "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"]
  usersFile = "/path/to/.htpasswd"

Digest Authentication¶

You can use htdigest to generate them.

Users can be specified directly in the TOML file, or indirectly by referencing an external file; if both are provided, the two are merged, with external file contents having precedence

# To enable digest auth on an entrypoint with 2 user/realm/pass: test:traefik:test and test2:traefik:test2
[entryPoints]
  [entryPoints.http]
  address = ":80"
  [entryPoints.http.auth.digest]
  users = ["test:traefik:a2688e031edb4be6a3797f3882655c05", "test2:traefik:518845800f9e2bfb1f1f740ec24f074e"]
  usersFile = "/path/to/.htdigest"

Forward Authentication¶

This configuration will first forward the request to http://authserver.com/auth.

If the response code is 2XX, access is granted and the original request is performed. Otherwise, the response from the authentication server is returned.

[entryPoints]
  [entryPoints.http]
    # ...
    # 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.
    #
    # Optional
    # Default: false
    #
    trustForwardHeader = true

    # Enable forward auth TLS connection.
    #
    # Optional
    #
    [entryPoints.http.auth.forward.tls]
    cert = "authserver.crt"
    key = "authserver.key"

Specify Minimum TLS Version¶

To specify an https entry point with a minimum TLS version, and specifying an array of cipher suites (from crypto/tls).

[entryPoints]
  [entryPoints.https]
  address = ":443"
    [entryPoints.https.tls]
    minVersion = "VersionTLS12"
    cipherSuites = [
      "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
      "TLS_RSA_WITH_AES_256_GCM_SHA384"
    ]
      [[entryPoints.https.tls.certificates]]
      certFile = "integration/fixtures/https/snitest.com.cert"
      keyFile = "integration/fixtures/https/snitest.com.key"
      [[entryPoints.https.tls.certificates]]
      certFile = "integration/fixtures/https/snitest.org.cert"
      keyFile = "integration/fixtures/https/snitest.org.key"

Compression¶

To enable compression support using gzip format.

[entryPoints]
  [entryPoints.http]
  address = ":80"
  compress = true

Responses are compressed when:

The response body is larger than 512 bytes
And the Accept-Encoding request header contains gzip
And the response is not already compressed, i.e. the Content-Encoding response header is not already set.

White Listing¶

To enable IP white listing at the entry point level.

[entryPoints]
  [entryPoints.http]
    address = ":80"

    [entryPoints.http.whiteList]
      sourceRange = ["127.0.0.1/32", "192.168.1.7"]
      # useXForwardedFor = true

ProxyProtocol¶

To enable ProxyProtocol support. Only IPs in trustedIPs will lead to remote client address replacement: you should declare your load-balancer IP or CIDR range here (in testing environment, you can trust everyone using insecure = true).

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.

[entryPoints]
  [entryPoints.http]
    address = ":80"

    # Enable ProxyProtocol
    [entryPoints.http.proxyProtocol]
      # List of trusted IPs
      #
      # Required
      # Default: []
      #
      trustedIPs = ["127.0.0.1/32", "192.168.1.7"]

      # Insecure mode FOR TESTING ENVIRONNEMENT ONLY
      #
      # Optional
      # Default: false
      #
      # insecure = true

Forwarded Header¶

Only IPs in trustedIPs will be authorized to trust the client forwarded headers (X-Forwarded-*).

[entryPoints]
  [entryPoints.http]
    address = ":80"

    # Enable Forwarded Headers
    [entryPoints.http.forwardedHeaders]
      # List of trusted IPs
      #
      # Required
      # Default: []
      #
      trustedIPs = ["127.0.0.1/32", "192.168.1.7"]