From 46accfdb3c53f0a6b9e5fd7aacf9adaf21172ebc Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Fri, 8 Feb 2019 11:59:00 +0200 Subject: [PATCH] Add guide about certificates for other domains We had something like that on the Server Delegation how-to page, but it's better if we have it on the SSL certificates page. Relocated there and improved linking. Fixes #94 (Github Issue) --- docs/configuring-playbook-ssl-certificates.md | 48 ++++++++++++++++++- docs/howto-server-delegation.md | 16 ++----- 2 files changed, 49 insertions(+), 15 deletions(-) diff --git a/docs/configuring-playbook-ssl-certificates.md b/docs/configuring-playbook-ssl-certificates.md index 5c8161faf..d7673738c 100644 --- a/docs/configuring-playbook-ssl-certificates.md +++ b/docs/configuring-playbook-ssl-certificates.md @@ -1,10 +1,21 @@ # Adjusting SSL certificate retrieval (optional, advanced) -By default, this playbook retrieves and auto-renews free SSL certificates from [Let's Encrypt](https://letsencrypt.org/). +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 `riot.`) Those certificates are used when configuring the nginx reverse proxy installed by this playbook. +They can also be used for configuring [your own webserver](docs/configuring-playbook-own-webserver.md), in case you're not using the integrated nginx server provided by the playbook. -If that's alright, you can skip this. +If you need to retrieve certificates for other domains (e.g. your base domain) or more control over certificate retrieval, read below. + +Things discussed in this document: + +- [Using self-signed SSL certificates](#using-self-signed-ssl-certificates), if you can't use Let's Encrypt or just need a test setup + +- [Using your own SSL certificates](#using-your-own-ssl-certificates), if you don't want to or can't use Let's Encrypt certificates, but are still interested in using the integrated nginx reverse proxy server + +- [Not bothering with SSL certificates](#not-bothering-with-ssl-certificates), if you're using [your own webserver](docs/configuring-playbook-own-webserver.md) and would rather this playbook leaves SSL certificate management to you + +- [Obtaining SSL certificates for additional domains](#obtaining-ssl-certificates-for-additional-domains), if you'd like to host additional domains on the Matrix server (perhaps your base domain?) and would like the playbook to help you obtain and renew certificates for those domains automatically. ## Using self-signed SSL certificates @@ -43,3 +54,36 @@ matrix_ssl_retrieval_method: none ``` With such a configuration, no certificates will be retrieved at all. You're free to manage them however you want. + + +## Obtaining SSL certificates for additional domains + +The playbook tries to be smart about the certificates it will obtain for you. + +By default, it obtains certificates for `matrix.` and possibly for `riot.` (unless you have disabled the Riot component using `matrix_riot_web_enabled: false`). + +If you are hosting other domains on the Matrix machine, you can make the playbook obtain and renew certificates for those other domains too. +To do that, simply define your own custom configuration like this: + +```yaml +# Note: we need to include the matrix (`hostname_matrix`) and riot (`hostname_riot`) domains explicitly. +# Your base domain is in the `hostname_identity` variable. +# Adding any other additional domains (hosted on the same machine) is possible. +matrix_ssl_domains_to_obtain_certificates_for: + - '{{ hostname_matrix }}' + - '{{ hostname_riot }}' + - '{{ hostname_identity }}' +``` + +After redefining `matrix_ssl_domains_to_obtain_certificates_for`, to actually obtain certificates you should: + +- make sure the web server occupying port 80 is stopped. If you are using matrix-nginx-proxy server (which is the default for this playbook), you need to stop it temporarily by running `systemctl stop matrix-nginx-proxy` on the server. + +- re-run the SSL part of the playbook and restart all services: `ansible-playbook -i inventory/hosts setup.yml --tags=setup-ssl,start` + +The certificate files would be available in `/matrix/ssl/config/live//...`. + +For automated certificate renewal to work, each port `80` vhost for each domain you are obtaining certificates for needs to forward requests for `/.well-known/acme-challenge` to the certbot container we use for renewal. + +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 configuraiton file says port `8080`, instead of port `80`. It's due to port mapping due to our use of containers. diff --git a/docs/howto-server-delegation.md b/docs/howto-server-delegation.md index aa9b0f95d..ef0c0faac 100644 --- a/docs/howto-server-delegation.md +++ b/docs/howto-server-delegation.md @@ -54,20 +54,10 @@ To use DNS SRV record validation, you need to: How you can obtain a valid certificate for `` on the `matrix.` server is up to you. -If `` and `matrix.` is the same machine, you can let the playbook obtain the certificate for you by redefining the `matrix_ssl_domains_to_obtain_certificates_for` variable. Example: +If `` and `matrix.` are hosted on the same machine, you can let the playbook obtain the certificate for you, by following our [Obtaining SSL certificates for additional domains](configuring-playbook-ssl-certificates.md#obtaining-ssl-certificates-for-additional-domains) guide. -```yaml -matrix_ssl_domains_to_obtain_certificates_for: - - '{{ hostname_matrix }}' - - '{{ hostname_riot }}' - - '{{ hostname_identity }}' -``` - -This way, the playbook would obtain certificates for your base domain as well (referred to by the `hostname_identity` variable). -The certificate files would be available in `/matrix/ssl/config/live//...`. - -If `` and `matrix.` are not the same machine, you can copy over the certificate files manually. -If they get renewed automatically, you may also have to transfer them periodically. How often you do that is up to you, as long as the certificate files don't expire. +If `` and `matrix.` are not hosted on the same machine, you can copy over the certificate files manually. +Don't forget that they may get renewed once in a while, so you may also have to transfer them periodically. How often you do that is up to you, as long as the certificate files don't expire. ### Serving the Federation API with your certificates