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

Enhance acme page.

Browse source
This commit is contained in:
Ludovic Fernandez 2019-03-18 10:50:05 +01:00 committed by Traefiker Bot
parent f3ecc040c8
commit 9908137638
6 changed files with 188 additions and 235 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

113
docs/content/https-tls/acme.md
View file

@ -53,14 +53,15 @@ 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](../reference/acme.md).
## Configuration Options
## The Different ACME Challenges
### The Different ACME Challenges
#### tlsChallenge
### `tlsChallenge`
Use the `TLS-ALPN-01` challenge to generate and renew ACME certificates by provisioning a TLS certificate.
As described on the Let's Encrypt [community forum](https://community.letsencrypt.org/t/support-for-ports-other-than-80-and-443/3419/72),
when using the `TLS-ALPN-01` challenge, Traefik must be reachable by Let's Encrypt through port 443.
??? example "Configuring the `tlsChallenge`"
```toml
@ -68,13 +69,13 @@ Use the `TLS-ALPN-01` challenge to generate and renew ACME certificates by provi
[acme.tlsChallenge]
```
!!! note
As described on the Let's Encrypt [community forum](https://community.letsencrypt.org/t/support-for-ports-other-than-80-and-443/3419/72), when using the `TLS-ALPN-01` challenge, Traefik must be reachable by Let's Encrypt through port 443.
#### `httpChallenge`
### `httpChallenge`
Use the `HTTP-01` challenge to generate and renew ACME certificates by provisioning an HTTP resource under a well-known URI.
As described on the Let's Encrypt [community forum](https://community.letsencrypt.org/t/support-for-ports-other-than-80-and-443/3419/72),
when using the `HTTP-01` challenge, `acme.httpChallenge.entryPoint` must be reachable by Let's Encrypt through port 80.
??? example "Using an EntryPoint Called http for the `httpChallenge`"
```toml
@ -84,17 +85,14 @@ Use the `HTTP-01` challenge to generate and renew ACME certificates by provision
entryPoint = "http"
```
!!! note
As described on the Let's Encrypt [community forum](https://community.letsencrypt.org/t/support-for-ports-other-than-80-and-443/3419/72), when using the `HTTP-01` challenge, `acme.httpChallenge.entryPoint` must be reachable by Let's Encrypt through port 80.
!!! note
Redirection is fully compatible with the `HTTP-01` challenge.
#### `dnsChallenge`
### `dnsChallenge`
Use the `DNS-01` challenge to generate and renew ACME certificates by provisioning a DNS record.
??? example "Configuring a `dnsChallenge` with the digitalocean Provider"
??? example "Configuring a `dnsChallenge` with the DigitalOcean Provider"
```toml
[acme]
@ -108,9 +106,10 @@ Use the `DNS-01` challenge to generate and renew ACME certificates by provisioni
!!! important
A `provider` is mandatory.
??? list "Supported Providers"
#### `providers`
Here is a list of supported `providers`, that can automate the DNS verification, along with the required environment variables and their [wildcard & root domain support](#wildcard-domains).
Here is a list of supported `providers`, that can automate the DNS verification,
along with the required environment variables and their [wildcard & root domain support](#wildcard-domains).
Do not hesitate to complete it.
| Provider Name | Provider Code | Environment Variables | Wildcard & Root Domain Support |
@ -138,9 +137,9 @@ Do not hesitate to complete it.
| [Gandi v5](http://doc.livedns.gandi.net) | `gandiv5` | `GANDIV5_API_KEY` | YES |
| [Glesys](https://glesys.com/) | `glesys` | `GLESYS_API_USER`, `GLESYS_API_KEY`, `GLESYS_DOMAIN` | Not tested yet |
| [GoDaddy](https://godaddy.com/domains) | `godaddy` | `GODADDY_API_KEY`, `GODADDY_API_SECRET` | Not tested yet |
| [Google Cloud DNS](https://cloud.google.com/dns/docs/) | `gcloud` | `GCE_PROJECT`, Application Default Credentials (2) (3), [`GCE_SERVICE_ACCOUNT_FILE`] | YES |
| [Google Cloud DNS](https://cloud.google.com/dns/docs/) | `gcloud` | `GCE_PROJECT`, Application Default Credentials [^2] [^3], [`GCE_SERVICE_ACCOUNT_FILE`] | YES |
| [hosting.de](https://www.hosting.de) | `hostingde` | `HOSTINGDE_API_KEY`, `HOSTINGDE_ZONE_NAME` | Not tested yet |
| HTTP request | `httpreq` | `HTTPREQ_ENDPOINT`, `HTTPREQ_MODE`, `HTTPREQ_USERNAME`, `HTTPREQ_PASSWORD` (1) | YES |
| HTTP request | `httpreq` | `HTTPREQ_ENDPOINT`, `HTTPREQ_MODE`, `HTTPREQ_USERNAME`, `HTTPREQ_PASSWORD` [^1] | YES |
| [IIJ](https://www.iij.ad.jp/) | `iij` | `IIJ_API_ACCESS_KEY`, `IIJ_API_SECRET_KEY`, `IIJ_DO_SERVICE_CODE` | Not tested yet |
| [INWX](https://www.inwx.de/en) | `inwx` | `INWX_USERNAME`, `INWX_PASSWORD` | YES |
| [Lightsail](https://aws.amazon.com/lightsail/) | `lightsail` | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `DNS_ZONE` | Not tested yet |
@ -170,16 +169,16 @@ Do not hesitate to complete it.
| [VULTR](https://www.vultr.com) | `vultr` | `VULTR_API_KEY` | Not tested yet |
| [Zone.ee](https://www.zone.ee) | `zoneee` | `ZONEEE_API_USER`, `ZONEEE_API_KEY` | YES |
- (1): more information about the HTTP message format can be found [here](https://go-acme.github.io/lego/dns/httpreq/)
- (2): https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application
- (3): https://github.com/golang/oauth2/blob/36a7019397c4c86cf59eeab3bc0d188bac444277/google/default.go#L61-L76
[^1]: more information about the HTTP message format can be found [here](https://go-acme.github.io/lego/dns/httpreq/)
[^2]: [providing_credentials_to_your_application](https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application)
[^3]: [google/default.go](https://github.com/golang/oauth2/blob/36a7019397c4c86cf59eeab3bc0d188bac444277/google/default.go#L61-L76)
!!! note "`delayBeforeCheck`"
By default, the `provider` verifies the TXT record _before_ letting ACME verify.
You can delay this operation by specifying a delay (in seconds) with `delayBeforeCheck` (value must be greater than zero).
This option is useful when internal networks block external DNS queries.
!!! note "`resolvers`"
#### `resolvers`
Use custom DNS servers to resolve the FQDN authority.
@ -191,7 +190,36 @@ Do not hesitate to complete it.
resolvers = ["1.1.1.1:53", "8.8.8.8:53"]
```
### Known Domains, SANs, and Wildcards
#### Wildcard Domains
[ACME V2](https://community.letsencrypt.org/t/acme-v2-and-wildcard-certificate-support-is-live/55579) supports wildcard certificates.
As described in [Let's Encrypt's post](https://community.letsencrypt.org/t/staging-endpoint-for-acme-v2/49605) wildcard certificates can only be generated through a [`DNS-01` challenge](#dnschallenge).
```toml
[acme]
# ...
[[acme.domains]]
main = "*.local1.com"
sans = ["local1.com"]
# ...
```
!!! note "Double Wildcard Certificates"
It is not possible to request a double wildcard certificate for a domain (for example `*.*.local.com`).
Due to an ACME limitation it is not possible to define wildcards in SANs (alternative domains).
Thus, the wildcard domain has to be defined as a main domain.
Most likely the root domain should receive a certificate too, so it needs to be specified as SAN and 2 `DNS-01` challenges are executed.
In this case the generated DNS TXT record for both domains is the same.
Even though this behavior is [DNS RFC](https://community.letsencrypt.org/t/wildcard-issuance-two-txt-records-for-the-same-name/54528/2) compliant,
it can lead to problems as all DNS providers keep DNS records cached for a given time (TTL) and this TTL can be greater than the challenge timeout making the `DNS-01` challenge fail.
The Traefik ACME client library [LEGO](https://github.com/go-acme/lego) supports some but not all DNS providers to work around this issue.
The [Supported `provider` table](#providers) indicates if they allow generating certificates for a wildcard domain and its root domain.
## Known Domains, SANs
You can set SANs (alternative domains) for each main domain.
Every domain must have A/AAAA records pointing to Traefik.
@ -217,36 +245,7 @@ Each domain & SAN will lead to a certificate request.
!!! note
Wildcard certificates can only be verified through a `DNS-01` challenge.
#### Wildcard Domains
[ACME V2](https://community.letsencrypt.org/t/acme-v2-and-wildcard-certificate-support-is-live/55579) supports wildcard certificates.
As described in [Let's Encrypt's post](https://community.letsencrypt.org/t/staging-endpoint-for-acme-v2/49605) wildcard certificates can only be generated through a [`DNS-01` challenge](#dnschallenge).
```toml
[acme]
# ...
[[acme.domains]]
main = "*.local1.com"
sans = ["local1.com"]
# ...
```
!!! warning
Take note that Let's Encrypt applies [rate limiting](https://letsencrypt.org/docs/rate-limits).
!!! note "Double Wildcard Certificates"
It is not possible to request a double wildcard certificate for a domain (for example `*.*.local.com`).
Due to an ACME limitation it is not possible to define wildcards in SANs (alternative domains).
Thus, the wildcard domain has to be defined as a main domain.
Most likely the root domain should receive a certificate too, so it needs to be specified as SAN and 2 `DNS-01` challenges are executed.
In this case the generated DNS TXT record for both domains is the same.
Even though this behavior is [DNS RFC](https://community.letsencrypt.org/t/wildcard-issuance-two-txt-records-for-the-same-name/54528/2) compliant, it can lead to problems as all DNS providers keep DNS records cached for a given time (TTL) and this TTL can be greater than the challenge timeout making the `DNS-01` challenge fail.
The Traefik ACME client library [LEGO](https://github.com/go-acme/lego) supports some but not all DNS providers to work around this issue.
The [Supported `provider` table](#dnschallenge) indicates if they allow generating certificates for a wildcard domain and its root domain.
### caServer
## `caServer`
??? example "Using the Let's Encrypt staging server"
@ -257,7 +256,7 @@ The [Supported `provider` table](#dnschallenge) indicates if they allow generati
# ...
```
### onHostRule
## `onHostRule`
Enable certificate generation on [routers](../routing/routers/index.md) `Host` & `HostSNI` rules.
@ -276,7 +275,7 @@ This will request a certificate from Let's Encrypt for each router with a Host r
!!! warning
`onHostRule` option can not be used to generate wildcard certificates. Refer to [wildcard generation](#wildcard-domains) for further information.
### `storage`
## `storage`
The `storage` option sets the location where your ACME certificates are saved to.
@ -292,7 +291,7 @@ The value can refer to two kinds of storage:
- a JSON file
- a KV store entry
#### In a File
### In a File
ACME certificates can be stored in a JSON file that needs to have a `600` file mode .
@ -309,7 +308,7 @@ docker run -v "/my/host/acme:/etc/traefik/acme" traefik
!!! warning
For concurrency reason, this file cannot be shared across multiple instances of Traefik. Use a key value store entry instead.
#### In a a Key Value Store Entry
### In a a Key Value Store Entry
ACME certificates can be stored in a key-value store entry.
@ -331,4 +330,4 @@ If Let's Encrypt is not reachable, the following certificates will apply:
1. Provided certificates
!!! note
For new (sub)domains which need Let's Encrypt authentification, the default Traefik certificate will be used until Traefik is restarted.
For new (sub)domains which need Let's Encrypt authentication, the default Traefik certificate will be used until Traefik is restarted.

10
docs/mkdocs.yml
View file

@ -9,6 +9,7 @@ repo_url: 'https://github.com/containous/traefik'
docs_dir: 'content'
# https://squidfunk.github.io/mkdocs-material/
theme:
name: 'material'
custom_dir: 'theme'
@ -16,9 +17,6 @@ theme:
include_sidebar: true
favicon: assets/img/traefik.icon.png
logo: assets/img/traefik.logo.png
palette:
primary: 'blue'
accent: 'light blue'
feature:
tabs: false
palette:
@ -45,6 +43,8 @@ extra_javascript:
plugins:
- search
# https://squidfunk.github.io/mkdocs-material/extensions/admonition/
# https://facelessuser.github.io/pymdown-extensions/
markdown_extensions:
- attr_list
- admonition
@ -52,10 +52,12 @@ markdown_extensions:
- pymdownx.details
- pymdownx.inlinehilite
- pymdownx.highlight:
use_pygments: false # hljs is used instead of pygment for TOML hihglighting support
use_pygments: false # hljs is used instead of pygment for TOML highlighting support
- pymdownx.smartsymbols
- pymdownx.superfences
- pymdownx.tasklist
- pymdownx.snippets:
check_paths: true
- markdown_include.include:
base_path: content/includes/
encoding: utf-8

19
docs/readme.md Normal file
View file

@ -0,0 +1,19 @@
# Documentation
## Tooling
| Tool | Documentation | Sources |
|-------------------|-------------------------------------|-----------------------------------|
| mkdocs | [documentation][mkdocs] | [Sources][mkdocs-src] |
| mkdocs-material | [documentation][mkdocs-material] | [Sources][mkdocs-material-src] |
| pymdown-extensions| [documentation][pymdown-extensions] | [Sources][pymdown-extensions-src] |
[mkdocs]: https://www.mkdocs.org "Mkdocs"
[mkdocs-src]: https://github.com/mkdocs/mkdocs "Mkdocs - Sources"
[mkdocs-material]: https://squidfunk.github.io/mkdocs-material/ "Material for MkDocs"
[mkdocs-material-src]: https://github.com/squidfunk/mkdocs-material "Material for MkDocs - Sources"
[pymdown-extensions]: https://facelessuser.github.io/pymdown-extensions/extensions "PyMdown Extensions"
[pymdown-extensions-src]: https://github.com/facelessuser/pymdown-extensions "PyMdown Extensions - Sources"

2
docs/scripts/verify.sh
View file

@ -21,7 +21,7 @@ find "${PATH_TO_SITE}" -type f -not -path "/app/site/theme/*" \
--check_external_hash \
--alt_ignore="/traefik.logo.png/" \
--http_status_ignore="0,500,501,503" \
--url-ignore "/https://groups.google.com/a/traefik.io/forum/#!forum/security/,/localhost:/,/127.0.0.1:/,/fonts.gstatic.com/,/.minikube/,/github.com\/containous\/traefik\/*edit*/,/github.com\/containous\/traefik\/$/,/docs.traefik.io/" \
--url_ignore="/https://groups.google.com/a/traefik.io/forum/#!forum/security/,/localhost:/,/127.0.0.1:/,/fonts.gstatic.com/,/.minikube/,/github.com\/containous\/traefik\/*edit*/,/github.com\/containous\/traefik\/$/,/docs.traefik.io/,/github\.com\/golang\/oauth2\/blob\/36a7019397c4c86cf59eeab3bc0d188bac444277\/.+/" \
'{}' 1>/dev/null
## HTML-proofer options at https://github.com/gjtorikian/html-proofer#configuration

37
docs/theme/main.html vendored Normal file
View file

@ -0,0 +1,37 @@
{% extends "base.html" %}
{% block footer %}
{% import "partials/language.html" as lang with context %}
<!-- Application footer -->
<footer class="md-footer">
<!-- Further information -->
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<!-- Copyright and theme information -->
<div class="md-footer-copyright">
{% if config.copyright %}
<div class="md-footer-copyright__highlight">
{{ config.copyright }}
</div>
{% endif %}
powered by
<a href="http://www.mkdocs.org" title="MkDocs">MkDocs</a>
and
<a href="http://squidfunk.github.io/mkdocs-material/"
title="Material for MkDocs">
Material for MkDocs</a>
</div>
<!-- Social links -->
{% block social %}
{% include "partials/social.html" %}
{% endblock %}
</div>
</div>
</footer>
{% endblock %}

104
docs/theme/partials/footer.html vendored
View file

@ -1,104 +0,0 @@
<!--
Copyright (c) 2016-2017 Martin Donath <martin.donath@squidfunk.com>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.
-->
{% import "partials/language.html" as lang with context %}
<!-- Application footer -->
<footer class="md-footer">
<!-- Link to previous and/or next page -->
{% if page.previous_page or page.next_page %}
<!--<div class="md-footer-nav">-->
<!--<nav class="md-footer-nav__inner md-grid">-->
<!-- -->
<!-- Link to previous page -->
<!--{% if page.previous_page %}-->
<!--<a href="{{ page.previous_page.url }}"-->
<!--title="{{ page.previous_page.title }}"-->
<!--class="md-flex md-footer-nav__link md-footer-nav__link&#45;&#45;prev"-->
<!--rel="prev">-->
<!--<div class="md-flex__cell md-flex__cell&#45;&#45;shrink">-->
<!--<i class="md-icon md-icon&#45;&#45;arrow-back-->
<!--md-footer-nav__button"></i>-->
<!--</div>-->
<!--<div class="md-flex__cell md-flex__cell&#45;&#45;stretch-->
<!--md-footer-nav__title">-->
<!--<span class="md-flex__ellipsis">-->
<!--<span class="md-footer-nav__direction">-->
<!--{{ lang.t("footer.previous") }} -->
<!--</span>-->
<!--{{ page.previous_page.title }}-->
<!--</span>-->
<!--</div>-->
<!--</a>-->
<!--{% endif %}-->
<!-- -->
<!-- Link to next page -->
<!--{% if page.next_page %}-->
<!--<a href="{{ page.next_page.url }}" title="{{ page.next_page.title }}"-->
<!--class="md-flex md-footer-nav__link md-footer-nav__link&#45;&#45;next"-->
<!--rel="next">-->
<!--<div class="md-flex__cell md-flex__cell&#45;&#45;stretch-->
<!--md-footer-nav__title">-->
<!--<span class="md-flex__ellipsis">-->
<!--<span class="md-footer-nav__direction">-->
<!--{{ lang.t("footer.next") }}-->
<!--</span>-->
<!--{{ page.next_page.title }}-->
<!--</span>-->
<!--</div>-->
<!--<div class="md-flex__cell md-flex__cell&#45;&#45;shrink">-->
<!--<i class="md-icon md-icon&#45;&#45;arrow-forward-->
<!--md-footer-nav__button"></i>-->
<!--</div>-->
<!--</a>-->
<!--{% endif %}-->
<!--</nav>-->
<!--</div>-->
{% endif %}
<!-- Further information -->
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<!-- Copyright and theme information -->
<div class="md-footer-copyright">
{% if config.copyright %}
<div class="md-footer-copyright__highlight">
{{ config.copyright }}
</div>
{% endif %}
powered by
<a href="http://www.mkdocs.org" title="MkDocs">MkDocs</a>
and
<a href="http://squidfunk.github.io/mkdocs-material/"
title="Material for MkDocs">
Material for MkDocs</a>
</div>
<!-- Social links -->
{% block social %}
{% include "partials/social.html" %}
{% endblock %}
</div>
</div>
</footer>