From 96d37f410857a650f23747bde70549e5c592880e Mon Sep 17 00:00:00 2001 From: Roland Wolters Date: Fri, 5 Jan 2024 19:20:21 +0100 Subject: [PATCH] letsencrypt: document UI configuration, automation, cert usage (#3299) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: add UI configuration, automation, cert usage - Add information where to enter configuration at all - Rewrite configuration guide to be UI first - Add guide on how to renew certificates - Add details and example on how to use the certificates in the Home Assistance default installation - Resort DNS provider data: now all in one place and not spread, also long lists hidden behind details * fix: add summary to DNS details * feat: simplify automation creation steps, update dns list * fix typos * fix typo introduced when fixing typos * wrap long lines in new paragraphs --------- Co-authored-by: Jan Čermák --- letsencrypt/DOCS.md | 226 +++++++++++++++++++++++++++++--------------- 1 file changed, 150 insertions(+), 76 deletions(-) diff --git a/letsencrypt/DOCS.md b/letsencrypt/DOCS.md index b0ba9b74088..8f3f703cf51 100644 --- a/letsencrypt/DOCS.md +++ b/letsencrypt/DOCS.md @@ -10,7 +10,18 @@ Follow these steps to get the add-on installed on your system: ## How to use -To use this add-on, you have two options on how to get your certificate: +The Letsencrypt add-on can be configured via the add-on interface. +The configuration via YAML is also possible, see the examples below. + +Navigate in your Home Assistant frontend to the add-ons overview page at +**Settings** -> **Add-ons**, and pick the **Let's Encrypt** add-on. On the top, +pick the **Configuration** page. + +Provide the domain names to issue certificates for. Additionally, provide the +e-mail address used for the registration, and path values for **Priv Key File** +and **Certificate File**. + +There are two options to obtain certificates. ### 1. HTTP challenge @@ -23,26 +34,44 @@ To use this add-on, you have two options on how to get your certificate: - Allows to request wildcard certificates (*.yourdomain.com) - Doesn’t need you to open a port to your Home Assistant host on your router. -### You always need to provide the following entries within the configuration +### DNS providers -```yaml -email: your@email.com -domains: - # use "*.yourdomain.com" for wildcard certificates. - - yourdomain.com -challenge: http OR dns -``` - -IF you choose `dns` as `challenge`, you will also need to fill: +
+ Supported DNS providerss -```yaml -# Add the dnsprovider of your choice from the list of "Supported DNS providers" below -dns: - provider: "" +```txt +dns-azure +dns-cloudflare +dns-desec +dns-digitalocean +dns-directadmin +dns-dnsimple +dns-dnsmadeeasy +dns-duckdns +dns-dreamhost +dns-gehirn +dns-google +dns-hetzner +dns-infomaniak +dns-linode +dns-luadns +dns-njalla +dns-nsone +dns-ovh +dns-rfc2136 +dns-route53 +dns-sakuracloud +dns-namecheap +dns-netcup +dns-gandi +dns-transip +dns-inwx +dns-porkbun ``` +
-In addition add the fields according to the credentials required by your DNS provider: - +
+ In addition add the fields according to the credentials required by your DNS provider: ```yaml propagation_seconds: 60 @@ -102,19 +131,65 @@ porkbun_secret: '' dreamhost_api_baseurl: '' dreamhost_api_key: '' ``` +
+ +### Configure certificate files + +The certificate files will be available within the "ssl" share after successful +request of the certificates. + +By default other addons are referring to the correct path of the certificates. +You can in addition find the files via the "samba" addon within the "ssl" share. + +For example, to use the certificates provided by this add-on to enable TLS on +Home Assistant in the default paths, add the following lines to Home +Assistant's main configuration file, `configuration.yaml`: + +```yaml +# TLS with letsencrypt add-on +http: + server_port: 443 + ssl_certificate: /ssl/fullchain.pem + ssl_key: /ssl/privkey.pem +``` + +### Create & renew certificates + +The letsencrypt add-on creates the certificates once it is started: navigate +to **Settings** -> **Add-ons**, pick the **Let's Encrypt** add-on, click the +**START** button on the bottom. The add-on stops once the certificates are +created. + +Certificates are not renewed automatically by the plugin. The add-on has to be +started again to renew certificates. If the add-on is started again, it checks +if the certificates are due for renewal. This is usually the case 30 days +before the certificates' due date. If the certificates are not due for renewal, +the add-on terminates without changes. If the certificates are due for renewal, +new certificates will be created. + +There are multiple ways how the add-on can be started to check/renew the +certificates. One way to automate the certificate renewal it to configure a +renewal via [Home Assistant automation][haauto], and then restarting this +automation every night via the [Supervisor Addon restart action][supervisorrestart]. + +[haauto]: https://www.home-assistant.io/docs/automation/editor/ +[supervisorrestart]: https://www.home-assistant.io/integrations/hassio/#service-hassioaddon_restart + +In this example, the automation will run every day at the chosen time, checking +if a renewal is due, and will request it if needed. ## Advanced
Changing the ACME Server - By default, The addon uses Let’s Encrypt’s default server at https://acme-v02.api.letsencrypt.org/. You can instruct the addon to use a different ACME server by providing the field `acme_server` with the URL of the server’s ACME directory: +By default, The addon uses Let’s Encrypt’s default server at https://acme-v02.api.letsencrypt.org/. You can instruct the addon to use a different ACME server by providing the field `acme_server` with the URL of the server’s ACME directory: ```yaml acme_server: 'https://my.custom-acme-server.com' ``` - If your custom ACME server uses a certificate signed by an untrusted certificate authority (CA), you can add the root certificate to the trust store by setting its content as an option: +If your custom ACME server uses a certificate signed by an untrusted certificate authority (CA), you can add the root certificate to the trust store by setting its content as an option: ```yaml acme_server: 'https://my.custom-acme-server.com' acme_root_ca_cert: | @@ -127,14 +202,13 @@ dreamhost_api_key: ''
Changing the key type - - Starting with Certbot version 2.0.0 (add-on version 5.0.0 and newer), ECDSA keys are now the default. These keys utilize a more secure cryptography algorithm, however, they are not supported everywhere yet. For instance, Tasmota does not support MQTTS with an ECDSA key. If your use case does not support ECDSA keys, you can change them with the `keytype` parameter. + +Starting with Certbot version 2.0.0 (add-on version 5.0.0 and newer), ECDSA keys are now the default. These keys utilize a more secure cryptography algorithm, however, they are not supported everywhere yet. For instance, Tasmota does not support MQTTS with an ECDSA key. If your use case does not support ECDSA keys, you can change them with the `keytype` parameter. ```yaml keytype: rsa ``` - ## Example Configurations
@@ -235,14 +309,14 @@ on the DNS zone to be used for authentication. google_creds: google.json ``` - Please copy your credentials file "google.json" into the "share" shared folder on the Home Assistant host before starting the service. +Please copy your credentials file "google.json" into the "share" shared folder on the Home Assistant host before starting the service. - One way is to use the "Samba" add on to make the folder available via network or SSH Add-on. +One way is to use the "Samba" add on to make the folder available via network or SSH Add-on. - The credential file can be created and downloaded when creating the service user within the Google cloud. - You can find additional information regarding the required permissions in the "credentials" section here: +The credential file can be created and downloaded when creating the service user within the Google cloud. +You can find additional information regarding the required permissions in the "credentials" section here: - +
@@ -262,11 +336,11 @@ on the DNS zone to be used for authentication. google_domains_zone: home-assistant.io ``` - To obtain the ACME DNS API token follow the instructions here: +To obtain the ACME DNS API token follow the instructions here: - + - The optional `google_domains_zone` option specifies the domain name registered with Google Domains. If not specified, it is guessed based on the public suffix list. +The optional `google_domains_zone` option specifies the domain name registered with Google Domains. If not specified, it is guessed based on the public suffix list.
@@ -285,11 +359,11 @@ on the DNS zone to be used for authentication. infomaniak_api_token: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX ``` - To obtain the DNS API token follow the instructions here: +To obtain the DNS API token follow the instructions here: - + - Choose "Domain" as the scope. +Choose "Domain" as the scope.
@@ -309,7 +383,7 @@ on the DNS zone to be used for authentication. aws_secret_access_key: 0123456789abcdef0123456789/abcdef0123456 ``` - For security reasons, don't use your main account's credentials. Instead, add a new [AWS user](https://console.aws.amazon.com/iam/home?#/users) with _Access Type: Programmatic access_ and use that user's access key. Assign a minimum [policy](https://console.aws.amazon.com/iam/home?#/policies$new?step=edit) like the following example. Make sure to replace the Resource ARN in the first statement to your domain's hosted zone ARN or use _*_ for all. +For security reasons, don't use your main account's credentials. Instead, add a new [AWS user](https://console.aws.amazon.com/iam/home?#/users) with _Access Type: Programmatic access_ and use that user's access key. Assign a minimum [policy](https://console.aws.amazon.com/iam/home?#/policies$new?step=edit) like the following example. Make sure to replace the Resource ARN in the first statement to your domain's hosted zone ARN or use _*_ for all. ```json { @@ -342,19 +416,19 @@ on the DNS zone to be used for authentication.
CloudFlare - Previously, Cloudflare’s “Global API Key” was used for authentication, however this key can access the entire Cloudflare API for all domains in your account, meaning it could cause a lot of damage if leaked. +Previously, Cloudflare’s “Global API Key” was used for authentication, however this key can access the entire Cloudflare API for all domains in your account, meaning it could cause a lot of damage if leaked. - Cloudflare’s newer API Tokens can be restricted to specific domains and operations, and are therefore now the recommended authentication option. - The API Token used for Certbot requires only the `Zone:DNS:Edit` permission for the zone in which you want a certificate. +Cloudflare’s newer API Tokens can be restricted to specific domains and operations, and are therefore now the recommended authentication option. +The API Token used for Certbot requires only the `Zone:DNS:Edit` permission for the zone in which you want a certificate. - Example credentials file using restricted API Token (recommended): +Example credentials file using restricted API Token (recommended): ```yaml dns: provider: dns-cloudflare cloudflare_api_token: 0123456789abcdef0123456789abcdef01234 ``` - Example credentials file using Global API Key (not recommended): +Example credentials file using Global API Key (not recommended): ```yaml dns: provider: dns-cloudflare @@ -367,7 +441,7 @@ on the DNS zone to be used for authentication.
Linode - To use this addon with Linode DNS, first [create a new API/access key](https://www.linode.com/docs/platform/api/getting-started-with-the-linode-api#get-an-access-token), with read/write permissions to DNS; no other permissions are needed. Newly keys will likely use API version '4.' **Important**: single quotes are required around the `linode_version` number; failure to do this will cause a type error (as the addon expects a string, not an integer). +To use this addon with Linode DNS, first [create a new API/access key](https://www.linode.com/docs/platform/api/getting-started-with-the-linode-api#get-an-access-token), with read/write permissions to DNS; no other permissions are needed. Newly keys will likely use API version '4.' **Important**: single quotes are required around the `linode_version` number; failure to do this will cause a type error (as the addon expects a string, not an integer). ```yaml email: you@mailprovider.com @@ -387,17 +461,17 @@ on the DNS zone to be used for authentication.
DirectAdmin - It is recommended to create a login key in the DirectAdmin control panel to be used as value for directadmin_password. - Instructions on how to create such key can be found at https://help.directadmin.com/item.php?id=523. +It is recommended to create a login key in the DirectAdmin control panel to be used as value for directadmin_password. +Instructions on how to create such key can be found at https://help.directadmin.com/item.php?id=523. - Make sure to grant the following permissions: - - `CMD_API_LOGIN_TEST` - - `CMD_API_DNS_CONTROL` - - `CMD_API_SHOW_DOMAINS` +Make sure to grant the following permissions: +- `CMD_API_LOGIN_TEST` +- `CMD_API_DNS_CONTROL` +- `CMD_API_SHOW_DOMAINS` - Username and password can also be used in case your DirectAdmin instance has no support for login keys. +Username and password can also be used in case your DirectAdmin instance has no support for login keys. - Example configuration: +Example configuration: ```yaml email: mail@domain.tld domains: @@ -418,9 +492,9 @@ on the DNS zone to be used for authentication.
Namecheap - To use this addon with Namecheap, you must first enable API access on your account. See "Enabling API Access" and "Whitelisting IP" [here](https://www.namecheap.com/support/api/intro/) for details and requirements. +To use this addon with Namecheap, you must first enable API access on your account. See "Enabling API Access" and "Whitelisting IP" [here](https://www.namecheap.com/support/api/intro/) for details and requirements. - Example configuration: +Example configuration: ```yaml email: your.email@example.com @@ -440,9 +514,9 @@ on the DNS zone to be used for authentication.
Njalla - You need to generate an API token inside Settings > API Access or directly at https://njal.la/settings/api/. If you have a static IP-address restrict the access to your IP. I you are not sure, you probably don't have a static IP-address. +You need to generate an API token inside Settings > API Access or directly at https://njal.la/settings/api/. If you have a static IP-address restrict the access to your IP. I you are not sure, you probably don't have a static IP-address. - Example configuration: +Example configuration: ```yaml email: your.email@example.com @@ -461,11 +535,11 @@ on the DNS zone to be used for authentication.
TransIP - You will need to generate an API key from the TransIP Control Panel at https://www.transip.nl/cp/account/api/. +You will need to generate an API key from the TransIP Control Panel at https://www.transip.nl/cp/account/api/. - The propagation limit will be automatically raised to 240 seconds. +The propagation limit will be automatically raised to 240 seconds. - Example configuration: +Example configuration: ```yaml email: your.email@example.com domains: @@ -488,15 +562,15 @@ on the DNS zone to be used for authentication.
OVH - You will need to generate an OVH API Key first at https://eu.api.ovh.com/createToken/ (for Europe) or https://ca.api.ovh.com/createToken/ (for north America). +You will need to generate an OVH API Key first at https://eu.api.ovh.com/createToken/ (for Europe) or https://ca.api.ovh.com/createToken/ (for north America). - When creating the API Key, you must ensure that the following rights are granted: - * ``GET /domain/zone/*`` - * ``PUT /domain/zone/*`` - * ``POST /domain/zone/*`` - * ``DELETE /domain/zone/*`` +When creating the API Key, you must ensure that the following rights are granted: +* ``GET /domain/zone/*`` +* ``PUT /domain/zone/*`` +* ``POST /domain/zone/*`` +* ``DELETE /domain/zone/*`` - Example configuration +Example configuration ```yaml email: your.email@example.com domains: @@ -511,15 +585,15 @@ on the DNS zone to be used for authentication. ovh_application_secret: 0123456789abcdef0123456789abcdef01234 ovh_consumer_key: 0123456789abcdef0123456789abcdef01234 ``` - Use `ovh_endpoint: ovh-ca` for north America region. +Use `ovh_endpoint: ovh-ca` for north America region.
RFC2136 - You will need to set up a server with RFC2136 (Dynamic Update) support with a TKEY (to authenticate the updates). How to do this will vary depending on the DNS server software in use. For Bind9, you first need to first generate an authentication key by running - +You will need to set up a server with RFC2136 (Dynamic Update) support with a TKEY (to authenticate the updates). How to do this will vary depending on the DNS server software in use. For Bind9, you first need to first generate an authentication key by running + ``` $ tsig-keygen -a hmac-sha512 letsencrypt key "letsencrypt" { @@ -527,8 +601,8 @@ on the DNS zone to be used for authentication. secret "G/adDW8hh7FDlZq5ZDW3JjpU/I7DzzU1PDvp26DvPQWMLg/LfM2apEOejbfdp5BXu78v/ruWbFvSK5dwYY7bIw=="; }; ``` - - You don't need to publish this; just copy the key data into your named.conf file: + +You don't need to publish this; just copy the key data into your named.conf file: ``` key "letsencrypt" { @@ -537,7 +611,7 @@ on the DNS zone to be used for authentication. }; ``` - And ensure you have an update policy in place in the zone that uses this key to enable update of the correct domain (which must match the domain in your yaml configuration): +And ensure you have an update policy in place in the zone that uses this key to enable update of the correct domain (which must match the domain in your yaml configuration): ``` update-policy { @@ -545,9 +619,9 @@ on the DNS zone to be used for authentication. }; ``` - For this provider, you will need to supply all the `rfc2136_*` options. Note that the `rfc2136_port` item is required (there is no default port in the add-on) and, most importantly, the port number must be quoted. Also, be sure to copy in the key so certbot can authenticate to the DNS server. Finally, the algorithm should be in all caps. +For this provider, you will need to supply all the `rfc2136_*` options. Note that the `rfc2136_port` item is required (there is no default port in the add-on) and, most importantly, the port number must be quoted. Also, be sure to copy in the key so certbot can authenticate to the DNS server. Finally, the algorithm should be in all caps. - An example configuration: +An example configuration: ```yaml email: your.email@example.com @@ -564,18 +638,18 @@ on the DNS zone to be used for authentication. rfc2136_secret: "secret-key" rfc2136_algorithm: HMAC-SHA512 ``` - +
INWX - Use the user for the dyndns service, not the normal user. - The shared secret is the 2FA code, it must be the same length as the example. - To get this code, you must activate the 2FA or deactivate and reactivate 2FA. - Without 2FA leave the example key. +Use the user for the dyndns service, not the normal user. +The shared secret is the 2FA code, it must be the same length as the example. +To get this code, you must activate the 2FA or deactivate and reactivate 2FA. +Without 2FA leave the example key. - Example configuration: +Example configuration: ```yaml email: your.email@example.com domains: