From 89b0037ec10ce5cdaf73f7ee4993526c0bf42725 Mon Sep 17 00:00:00 2001 From: NicoMen Date: Fri, 25 Aug 2017 21:10:03 +0200 Subject: [PATCH] Improve Let's Encrypt documentation --- docs/user-guide/examples.md | 169 ++++++++++++++++++++++++++++++++++-- examples/traefik.crt | 36 ++++---- examples/traefik.key | 55 ++++++------ 3 files changed, 205 insertions(+), 55 deletions(-) diff --git a/docs/user-guide/examples.md b/docs/user-guide/examples.md index f58828fe6..8089a8ec4 100644 --- a/docs/user-guide/examples.md +++ b/docs/user-guide/examples.md @@ -44,25 +44,23 @@ defaultEntryPoints = ["http", "https"] address = ":443" [entryPoints.https.tls] [[entryPoints.https.tls.certificates]] - certFile = "tests/traefik.crt" - keyFile = "tests/traefik.key" + CertFile = "examples/traefik.crt" + KeyFile = "examples/traefik.key" ``` ## Let's Encrypt support +### Basic example + ```toml [entryPoints] [entryPoints.https] address = ":443" [entryPoints.https.tls] - # certs used as default certs - [[entryPoints.https.tls.certificates]] - certFile = "tests/traefik.crt" - keyFile = "tests/traefik.key" + [acme] email = "test@traefik.io" -storageFile = "acme.json" -onDemand = true +storage = "acme.json" caServer = "http://172.18.0.1:4000/directory" entryPoint = "https" @@ -78,6 +76,161 @@ entryPoint = "https" main = "local4.com" ``` +This configuration allows generating Let's Encrypt certificates for the four domains `local[1-4].com` with described SANs. +Traefik generates these certificates when it starts and it needs to be restart if new domains are added. + +### OnHostRule option + +```toml +[entryPoints] + [entryPoints.https] + address = ":443" + [entryPoints.https.tls] + +[acme] +email = "test@traefik.io" +storage = "acme.json" +onHostRule = true +caServer = "http://172.18.0.1:4000/directory" +entryPoint = "https" + +[[acme.domains]] + main = "local1.com" + sans = ["test1.local1.com", "test2.local1.com"] +[[acme.domains]] + main = "local2.com" + sans = ["test1.local2.com", "test2x.local2.com"] +[[acme.domains]] + main = "local3.com" +[[acme.domains]] + main = "local4.com" +``` + +This configuration allows generating Let's Encrypt certificates for the four domains `local[1-4].com`. +Traefik generates these certificates when it starts. + +If a backend is added with a `onHost` rule, Traefik will automatically generate the Let's Encrypt certificate for the new domain. + +### OnDemand option + +```toml +[entryPoints] + [entryPoints.https] + address = ":443" + [entryPoints.https.tls] + +[acme] +email = "test@traefik.io" +storage = "acme.json" +OnDemand = true +caServer = "http://172.18.0.1:4000/directory" +entryPoint = "https" + +``` + +This configuration allows generating a Let's Encrypt certificate during the first HTTPS request on a new domain. + +**Note** : This option simplifies the configuration but : +* TLS handshakes will be slow when requesting a hostname certificate for the first time, this can leads to DDoS attacks. +* Let's Encrypt have rate limiting: https://letsencrypt.org/docs/rate-limits +That's why, it's better to use the `onHostRule` optin if possible. + +### DNS challenge + +```toml +[entryPoints] + [entryPoints.https] + address = ":443" + [entryPoints.https.tls] + +[acme] +email = "test@traefik.io" +storage = "acme.json" +dnsProvider = "digitalocean" # DNS Provider name (cloudflare, OVH, gandi...) +delayDontCheckDNS = 0 +caServer = "http://172.18.0.1:4000/directory" +entryPoint = "https" + +[[acme.domains]] + main = "local1.com" + sans = ["test1.local1.com", "test2.local1.com"] +[[acme.domains]] + main = "local2.com" + sans = ["test1.local2.com", "test2x.local2.com"] +[[acme.domains]] + main = "local3.com" +[[acme.domains]] + main = "local4.com" +``` + +DNS challenge needs environment variables to be executed. This variables have to be set on the machine/container which host Traefik. +These variables has described [in this section](toml/#acme-lets-encrypt-configuration). + +### OnHostRule option and provided certificates + +```toml +[entryPoints] + [entryPoints.https] + address = ":443" + [entryPoints.https.tls] + [[entryPoints.https.tls.certificates]] + CertFile = "examples/traefik.crt" + KeyFile = "examples/traefik.key" + +[acme] +email = "test@traefik.io" +storage = "acme.json" +onHostRule = true +caServer = "http://172.18.0.1:4000/directory" +entryPoint = "https" + +``` + +Traefik will only try to generate a Let's encrypt certificate if the domain cannot be checked by the provided certificates. + +### Cluster mode + +#### Prerequisites + +Before to use Let's Encrypt in a Traefik cluster, take a look to [the key-value store explanations](/user-guide/kv-config) and more precisely to [this section](/user-guide/kv-config/#store-configuration-in-key-value-store) in the way to know how to migrate from a acme local storage *(acme.json file)* to a key-value store configuration. + +#### Configuration + +```toml +[entryPoints] + [entryPoints.https] + address = ":443" + [entryPoints.https.tls] + +[acme] +email = "test@traefik.io" +storage = "traefik/acme/account" +caServer = "http://172.18.0.1:4000/directory" +entryPoint = "https" + +[[acme.domains]] + main = "local1.com" + sans = ["test1.local1.com", "test2.local1.com"] +[[acme.domains]] + main = "local2.com" + sans = ["test1.local2.com", "test2x.local2.com"] +[[acme.domains]] + main = "local3.com" +[[acme.domains]] + main = "local4.com" + +[consul] + endpoint = "127.0.0.1:8500" + watch = true + prefix = "traefik" + +``` + +This configuration allows to use the key `traefik/acme/account` to get/set Let's Encrypt certificates content. +The `consul` provider contains the configuration. + +**Note** : It's possible to use others key-value store providers as described [here](/user-guide/kv-config/#key-value-store-configuration). + ## Override entrypoints in frontends ```toml diff --git a/examples/traefik.crt b/examples/traefik.crt index 71921f742..fe1c90f5f 100644 --- a/examples/traefik.crt +++ b/examples/traefik.crt @@ -1,21 +1,19 @@ -----BEGIN CERTIFICATE----- -MIIDXTCCAkWgAwIBAgIJAPPVb4fq4kkvMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV -BAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEwHwYDVQQKDBhJbnRlcm5ldCBX -aWRnaXRzIFB0eSBMdGQwHhcNMTUxMDE5MTk0MTU4WhcNMTYxMDE4MTk0MTU4WjBF -MQswCQYDVQQGEwJBVTETMBEGA1UECAwKU29tZS1TdGF0ZTEhMB8GA1UECgwYSW50 -ZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB -CgKCAQEAsPnpfnUPbQxSu3oq38OaX/Q6LKZ5gnS04F8kREF2RvCDMWiKOWru+hXb -udkwU7Fx+7BcDBGsnJGFpY23dDcRurxF1DVs1jIFukH/vbYyHE8JQEgvOGSpDEiv -rfbcxqK8E/VMrI10eXYGxWzaTFWQOND2PAJ1b5JvZrrzc8rfJ7h5Q24GKnw1999t -hwsZgpUOh9te7fz1M4XxxRRoliMg0oH9EV3P9Yqq635tjWOix8PcnpcqnRKXVDhk -TcNtE+45RsPoSgM6nkiXt8HP4afaVUAGAzF41kDm94SNexcyk7gyVsLs2cEI61Eu -mhvpP3z91md+eAa3If7kU1w70WiY1wIDAQABo1AwTjAdBgNVHQ4EFgQUue6v2TkZ -1oR0ZzEnnxfKdsGuBPMwHwYDVR0jBBgwFoAUue6v2TkZ1oR0ZzEnnxfKdsGuBPMw -DAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEAk+xxO8gC40R7+5WVtWvA -+chNsOoxKyFBOPvGzrYGQbt4OBWKrwQmMXSY3VnjY4GzVaZpOCJOxnupKfZrK4AP -G+M+NI+J6fHJRCQdov7Xoje5M14FmgjRiLg+haDZhh//11C7P6MQPAzGNUTpUyqV -Hsi/wwCYvre5bApb/4uDkDlZkLrgN4e1q8+gh6XLj8NPEOEBEI4VpMVoieC1PwnK -pRfNlTsEhyjeMmOllw9fBKMEvEf1BKsJGaKmQ7zCr1nWznCxyI1Fuf66TfmL8/up -lK6sQysLEOIgn2gZEjQz4O/9Jj9v8+TvyP4GZIDsCiv33AaeKJVuSkoeCH0Ls2V8 -aQ== +MIIDHDCCAgQCCQDODsC1A72mSDANBgkqhkiG9w0BAQsFADBQMQswCQYDVQQGEwJG +UjELMAkGA1UECAwCTVAxDTALBgNVBAcMBFRsc2UxEzARBgNVBAoMCkNvbnRhaW5v +dXMxEDAOBgNVBAsMB1RyYWVmaWswHhcNMTcwODI1MTQxMzU3WhcNMjcwODIzMTQx +MzU3WjBQMQswCQYDVQQGEwJGUjELMAkGA1UECAwCTVAxDTALBgNVBAcMBFRsc2Ux +EzARBgNVBAoMCkNvbnRhaW5vdXMxEDAOBgNVBAsMB1RyYWVmaWswggEiMA0GCSqG +SIb3DQEBAQUAA4IBDwAwggEKAoIBAQCacKEL5+AlaArZWyfysY1qbtOWdGj0xwq1 +tZ6GZ0fb+0uVeKzJxPBulpwhmXiofUncvFOpr1paaQQRRgE71A6PSIzc64a3NGmm +dbju3eOdFVm9za37asFTA2Y87v9HSYJyNSeQgdVCbykhHBrHPrP6kfPx8T7uiPRT +cYWhL9Ko1IuW2rTjMt2UUmk1IPk2WFMWKM1mopqzrxu/NB+O5wOs7MRO1Z8BtAak +bclxCQaaE0TgjChlxVPP0us77rCq3///i9kf1x0PGt/LyseaxzAoKfZ6kM6Uq0yk +psWGSxu7sPXmERsN4tZLj7d/J5A2nvnO7h/bhl2FtBAauzsi3LIbAgMBAAEwDQYJ +KoZIhvcNAQELBQADggEBACQbp2gcCFbbQE47SwdI7rWDIITylHj0uCXHJfUggkUl +F/WHIBUdpVaWVOLSysmG8n6fmWTDZOCVNA1+XMjRZUPwVvr//XHjcFpOKfHW47r2 +VeMHQYQpZH7QmsjyvxXZOrz/Ft3uA9Dna1N5nHRYflpfasdRmXbNK81IykR93Dfn +jV9ecDAQl0ru/YcMmabYx3uoWyTvO57EnbXfiPcwIdKGpykXKTv64vAMtkrJicgX +jhh+p7ayKklfxinEL7/GCjfSBip7J4DszvLVoyIzmS7HjVdJkpu9agZLYsSl4tCJ +qnh7nkp/Fd0XdTV17FwL/veMlpq9AkillIKjHl6vFL0= -----END CERTIFICATE----- diff --git a/examples/traefik.key b/examples/traefik.key index c19826d90..95e6425a0 100644 --- a/examples/traefik.key +++ b/examples/traefik.key @@ -1,28 +1,27 @@ ------BEGIN PRIVATE KEY----- -MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCw+el+dQ9tDFK7 -eirfw5pf9DospnmCdLTgXyREQXZG8IMxaIo5au76Fdu52TBTsXH7sFwMEayckYWl -jbd0NxG6vEXUNWzWMgW6Qf+9tjIcTwlASC84ZKkMSK+t9tzGorwT9UysjXR5dgbF -bNpMVZA40PY8AnVvkm9muvNzyt8nuHlDbgYqfDX3322HCxmClQ6H217t/PUzhfHF -FGiWIyDSgf0RXc/1iqrrfm2NY6LHw9yelyqdEpdUOGRNw20T7jlGw+hKAzqeSJe3 -wc/hp9pVQAYDMXjWQOb3hI17FzKTuDJWwuzZwQjrUS6aG+k/fP3WZ354Brch/uRT -XDvRaJjXAgMBAAECggEAHvnvO5ojtBOXG4d7n6TuDWODFzOgSwxAaJFemK/Ykvwg -CnLg1sH3yEAxMGtqgQurBsHMqrQhQVpbSSnv9WB6MvQnSMh9H1SsGfjZWYxdYwUW -enDoCvfbevHyBgISjJYJU3j5Da7It0XIU6AE6Z2EW91/a+uGQJwh8ZpBaIAW5S2j -B3k+bASANtwEcDdhGE7iLYeHiAttZo89oSSFZP/mwh84pIU29zUVUtsUaHXrob0p -iyGXKPa8NqTvIsbX5Kh/lbbCO4KwsOqgs/eqL7cLSv2VfTmSQCJz+ikiVzcw/vJU -PaT9H4SCBLP73/Gyjf5P14esWvprPQ3ZnWNNDDGWsQKBgQDoWqxQUy6PKY9or7QH -M985y52Y0QlWdmRaLc8gxfWLU4/3Wn0NH1flkFXJ5X9uZFNoGMQpidJBajepzkNO -/54V+1NCLUWl7SE5gMeFG8QtEE7ISyjut71CUDSn5mOp7EBARmqRpMZhmXT42RZi -1zVDkG08ArKdH0Jnvkq5lWHGbwKBgQDC/IYJXkd27XZO+Ti8TdzaU+SSJV26aY++ -0N4pzq0cC6IWadHugH/XrgkfH+ImPzkf6XHrCSqSipJJLZMd473/8IjdOsf54wDP -/yHKPXWhfC4W2L+6+l34Jo/ebnuDVvDme1nKLcdmxhwz4YZfg/TYbWaFzANrl3St -beGg9ENIGQKBgBr6/GtPXWauUsK7NFJpyY/yfthR3Z22nayDCTwrAHovN9ZnIYI2 -k4RKoEuTZJqy96Rsy8pvAIUsCk6jbtlrgTXYOzDCBQZhZKxCsehY8wywihVj9NrT -ZxyeJ58fd48xqbxM8O78jTSkFxsWSi0sBDlWOfjv70GjcZiOVir6l6HtAoGBAJeA -MAENcQeV4AviltOwx/4Xmwx23gmeRaMklMn1HQoie9FgbU4cJ7kEL3AwjL3c99y0 -vN+7Ion0A0+6iol5z8ISObVzG7gsShBSkwWZlVFgtErqJKb6K5NJGxXf0DYvkkPy -6cQup7VSDs282HRUiiSzdCpXZvztFCpAq0QtJi3ZAoGACjtJ7zEVs0hB7+sCq/SI -UHjjv/fjGSm1TVDP46Joqbm62FRdYkEhd+pGMjtGs80OhM+psTZIqe/fgKdKl5yX -nS9m6f4ny6XCcilfI3+bxXtsmWnpQnybSU2goe2n+Eoi3RcEB68Hp8U0aPjgDULM -9YDU/ZMupHh/eT79n67QIXw= ------END PRIVATE KEY----- +-----BEGIN RSA PRIVATE KEY----- +MIIEpAIBAAKCAQEAmnChC+fgJWgK2Vsn8rGNam7TlnRo9McKtbWehmdH2/tLlXis +ycTwbpacIZl4qH1J3LxTqa9aWmkEEUYBO9QOj0iM3OuGtzRppnW47t3jnRVZvc2t ++2rBUwNmPO7/R0mCcjUnkIHVQm8pIRwaxz6z+pHz8fE+7oj0U3GFoS/SqNSLltq0 +4zLdlFJpNSD5NlhTFijNZqKas68bvzQfjucDrOzETtWfAbQGpG3JcQkGmhNE4Iwo +ZcVTz9LrO+6wqt///4vZH9cdDxrfy8rHmscwKCn2epDOlKtMpKbFhksbu7D15hEb +DeLWS4+3fyeQNp75zu4f24ZdhbQQGrs7ItyyGwIDAQABAoIBAQCYFpBSJC/1Rmdg +s0c81iMYjDlsMgll/FmMpmWNoEoA1ZESintGW94WWdU5tWRAMNm7Oe797ISDAmYS +CKmQXH1WFzE5IexRoJjmZ4oOGY9cEzmEE/fg3rmxYWieWxIkBr0icTwcL+9u8/9B +7uZkDli5SmA8g8HgsBhD0Eizel/vB5DyUtm8VoVYvDkkljYO/PGT/ectclr6JK9g +biP4jkA2a3CTb8KeyBTrYbULWCtwZ7H5fmySXIX4QpJmEcx5Af7nYITU0OEK63uV +NKCQLDpHyOrDIj+mwjxASBQdUDU7NApCR2MrzmGDRPPCGiEWYao5bCrsNRAoDFuy +Ux2H+jnRAoGBAM2nOcjJ7nKmOEUTyB0J9ElJRBoChBJAF3ak/aj4xDYAz/hadQL0 +OuulOgmYwHjv7Y5Tx6P5ZQgyComa6rKfNZ/mzgm1wMPsKOi5q5T2Zj/0Pt6xih3x ++PxonLiIS7221U5xlBZUyW1LLIM4gT7NS9n2pxBuNESotmSwFnPru4OzAoGBAMA/ +vyXAnOTRi1on8TDItdPDgq13s0I+q+Fj4+KVCEifRiT9P9NRKQNfvRZI39QGmJ+x +kGx6VY96SZo5ysm4ElkcKLJ7EcZ38XehG9rar6ZLEAgY4KnA4wDZWmJ1dUm4ZJZI +Sj2EFmb30V1FP/qo9TFro5Je6P0m9TjFeLKwF4P5AoGAKIu0x9KQMYh2BaB9zsPc +pupMA/jFAzghqCGlZUAOpzsHxcZH1ZpDV5xO0f+Myws6wdngvYJ5GeGL1E93wFnF +X85Ihv+PjtEry553prnhtPA5yPwl5/uCBHm3lGZC0JeQfJPGB5UV1XeBwilMyg39 +y25mx8WChprgwv84ngg3AyMCgYEAlb2RPvCFw9xK9FAEFwFeTrELyd1gLIrwCcBq +MYPvTdFxK0JuQkQG8+/QMdlVLaptmoUNftDSb8zKI2w8PV44PFwofsxJDhNCavF7 +5r1K7vWsaQIni1EH/xNMyT+/uUn8XumzmbKWWGFSG5niuXR8dp/mag2u3+9GNY/p +8RQjXNECgYAnA7rQ7UVayRQUL8NKB0jhP/J0UomrJRXYx+J5UP7QIoObXlTbDVSi +VTAiSrhPQIFa1s8ghUgCghwq6KJsZoQzrp1fLLlV/HIN+4XXhYVAmOI/k41rCj/0 +eYTkXlXyFpcaW3h9vVjT1wN9FwbU1kNpFo/PvDLM/SQB7GhFRznDDw== +-----END RSA PRIVATE KEY-----