baalajimaestro/traefik
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions

docs: rewrite of the HTTPS and TLS section

Browse source 
Co-authored-by: Ludovic Fernandez <ldez@users.noreply.github.com>
This commit is contained in:
mpl 2019-06-19 19:00:06 +02:00 committed by Traefiker Bot
parent 429b1d8574
commit 4012599264
7 changed files with 184 additions and 172 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

145
docs/content/https-tls/overview.md
View file

@ -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`).

4
docs/content/https-tls/acme.md → docs/content/https/acme.md
View file

@ -1,4 +1,4 @@
# ACME # Let's Encrypt
Automatic HTTPS Automatic HTTPS
{: .subtitle } {: .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: There are many available options for ACME. For a quick glance at what's possible, browse the configuration reference:
```toml ```toml
--8<-- "content/https-tls/ref-acme.toml" --8<-- "content/https/ref-acme.toml"
``` ```
## Automatic Renewals ## Automatic Renewals

16
docs/content/https/overview.md Normal file
View file

@ -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).

0
docs/content/https-tls/ref-acme.toml → docs/content/https/ref-acme.toml
View file

140
docs/content/https/tls.md Normal file
View file

@ -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
```

40
docs/content/routing/routers/index.md
View file

@ -108,15 +108,15 @@ If the rule is verified, the router becomes active, calls middlewares, and then
The table below lists all the available matchers: The table below lists all the available matchers:
| Rule | Description | | Rule | Description |
|--------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------| |----------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|
| ``Headers(`key`, `value`)`` | Check if there is a key `key`defined in the headers, with the value `value` | | ```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` | | ```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`. | | ```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`. | | ```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`) | | `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. | | ```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. | | ```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. | | ```Query(`foo=bar`, `bar=baz`)``` | Match` Query String parameters. It accepts a sequence of key=value pairs. |
!!! important "Regexp Syntax" !!! important "Regexp Syntax"
@ -173,7 +173,7 @@ Traefik will terminate the SSL connections (meaning that it will send decrypted
!!! note "HTTPS & ACME" !!! 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" !!! note "Passthrough"
@ -200,7 +200,7 @@ Traefik will terminate the SSL connections (meaning that it will send decrypted
#### `Options` #### `Options`
The `Options` field enables fine-grained control of the TLS parameters. 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" ??? example "Configuring the tls options"
@ -226,13 +226,13 @@ It refers to a [tlsOptions](../../https-tls/overview/#configuration-options) and
### General ### 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. If no matching route is found for the TCP routers, then the HTTP routers will take over.
### EntryPoints ### EntryPoints
If not specified, TCP routers will accept requests from all defined entrypoints. 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 entrypoints, set the entrypoints option. If you want to limit the router scope to a set of entry points, set the entry points option.
??? example "Listens to Every EntryPoint" ??? example "Listens to Every EntryPoint"
@ -275,8 +275,8 @@ If you want to limit the router scope to a set of entrypoints, set the entrypoin
### Rule ### Rule
| Rule | Description | | Rule | Description |
|------------------------------|-------------------------------------------------------------------------| |--------------------------------|-------------------------------------------------------------------------|
| ``HostSNI(`domain-1`, ...)`` | Check if the Server Name Indication corresponds to the given `domains`. | | ```HostSNI(`domain-1`, ...)``` | Check if the Server Name Indication corresponds to the given `domains`. |
!!! important "HostSNI & TLS" !!! important "HostSNI & TLS"
@ -305,7 +305,7 @@ Services are the target for the router.
```toml ```toml
[tcp.routers] [tcp.routers]
[tcp.routers.Router-1] [tcp.routers.Router-1]
rule = "Host(`foo-domain`)" rule = "HostSNI(`foo-domain`)"
service = "service-id" service = "service-id"
[tcp.routers.Router-1.tls] # will terminate the TLS request by default [tcp.routers.Router-1.tls] # will terminate the TLS request by default
``` ```
@ -315,7 +315,7 @@ Services are the target for the router.
```toml ```toml
[tcp.routers] [tcp.routers]
[tcp.routers.Router-1] [tcp.routers.Router-1]
rule = "Host(`foo-domain`)" rule = "HostSNI(`foo-domain`)"
service = "service-id" service = "service-id"
[tcp.routers.Router-1.tls] [tcp.routers.Router-1.tls]
passthrough=true passthrough=true
@ -323,19 +323,19 @@ Services are the target for the router.
!!! note "TLS & ACME" !!! 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` #### `Options`
The `Options` field enables fine-grained control of the TLS parameters. 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" ??? example "Configuring the tls options"
```toml ```toml
[tcp.routers] [tcp.routers]
[tcp.routers.Router-1] [tcp.routers.Router-1]
rule = "Host(`foo-domain`) && Path(`/foo-path/`)" rule = "HostSNI(`foo-domain`)"
service = "service-id" service = "service-id"
[tcp.routers.Router-1.tls] # will terminate the TLS request [tcp.routers.Router-1.tls] # will terminate the TLS request
options = "foo" options = "foo"

5
docs/mkdocs.yml
View file

@ -85,8 +85,9 @@ nav:
- 'Routers': 'routing/routers/index.md' - 'Routers': 'routing/routers/index.md'
- 'Services': 'routing/services/index.md' - 'Services': 'routing/services/index.md'
- 'HTTPS & TLS': - 'HTTPS & TLS':
- 'Overview': 'https-tls/overview.md' - 'Overview': 'https/overview.md'
- 'ACME': 'https-tls/acme.md' - 'TLS': 'https/tls.md'
- 'Let''s Encrypt': 'https/acme.md'
- 'Middlewares': - 'Middlewares':
- 'Overview': 'middlewares/overview.md' - 'Overview': 'middlewares/overview.md'
- 'AddPrefix': 'middlewares/addprefix.md' - 'AddPrefix': 'middlewares/addprefix.md'