From 8b003a0c47a62a9dcfb5bfed1b693ec33f45f713 Mon Sep 17 00:00:00 2001 From: ZzMzaw <89450172+ZzMzaw@users.noreply.github.com> Date: Sat, 28 May 2022 08:13:34 +0200 Subject: [PATCH] Add documentation for Let's encrypt DNS challenges Also listed all docker images introduced --- docs/configuring-playbook-ssl-certificates.md | 166 +++++++++++++++++- docs/container-images.md | 28 +++ 2 files changed, 192 insertions(+), 2 deletions(-) diff --git a/docs/configuring-playbook-ssl-certificates.md b/docs/configuring-playbook-ssl-certificates.md index 30a8f0b87..88b92242b 100644 --- a/docs/configuring-playbook-ssl-certificates.md +++ b/docs/configuring-playbook-ssl-certificates.md @@ -1,6 +1,6 @@ # Adjusting SSL certificate retrieval (optional, advanced) -By default, this playbook retrieves and auto-renews free SSL certificates from [Let's Encrypt](https://letsencrypt.org/) for the domains it needs (`matrix.` and possibly `element.`) +By default, this playbook retrieves and auto-renews free SSL certificates from [Let's Encrypt](https://letsencrypt.org/) for the domains it needs (`matrix.` and possibly others). Those certificates are used when configuring the nginx reverse proxy installed by this playbook. They can also be used for configuring [your own webserver](configuring-playbook-own-webserver.md), in case you're not using the integrated nginx server provided by the playbook. @@ -17,6 +17,7 @@ Things discussed in this document: - [Obtaining SSL certificates for additional domains](#obtaining-ssl-certificates-for-additional-domains), if you'd like to host additional domains on the Matrix server and would like the playbook to help you obtain and renew certificates for those domains automatically +- [Using DNS challenge to obtain Let's encrypt SSL certificates](#using-dns-challenge-to-obtain-lets-encrypt-ssl-certificates), if you'd like to host additional domains on the Matrix server and would like the playbook to help you obtain and renew certificates for those domains automatically ## Using self-signed SSL certificates @@ -102,7 +103,6 @@ For automated certificate renewal to work, each port `80` vhost for each domain See how this is configured for the `matrix.` subdomain in `/matrix/nginx-proxy/conf.d/matrix-synapse.conf` Don't be alarmed if the above configuration file says port `8080`, instead of port `80`. It's due to port mapping due to our use of containers. - ## Specify the SSL private key algorithm If you'd like to [specify the private key type](https://eff-certbot.readthedocs.io/en/stable/using.html#using-ecdsa-keys) used with Let's Encrypt, define your own custom configuration like this: @@ -110,3 +110,165 @@ If you'd like to [specify the private key type](https://eff-certbot.readthedocs. ```yaml matrix_ssl_lets_encrypt_key_type: ecdsa ``` + +## Using DNS challenge to obtain Let's encrypt SSL certificates + +Let's encrypt proposes different challenges prior delivering a certificate (https://letsencrypt.org/docs/challenge-types/). + +By default, this playbook uses HTTP challenges to request for Let's encrypt certificates. + +For some domains and in specific cases (e.g. no HTTP server on the matrix base domain), relying on a DNS challenge is the only possible solution. + +First of all, the domain to retrieve the certificate for must be in the list of domains to retrieve certificates for: `matrix_ssl_domains_to_obtain_certificates_for`. +Please see [Obtaining SSL certificates for additional domains](#obtaining-ssl-certificates-for-additional-domains) for more details about how to configure this list. + +### Configure the cerbot image to use + +In order to retrieve a certificate through DNS challenge, Cerbot must use a plugin adapted to the DNS provider which will answer to the challenge. + +By default, the playbook uses the main Cerbot image which has no plugins configured. + +To use an official Cerbot image with a plugin for DNS challenge, you must set `matrix_ssl_lets_encrypt_certbot_challenge_image` to 'dns' (default is 'http') and indicate the DNS plugin to use with `matrix_ssl_lets_encrypt_certbot_official_dns_provider`. + +```yaml +# In this example, we use the cerbot official with its plugin for doing DNS challenges using OVH. +matrix_ssl_lets_encrypt_certbot_challenge_image: 'dns' +matrix_ssl_lets_encrypt_certbot_official_dns_provider: 'ovh' +``` + +Supported DNS providers/methods are (https://eff-certbot.readthedocs.io/en/stable/using.html#dns-plugins): +- Cloudflare: `cloudflare` +- CloudXNS: `cloudxns` +- DigitalOcean: `digitalocean` +- DNS Made Easy: `dnsmadeeasy` +- DNSimple: `dnsimple` +- Gehirn: `gehirn` +- Google Cloud DNS: `google` +- Linode: `linode` +- LuaDNS: `luadns` +- NS1: `nsone` +- OVH: `ovh` +- RFC 2136 Dynamic Updates: `rfc2136` +- Amazon Route 53: `route53` +- Sakura Cloud: `sakuracloud` + +Some advanced users may need to use a custom certbot image to configure multiple DNS plugins. +To do so, you can set `matrix_ssl_lets_encrypt_certbot_challenge_image` to 'custom' and indicate which image to use with `matrix_ssl_lets_encrypt_certbot_custom_docker_image`. +This image must have similar behavior as cerbot official images for DNS plugins. + +```yaml +# For advanced users only +matrix_ssl_lets_encrypt_certbot_challenge_image: 'custom' +matrix_ssl_lets_encrypt_certbot_custom_docker_image: "{{ matrix_container_global_registry_prefix }}my-custom/image:v1.0.0" +``` + +### Prepare the configuration file for plugin authentication + +DNS plugins rely on configuration files which must be declared in an entry of `matrix_ssl_lets_encrypt_dns_config`. +Each entry must contain: +- a `name` which will be referenced by the domain (so that same configuration can be used for multiple domains) +- a `template` among those supported in the roles/matrix-nginx-proxy/templates/dns-config folder (without the .j2 extension) +- a list of the properties required by the plugin for authentication + +The properties to use are the named arguments listed in the cerbot plugin documentation, removing the leading double dashes ('--') and replacing other dashes ('-') by underscore ('_'): +- Cloudflare: https://certbot-dns-cloudflare.readthedocs.io/en/stable/# +- CloudXNS: https://certbot-dns-cloudxns.readthedocs.io/en/stable/# +- DigitalOcean: https://certbot-dns-digitalocean.readthedocs.io/en/stable/# +- DNS Made Easy: https://certbot-dns-dnsmadeeasy.readthedocs.io/en/stable/# +- DNSimple: https://certbot-dns-dnsimple.readthedocs.io/en/stable/# +- Gehirn: https://certbot-dns-gehirn.readthedocs.io/en/stable/# +- Google Cloud DNS: https://certbot-dns-google.readthedocs.io/en/stable/# +- Linode: https://certbot-dns-linode.readthedocs.io/en/stable/# +- LuaDNS: https://certbot-dns-luadns.readthedocs.io/en/stable/# +- NS1: https://certbot-dns-nsone.readthedocs.io/en/stable/# +- OVH: https://certbot-dns-ovh.readthedocs.io/en/stable/# +- RFC 2136 Dynamic Updates: https://certbot-dns-rfc2136.readthedocs.io/en/stable/# +- Amazon Route 53: https://certbot-dns-route53.readthedocs.io/en/stable/# +- Sakura Cloud: https://certbot-dns-sakuracloud.readthedocs.io/en/stable/# + +```yaml +# In this example, we use OVH official DNS cerbot plugin to create a 'myovh.ini' configuration file. +matrix_ssl_lets_encrypt_dns_config: + - name: 'myovh.ini' + template: 'ovh.ini' + dns_ovh_endpoint: 'ovh-eu' + dns_ovh_application_key: '{{ vault_ovh_application_key }}' + dns_ovh_application_secret: '{{ vault_ovh_application_secret }}' + dns_ovh_consumer_key: '{{ vault_ovh_consumer_key }}' +``` + +Beware that all generated configuration files will be mapped within all docker containers used for let's encrypt, whether they are needed or not!!! + +For using Route53 DNS plugin, a pre-hook script is used with cerbot in order to link ~/.aws/config to the relevant configuration file. + +### Declare which domain to use DNS challenge for + +Last but not least, the domain has to be configured with the provider to use in cerbot command and the name of a previously created configuration. + +Supported providers are: +- Cloudflare: `cloudflare` +- CloudXNS: `cloudxns` +- DigitalOcean: `digitalocean` +- DNS Made Easy: `dnsmadeeasy` +- DNSimple: `dnsimple` +- Gehirn: `gehirn` +- Google Cloud DNS: `google` +- Linode: `linode` +- LuaDNS: `luadns` +- NS1: `nsone` +- OVH: `ovh` +- RFC 2136 Dynamic Updates: `rfc2136` +- Amazon Route 53: `route53` +- Sakura Cloud: `sakuracloud` + +```yaml +# In this example, we use cerbot OVH command with the previously created 'myovh.ini' configuration. +matrix_ssl_lets_encrypt_dns_challenge_domains: + - domain: '{{ matrix_domain }}' + provider: 'ovh' + config_file: 'myovh.ini' +``` + +### Example configuration for base domain and OVH provider + +Complete example configuration to get certificate for the matrix domain with a DNS challenge to OVH DNS provider. + +```yaml +# In this example, we retrieve an extra certificate for +# the matrix base domain through DNS challenge to OVH DNS provider +# and we use it for the federation API. +# All other domains but the matrix base domain will use HTTP challenge. + +# Retrieve an extra certificate for +# the base domain (in the `matrix_domain` variable). +matrix_ssl_additional_domains_to_obtain_certificates_for: + - '{{ matrix_domain }}' + +# Use an image with the plugin for doing DNS challenges using OVH instead of the default one +# Other official images are supported by adapting the `matrix_ssl_lets_encrypt_certbot_official_dns_provider` variable. +matrix_ssl_lets_encrypt_certbot_challenge_image: 'dns' +matrix_ssl_lets_encrypt_certbot_official_dns_provider: 'ovh' + +# Provide configuration for DNS plugin +# Other configuration for official plugins are supported by adapting the `template` variable of a configuration. +matrix_ssl_lets_encrypt_dns_config: + - name: 'ovh.ini' + template: 'ovh.ini' + dns_ovh_endpoint: 'ovh-eu' + dns_ovh_application_key: '{{ vault_ovh_application_key }}' + dns_ovh_application_secret: '{{ vault_ovh_application_secret }}' + dns_ovh_consumer_key: '{{ vault_ovh_consumer_key }}' + +# Configure retrieval of certificate for the base domain +# through DNS challenge with previously created configuration. +matrix_ssl_lets_encrypt_dns_challenge_domains: + - domain: '{{ matrix_domain }}' + provider: 'ovh' + config_file: 'ovh.ini' + +# Configure the base domain certificate to be used +# by Federation API instead of the matrix domain one `matrix.{{ matrix_domain }}`. +matrix_nginx_proxy_proxy_matrix_federation_api_ssl_certificate: '/matrix/ssl/config/live/{{ matrix_domain }}/fullchain.pem' +matrix_nginx_proxy_proxy_matrix_federation_api_ssl_certificate_key: '/matrix/ssl/config/live/{{ matrix_domain }}/privkey.pem' + +``` diff --git a/docs/container-images.md b/docs/container-images.md index b16babff0..0fede308a 100644 --- a/docs/container-images.md +++ b/docs/container-images.md @@ -34,6 +34,34 @@ These services are not part of our default installation, but can be enabled by [ - [matrixdotorg/dendrite-monolith](https://hub.docker.com/r/matrixdotorg/dendrite-monolith/) - the [Dendrite](https://github.com/matrix-org/dendrite) Matrix homeserver (optional) +- [certbot/dns-cloudflare](https://hub.docker.com/r/certbot/dns-cloudflare/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using Cloudflare (optional) + +- [certbot/dns-cloudxns](https://hub.docker.com/r/certbot/dns-cloudxns/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using CloudXNS (optional) + +- [certbot/dns-digitalocean](https://hub.docker.com/r/certbot/dns-digitalocean/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using DigitalOcean (optional) + +- [certbot/dns-dnsmadeeasy](https://hub.docker.com/r/certbot/dns-dnsmadeeasy/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using DNS Made Easy (optional) + +- [certbot/dns-dnsimple](https://hub.docker.com/r/certbot/dns-dnsimple/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using DNSimple (optional) + +- [certbot/dns-gehirn](https://hub.docker.com/r/certbot/dns-gehirn/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using Gehirn (optional) + +- [certbot/dns-google](https://hub.docker.com/r/certbot/dns-google/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using Google Cloud DNS (optional) + +- [certbot/dns-linode](https://hub.docker.com/r/certbot/dns-linode/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using Linode (optional) + +- [certbot/dns-luadns](https://hub.docker.com/r/certbot/dns-luadns/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using LuaDNS (optional) + +- [certbot/dns-nsone](https://hub.docker.com/r/certbot/dns-nsone/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using NS1 (optional) + +- [certbot/dns-ovh](https://hub.docker.com/r/certbot/dns-ovh/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using OVH (optional) + +- [certbot/dns-rfc2136](https://hub.docker.com/r/certbot/dns-rfc2136/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using RFC 2136 Dynamic Updates (optional) + +- [certbot/dns-route53](https://hub.docker.com/r/certbot/dns-route53/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using Amazon Route 53 (optional) + +- [certbot/dns-sakuracloud](https://hub.docker.com/r/certbot/dns-sakuracloud/) - the [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) with its plugin for doing DNS challenges using Sakura Cloud (optional) + - [ewoutp/goofys](https://hub.docker.com/r/ewoutp/goofys/) - the [Goofys](https://github.com/kahing/goofys) Amazon [S3](https://aws.amazon.com/s3/) file-system-mounting program (optional) - [etherpad/etherpad](https://hub.docker.com/r/etherpad/etherpad/) - the [Etherpad](https://etherpad.org) realtime collaborative text editor that can be used in a Jitsi audio/video call or integrated as a widget into Matrix chat rooms via the Dimension integration manager (optional)