diff --git a/docs/content/https-tls/overview.md b/docs/content/https-tls/overview.md deleted file mode 100644 index 3b1a20733..000000000 --- a/docs/content/https-tls/overview.md +++ /dev/null @@ -1,145 +0,0 @@ -# HTTPS & TLS - -Traefik supports HTTPS & TLS, and is able to accept new certificates / updates over time (without being restarted). -TLS is enabled at the [router](../routing/routers/index.md) level, but some options are configured in dedicated sections (`tlsOptions` & `tlsStores`) described in this section. - -## Configuration Example - -??? example "Configuring a Default Certificate" - - ```toml - [tlsStores] - [tlsStores.default] - [tlsStores.default.defaultCertificate] - certFile = "path/to/cert.crt" - keyFile = "path/to/cert.key" - ``` - -??? example "Configuring a Minimum TLS Version" - - ```toml - [tlsOptions] - [tlsOptions.default] - minVersion = "VersionTLS12" - ``` - -??? example "Defining Certificates" - - ```toml - [[tls]] - [tls.certificate] - certFile = "/path/to/domain.cert" - keyFile = "/path/to/domain.key" - - [[tls]] - [tls.certificate] - certFile = "/path/to/other-domain.cert" - keyFile = "/path/to/other-domain.key" - ``` - -!!! important "File Provider Only" - - In the above example, we've used the [file provider](../providers/file.md) to handle the TLS configuration (tlsStores, tlsOptions, and TLS certificates). - In its current alpha version, it is the only available method to configure these elements. - Of course, these options are hot reloaded and can be updated at runtime (they belong to the [dynamic configuration](../getting-started/configuration-overview.md)). - -## Configuration Options - -### Dynamic Certificates - -To add / remove TLS certificates while Traefik is running, the [file provider](../providers/file.md) supports Dynamic TLS certificates in its `[[tls]]` section. - -!!! example "Defining Certificates" - - ```toml - [[tls]] - stores = ["default"] - [tls.certificate] - certFile = "/path/to/domain.cert" - keyFile = "/path/to/domain.key" - - [[tls]] - stores = ["default"] - [tls.certificate] - certFile = "/path/to/other-domain.cert" - keyFile = "/path/to/other-domain.key" - ``` - - ??? note "Stores" - - During the alpha version, the stores option will be ignored and be automatically set to ["default"]. - -### Mutual Authentication - -Traefik supports both optional and non optional (defaut value) mutual authentication. - -- When `optional = false`, Traefik accepts connections only from client presenting a certificate signed by a CA listed in `ClientCA.files`. -- When `optional = true`, Traefik authorizes connections from client presenting a certificate signed by an unknown CA. - -!!! example "Non Optional Mutual Authentication" - - In the following example, both `snitest.com` and `snitest.org` will require client certificates. - - ```toml - [tlsOptions] - [tlsOptions.default] - [tlsOptions.default.ClientCA] - files = ["tests/clientca1.crt", "tests/clientca2.crt"] - optional = false - ``` - - ??? note "ClientCA.files" - - You can use a file per `CA:s`, or a single file containing multiple `CA:s` (in `PEM` format). - - `ClientCA.files` is not optional: every client will have to present a valid certificate. (This requirement will apply to every server certificate declared in the entrypoint.) - -### Minimum TLS Version - -!!! example "Min TLS version & [cipherSuites](https://godoc.org/crypto/tls#pkg-constants)" - - ```toml - [tlsOptions] - [tlsOptions.default] - minVersion = "VersionTLS12" - cipherSuites = [ - "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", - "TLS_RSA_WITH_AES_256_GCM_SHA384" - ] - ``` - -### Strict SNI Checking - -With strict SNI checking, Traefik won't allow connections without a matching certificate. - -!!! example "Strict SNI" - - ```toml - [tlsOptions] - [tlsOptions.default] - sniStrict = true - ``` - -### Default Certificate - -Traefik can use a default certificate for connections without a SNI, or without a matching domain. - -If no default certificate is provided, Traefik generates and uses a self-signed certificate. - -!!! example "Setting a Default Certificate" - - ```toml - [tlsStores] - [tlsStores.default] - [tlsStores.default.defaultCertificate] - certFile = "path/to/cert.crt" - keyFile = "path/to/cert.key" - ``` - - ??? note "Only One Default Certificate" - - There can only be one `defaultCertificate` per tlsOptions. - - ??? note "Default TLS Store" - - During the alpha version, there is only one globally available TLS Store (`default`). diff --git a/docs/content/https-tls/acme.md b/docs/content/https/acme.md similarity index 99% rename from docs/content/https-tls/acme.md rename to docs/content/https/acme.md index ab6e8173e..ef75ecf5d 100644 --- a/docs/content/https-tls/acme.md +++ b/docs/content/https/acme.md @@ -1,4 +1,4 @@ -# ACME +# Let's Encrypt Automatic HTTPS {: .subtitle } @@ -54,7 +54,7 @@ You can configure Traefik to use an ACME provider (like Let's Encrypt) for autom There are many available options for ACME. For a quick glance at what's possible, browse the configuration reference: ```toml - --8<-- "content/https-tls/ref-acme.toml" + --8<-- "content/https/ref-acme.toml" ``` ## Automatic Renewals diff --git a/docs/content/https/overview.md b/docs/content/https/overview.md new file mode 100644 index 000000000..d03950388 --- /dev/null +++ b/docs/content/https/overview.md @@ -0,0 +1,16 @@ +# HTTPS & TLS + +Overview +{: .subtitle } + +Traefik supports HTTPS & TLS, which concerns roughly two parts of the configuration: +routers, and the TLS connection (and its underlying certificates). + +When a router has to handle HTTPS traffic, +it should be specified with a `tls` field of the router definition. +See the TLS section of the [routers documentation](../routing/routers/index.md#tls). + +The next sections of this documentation explain how to configure the TLS connection itself. +That is to say, how to obtain [TLS certificates](./tls.md#certificates-definition): +either through a definition in the dynamic configuration, or through [Let's Encrypt](./acme.md) (ACME). +And how to configure [TLS options](./tls.md#tls-options), and [certificates stores](./tls.md#certificates-stores). diff --git a/docs/content/https-tls/ref-acme.toml b/docs/content/https/ref-acme.toml similarity index 100% rename from docs/content/https-tls/ref-acme.toml rename to docs/content/https/ref-acme.toml diff --git a/docs/content/https/tls.md b/docs/content/https/tls.md new file mode 100644 index 000000000..c67da5d95 --- /dev/null +++ b/docs/content/https/tls.md @@ -0,0 +1,140 @@ +# TLS + +Transport Layer Security +{: .subtitle } + +## Certificates Definition + +### Automated + +See the [Let's Encrypt](./acme.md) page. + +### User defined + +To add / remove TLS certificates, even when Traefik is already running, their definition can be added to the [dynamic configuration](../getting-started/configuration-overview.md), in the `[[tls]]` section: + +```toml +[[tls]] + [tls.certificate] + certFile = "/path/to/domain.cert" + keyFile = "/path/to/domain.key" + +[[tls]] + [tls.certificate] + certFile = "/path/to/other-domain.cert" + keyFile = "/path/to/other-domain.key" +``` + +!!! important "File Provider Only" + + In the above example, we've used the [file provider](../providers/file.md) to handle these definitions. + In its current alpha version, it is the only available method to configure the certificates (as well as the options and the stores). + +## Certificates Stores + +In Traefik, certificates are grouped together in certificates stores, which are defined as such: + +```toml +[tlsStores] + [tlsStores.default] +``` + +!!! important "Alpha restriction" + + During the alpha version, any store definition other than the default one (named `default`) will be ignored, + and there is thefore only one globally available TLS store. + +In the `[[tls]]` section, a list of stores can then be specified to indicate where the certificates should be stored: + +```toml +[[tls]] + stores = ["default"] + [tls.certificate] + certFile = "/path/to/domain.cert" + keyFile = "/path/to/domain.key" + +[[tls]] + # Note that since no store is defined, + # the certificate below will be stored in the `default` store. + [tls.certificate] + certFile = "/path/to/other-domain.cert" + keyFile = "/path/to/other-domain.key" +``` + +!!! important "Alpha restriction" + + During the alpha version, the `stores` list will actually be ignored and automatically set to `["default"]`. + +### Default Certificate + +Traefik can use a default certificate for connections without a SNI, or without a matching domain. +This default certificate should be defined in a TLS store: + +```toml +[tlsStores] + [tlsStores.default] + [tlsStores.default.defaultCertificate] + certFile = "path/to/cert.crt" + keyFile = "path/to/cert.key" +``` + +If no default certificate is provided, Traefik generates and uses a self-signed certificate. + +## TLS Options + +The TLS options allow one to configure some parameters of the TLS connection. + +### Minimum TLS Version + +```toml +[tlsOptions] + + [tlsOptions.default] + minVersion = "VersionTLS12" + + [tlsOptions.mintls13] + minVersion = "VersionTLS13" +``` + +### Mutual Authentication + +Traefik supports both optional and strict (which is the default) mutual authentication, though the `ClientCA.files` section. +If present, connections from clients without a certificate will be rejected. + +For clients with a certificate, the `optional` option governs the behaviour as follows: + +- When `optional = false`, Traefik accepts connections only from clients presenting a certificate signed by a CA listed in `ClientCA.files`. +- When `optional = true`, Traefik authorizes connections from clients presenting a certificate signed by an unknown CA. + +```toml +[tlsOptions] + [tlsOptions.default] + [tlsOptions.default.ClientCA] + # in PEM format. each file can contain multiple CAs. + files = ["tests/clientca1.crt", "tests/clientca2.crt"] + optional = false +``` + +### Cipher Suites + +See [cipherSuites](https://godoc.org/crypto/tls#pkg-constants) for more information. + +```toml +[tlsOptions] + [tlsOptions.default] + cipherSuites = [ + "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", + "TLS_RSA_WITH_AES_256_GCM_SHA384" + ] +``` + +### Strict SNI Checking + +With strict SNI checking, Traefik won't allow connections from clients connections +that do not specify a server_name extension. + +```toml +[tlsOptions] + [tlsOptions.default] + sniStrict = true +``` diff --git a/docs/content/routing/routers/index.md b/docs/content/routing/routers/index.md index 05be2b464..0dfaa2348 100644 --- a/docs/content/routing/routers/index.md +++ b/docs/content/routing/routers/index.md @@ -107,16 +107,16 @@ If the rule is verified, the router becomes active, calls middlewares, and then ``` The table below lists all the available matchers: -| Rule | Description | -|--------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------| -| ``Headers(`key`, `value`)`` | Check if there is a key `key`defined in the headers, with the value `value` | -| ``HeadersRegexp(`key`, `regexp`)`` | Check if there is a key `key`defined in the headers, with a value that matches the regular expression `regexp` | -| ``Host(`domain-1`, ...)`` | Check if the request domain targets one of the given `domains`. | -| ``HostRegexp(`traefik.io`, `{subdomain:[a-z]+}.traefik.io`, ...)`` | Check if the request domain matches the given `regexp`. | -| `Method(methods, ...)` | Check if the request method is one of the given `methods` (`GET`, `POST`, `PUT`, `DELETE`, `PATCH`) | -| ``Path(`path`, `/articles/{category}/{id:[0-9]+}`, ...)`` | Match exact request path. It accepts a sequence of literal and regular expression paths. | -| ``PathPrefix(`/products/`, `/articles/{category}/{id:[0-9]+}`)`` | Match request prefix path. It accepts a sequence of literal and regular expression prefix paths. | -| ``Query(`foo=bar`, `bar=baz`)`` | Match` Query String parameters. It accepts a sequence of key=value pairs. | +| Rule | Description | +|----------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------| +| ```Headers(`key`, `value`)``` | Check if there is a key `key`defined in the headers, with the value `value` | +| ```HeadersRegexp(`key`, `regexp`)``` | Check if there is a key `key`defined in the headers, with a value that matches the regular expression `regexp` | +| ```Host(`domain-1`, ...)``` | Check if the request domain targets one of the given `domains`. | +| ```HostRegexp(`traefik.io`, `{subdomain:[a-z]+}.traefik.io`, ...)``` | Check if the request domain matches the given `regexp`. | +| `Method(methods, ...)` | Check if the request method is one of the given `methods` (`GET`, `POST`, `PUT`, `DELETE`, `PATCH`) | +| ```Path(`path`, `/articles/{category}/{id:[0-9]+}`, ...)``` | Match exact request path. It accepts a sequence of literal and regular expression paths. | +| ```PathPrefix(`/products/`, `/articles/{category}/{id:[0-9]+}`)``` | Match request prefix path. It accepts a sequence of literal and regular expression prefix paths. | +| ```Query(`foo=bar`, `bar=baz`)``` | Match` Query String parameters. It accepts a sequence of key=value pairs. | !!! important "Regexp Syntax" @@ -173,7 +173,7 @@ Traefik will terminate the SSL connections (meaning that it will send decrypted !!! note "HTTPS & ACME" - In the current version, with [ACME](../../https-tls/acme.md) enabled, automatic certificate generation will apply to every router declaring a TLS section. + In the current version, with [ACME](../../https/acme.md) enabled, automatic certificate generation will apply to every router declaring a TLS section. !!! note "Passthrough" @@ -200,7 +200,7 @@ Traefik will terminate the SSL connections (meaning that it will send decrypted #### `Options` The `Options` field enables fine-grained control of the TLS parameters. -It refers to a [tlsOptions](../../https-tls/overview/#configuration-options) and will be applied only if a `Host` rule is defined. +It refers to a [tlsOptions](../../https/tls.md#tls-options) and will be applied only if a `Host` rule is defined. ??? example "Configuring the tls options" @@ -226,13 +226,13 @@ It refers to a [tlsOptions](../../https-tls/overview/#configuration-options) and ### General -If both HTTP routers and TCP routers listen to the same entrypoints, the TCP routers will apply *before* the HTTP routers. +If both HTTP routers and TCP routers listen to the same entry points, the TCP routers will apply *before* the HTTP routers. If no matching route is found for the TCP routers, then the HTTP routers will take over. ### EntryPoints -If not specified, TCP routers will accept requests from all defined entrypoints. -If you want to limit the router scope to a set of entrypoints, set the entrypoints option. +If not specified, TCP routers will accept requests from all defined entry points. +If you want to limit the router scope to a set of entry points, set the entry points option. ??? example "Listens to Every EntryPoint" @@ -274,9 +274,9 @@ If you want to limit the router scope to a set of entrypoints, set the entrypoin ### Rule -| Rule | Description | -|------------------------------|-------------------------------------------------------------------------| -| ``HostSNI(`domain-1`, ...)`` | Check if the Server Name Indication corresponds to the given `domains`. | +| Rule | Description | +|--------------------------------|-------------------------------------------------------------------------| +| ```HostSNI(`domain-1`, ...)``` | Check if the Server Name Indication corresponds to the given `domains`. | !!! important "HostSNI & TLS" @@ -305,7 +305,7 @@ Services are the target for the router. ```toml [tcp.routers] [tcp.routers.Router-1] - rule = "Host(`foo-domain`)" + rule = "HostSNI(`foo-domain`)" service = "service-id" [tcp.routers.Router-1.tls] # will terminate the TLS request by default ``` @@ -315,7 +315,7 @@ Services are the target for the router. ```toml [tcp.routers] [tcp.routers.Router-1] - rule = "Host(`foo-domain`)" + rule = "HostSNI(`foo-domain`)" service = "service-id" [tcp.routers.Router-1.tls] passthrough=true @@ -323,19 +323,19 @@ Services are the target for the router. !!! note "TLS & ACME" - In the current version, with [ACME](../../https-tls/acme.md) enabled, automatic certificate generation will apply to every router declaring a TLS section. + In the current version, with [ACME](../../https/acme.md) enabled, automatic certificate generation will apply to every router declaring a TLS section. #### `Options` The `Options` field enables fine-grained control of the TLS parameters. -It refers to a [tlsOptions](../../https-tls/overview/#configuration-options) and will be applied only if a `HostSNI` rule is defined. +It refers to a [tlsOptions](../../https/tls.md#tls-options) and will be applied only if a `HostSNI` rule is defined. ??? example "Configuring the tls options" ```toml [tcp.routers] [tcp.routers.Router-1] - rule = "Host(`foo-domain`) && Path(`/foo-path/`)" + rule = "HostSNI(`foo-domain`)" service = "service-id" [tcp.routers.Router-1.tls] # will terminate the TLS request options = "foo" diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 4a7a40cd1..6dfbe7488 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -85,8 +85,9 @@ nav: - 'Routers': 'routing/routers/index.md' - 'Services': 'routing/services/index.md' - 'HTTPS & TLS': - - 'Overview': 'https-tls/overview.md' - - 'ACME': 'https-tls/acme.md' + - 'Overview': 'https/overview.md' + - 'TLS': 'https/tls.md' + - 'Let''s Encrypt': 'https/acme.md' - 'Middlewares': - 'Overview': 'middlewares/overview.md' - 'AddPrefix': 'middlewares/addprefix.md'