Follow these steps to get the add-on installed on your system:
- Navigate in your Home Assistant frontend to Settings -> Add-ons -> Add-on store.
- Find the "letsencrypt" add-on and click it.
- Click on the "INSTALL" button.
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.
- Requires Port 80 to be available from the internet and your domain assigned to the externally assigned IP address
- Doesn’t allow wildcard certificates (*.yourdomain.com).
- Requires you to use one of the supported DNS providers (See "Supported DNS providers" below)
- Allows to request wildcard certificates (*.yourdomain.com)
- Doesn’t need you to open a port to your Home Assistant host on your router.
Supported DNS providers
dns-azure
dns-cloudflare
dns-cloudns
dns-desec
dns-digitalocean
dns-directadmin
dns-dnsimple
dns-dnsmadeeasy
dns-duckdns
dns-dreamhost
dns-dynu
dns-gehirn
dns-google
dns-hetzner
dns-infomaniak
dns-joker
dns-linode
dns-luadns
dns-njalla
dns-noris
dns-simply
dns-nsone
dns-ovh
dns-rfc2136
dns-route53
dns-sakuracloud
dns-namecheap
dns-netcup
dns-gandi
dns-transip
dns-inwx
dns-porkbun
dns-easydns
dns-domainoffensive
dns-websupport
In addition add the fields according to the credentials required by your DNS provider:
propagation_seconds: 60
azure_config: ''
cloudflare_email: ''
cloudflare_api_key: ''
cloudflare_api_token: ''
cloudns_auth_id: ''
cloudns_sub_auth_id: ''
cloudns_sub_auth_user: ''
cloudns_auth_password: ''
desec_token: ''
digitalocean_token: ''
directadmin_url: ''
directadmin_username: ''
directadmin_password: ''
dnsimple_token: ''
dnsmadeeasy_api_key: ''
dnsmadeeasy_secret_key: ''
duckdns_token: ''
dynu_auth_token: ''
google_creds: ''
google_domains_access_token: ''
google_domains_zone: ''
hetzner_api_token: ''
gehirn_api_token: ''
gehirn_api_secret: ''
infomaniak_api_token: ''
joker_username: ''
joker_password: ''
joker_domain: ''
linode_key: ''
linode_version: ''
luadns_email: ''
luadns_token: ''
njalla_token: ''
noris_token: ''
nsone_api_key: ''
ovh_endpoint: ''
ovh_application_key: ''
ovh_application_secret: ''
ovh_consumer_key: ''
rfc2136_server: ''
rfc2136_port: ''
rfc2136_name: ''
rfc2136_secret: ''
rfc2136_algorithm: ''
aws_access_key_id: ''
aws_secret_access_key: ''
sakuracloud_api_token: ''
sakuracloud_api_secret: ''
namecheap_username: ''
namecheap_api_key: ''
netcup_customer_id: ''
netcup_api_key: ''
netcup_api_password: ''
gandi_api_key: ''
gandi_token: ''
gandi_sharing_id: ''
transip_username: ''
transip_api_key: ''
inwx_username: ''
inwx_password: ''
inwx_shared_secret: ''
porkbun_key: ''
porkbun_secret: ''
dreamhost_api_baseurl: ''
dreamhost_api_key: ''
domainoffensive_token: ''
plesk_username: ''
plesk_password: ''
plesk_api_url: ''
simply_account_name: ''
simply_api_key: ''
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
:
# TLS with letsencrypt add-on
http:
server_port: 443
ssl_certificate: /ssl/fullchain.pem
ssl_key: /ssl/privkey.pem
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, and then restarting this automation every night via the Supervisor Addon restart action.
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.
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:
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:
acme_server: 'https://my.custom-acme-server.com'
acme_root_ca_cert: |
-----BEGIN CERTIFICATE-----
MccBfTCCASugAwIBAgIRAPPIPTKNBXkBozsoE46UPZcwCGYIKoZIzj0EAwIwHTEb...kg==
-----END CERTIFICATE-----
Selecting the Key Type
By default the ECDSA key type is used. You can choose to use an RSA key for compatibility with systems where ECDSA keys are not supported. ECDSA is widely supported in modern software with security and performance benefits.
key_type: 'rsa'
When the key_type
parameter is not set, the add-on will attempt to auto-detect an existing certificate's key type or use ecdsa
by default.
Selecting the ECDSA Elliptic Curve
You can choose from the following ECDSA elliptic curves: secp256r1
, secp384r1
key_type: 'ecdsa'
elliptic_curve: 'secp384r1'
When the elliptic_curve
parameter is not set, ECDSA keys will be generated using the Certbot default. This option must be used with key_type
set to 'ecdsa'
.
Set up external account binding
The ACME protocol (RFC 8555) defines an external account binding (EAB) field that ACME clients can use to access a specific account on the certificate authority (CA). Some CAs may require the client to utilize the EAB protocol to operate. You can add your EAB key ID and HMAC key through the config options eab_kid
and eab_hmac_key
.
eab_kid: 'key_id'
eab_hmac_key: 'AABBCCDD' #Base64url encoded key
Note: These configuration examples are raw YAML configs. When you use UI edit mode (default), and configure DNS, simply copy the attributes underneath dns into the DNS Provider configuration field.
HTTP challenge
email: [email protected]
domains:
- home-assistant.io
certfile: fullchain.pem
keyfile: privkey.pem
challenge: http
dns: {}
DNS challenge
email: [email protected]
domains:
- home-assistant.io
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-cloudflare
cloudflare_email: [email protected]
cloudflare_api_key: 31242lk3j4ljlfdwsjf0
RSA key
email: [email protected]
domains:
- home-assistant.io
certfile: fullchain.pem
keyfile: privkey.pem
key_type: rsa
challenge: dns
dns:
provider: dns-cloudflare
cloudflare_email: [email protected]
cloudflare_api_key: 31242lk3j4ljlfdwsjf0
Azure DNS challenge
email: [email protected]
domains:
- home-assistant.io
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-azure
azure_config: azure.txt
Please copy your credentials file "azure.txt" 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. You can find information on the required file format in the documentation for the Certbot Azure plugin.
To use this plugin, create an Azure Active Directory app registration and service principal; add a client secret; and create a credentials file using the above directions. Grant the app registration DNS Zone Contributor on the DNS zone to be used for authentication.
Google Cloud DNS challenge
email: [email protected]
domains:
- home-assistant.io
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-google
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.
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:
Google Domains DNS challenge
email: [email protected]
domains:
- subdomain.home-assistant.io
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-google-domains
google_domains_access_token: XXXX
google_domains_zone: home-assistant.io
To obtain the ACME DNS API token follow the instructions here:
https://support.google.com/domains/answer/7630973#acme_dns
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.
Infomaniak DNS challenge
email: [email protected]
domains:
- subdomain.home-assistant.io
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-infomaniak
infomaniak_api_token: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
To obtain the DNS API token follow the instructions here:
https://manager.infomaniak.com/v3/infomaniak-api
Choose "Domain" as the scope.
Joker DNS challenge
email: [email protected]
domains:
- subdomain.example.com
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-joker
joker_username: username
joker_password: password
joker_domain: example.com
You can find further detailed information here:
https://joker.com/faq/books/jokercom-faq-en/page/lets-encrypt-ssl-certificates https://github.com/dhull/certbot-dns-joker/blob/master/README.md
route53 DNS challenge
email: [email protected]
domains:
- home-assistant.io
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-route53
aws_access_key_id: 0123456789ABCDEF0123
aws_secret_access_key: 0123456789abcdef0123456789/abcdef0123456
For security reasons, don't use your main account's credentials. Instead, add a new AWS user with Access Type: Programmatic access and use that user's access key. Assign a minimum policy 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.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ChangeSpecificDomainsRecordSet",
"Effect": "Allow",
"Action": "route53:ChangeResourceRecordSets",
"Resource": "arn:aws:route53:::hostedzone/01234567890ABC"
},
{
"Sid": "ListAllHostedZones",
"Effect": "Allow",
"Action": "route53:ListHostedZones",
"Resource": "*"
},
{
"Sid": "ReadChanges",
"Effect": "Allow",
"Action": "route53:GetChange",
"Resource": "arn:aws:route53:::change/*"
}
]
}
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.
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):
dns:
provider: dns-cloudflare
cloudflare_api_token: 0123456789abcdef0123456789abcdef01234
Example credentials file using Global API Key (not recommended):
dns:
provider: dns-cloudflare
cloudflare_email: [email protected]
cloudflare_api_key: 0123456789abcdef0123456789abcdef01234
Linode
To use this addon with Linode DNS, first create a new API/access key, 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).
email: [email protected]
domains:
- ha.yourdomain.com
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-linode
linode_key: 865c9f462c7d54abc1ad2dbf79c938bc5c55575fdaa097ead2178ee68365ab3e
linode_version: '4'
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.
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.
Example configuration:
email: [email protected]
domains:
- your.domain.tld
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
propagation_seconds: 60
provider: dns-directadmin
directadmin_url: 'https://domain.tld:2222/'
directadmin_username: da_user
directadmin_password: da_password_or_key
Namecheap
To use this addon with Namecheap, you must first enable API access on your account. See "Enabling API Access" and "Whitelisting IP" here for details and requirements.
Example configuration:
email: [email protected]
domains:
- ha.yourdomain.com
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-namecheap
namecheap_username: your-namecheap-username
namecheap_api_key: 0123456789abcdef0123456789abcdef01234567
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.
Example configuration:
email: [email protected]
domains:
- home-assistant.io
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-njalla
njalla_token: 0123456789abcdef0123456789abcdef01234567
TransIP
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.
Example configuration:
email: [email protected]
domains:
- your.domain.tld
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-transip
transip_username: transip-user
transip_api_key: |
-----BEGIN PRIVATE KEY-----
MII..ABCDEFGHIJKLMNOPQRSTUVWXYZ
AAAAAABCDEFGHIJKLMNOPQRSTUVWXYZ
-----END PRIVATE KEY-----
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).
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
email: [email protected]
domains:
- home-assistant.io
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-ovh
ovh_endpoint: ovh-eu
ovh_application_key: 0123456789abcdef0123456789abcdef01234
ovh_application_secret: 0123456789abcdef0123456789abcdef01234
ovh_consumer_key: 0123456789abcdef0123456789abcdef01234
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
$ tsig-keygen -a hmac-sha512 letsencrypt
key "letsencrypt" {
algorithm hmac-sha512;
secret "G/adDW8hh7FDlZq5ZDW3JjpU/I7DzzU1PDvp26DvPQWMLg/LfM2apEOejbfdp5BXu78v/ruWbFvSK5dwYY7bIw==";
};
You don't need to publish this; just copy the key data into your named.conf file:
key "letsencrypt" {
algorithm hmac-sha512;
secret "G/adDW8hh7FDlZq5ZDW3JjpU/I7DzzU1PDvp26DvPQWMLg/LfM2apEOejbfdp5BXu78v/ruWbFvSK5dwYY7bIw==";
};
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 {
grant letsencrypt name _acme-challenge.home-assistant.io. txt;
};
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:
email: [email protected]
domains:
- home-assistant.io
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-rfc2136
rfc2136_server: dns-server.dom.ain
rfc2136_port: '53'
rfc2136_name: letsencrypt
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.
Example configuration:
email: [email protected]
domains:
- your.domain.tld
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-inwx
inwx_username: user
inwx_password: password
inwx_shared_secret: ABCDEFGHIJKLMNOPQRSTUVWXYZ012345
Porkbun
In order to use a domain with this challenge, API access will need enabling on the domain. In order to do this go to domain management -> select the domain -> details and click the API access toggle. Then go to the menu in the top right select API access and then create a new api key. The title does not matter and is not used by certbot, make note of the key and the secret as both are required.
email: [email protected]
domains:
- your.domain.tld
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-porkbun
porkbun_key: 0123456789abcdef0123456789abcdef01234
porkbun_secret: 0123456789abcdef0123456789abcdef01234
Dreamhost
email: [email protected]
domains:
- your.domain.tld
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-dreamhost
dreamhost_baseurl: https://api.dreamhost.com/
dreamhost_api_key: XXXXXX
ClouDNS
In order to use a domain with this challenge, you first need to log into your control panel and create a new HTTP API user from the "API & Resellers" page on top of your control panel.email: [email protected]
domains:
- your.domain.tld
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-cloudns
cloudns_auth_id: 12345
cloudns_auth_password: ******
API Users have full account access. It is recommended to create an API Sub-user, which can be limited in scope. You can use either the sub-auth-id
or the sub-auth-user
as follows:
email: [email protected]
domains:
- your.domain.tld
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-cloudns
cloudns_sub_auth_id: 12345
cloudns_auth_password: ******
email: [email protected]
domains:
- your.domain.tld
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-cloudns
cloudns_sub_auth_user: alice
cloudns_auth_password: ******
Hurricane Electric (HE)
email: [email protected]
domains:
- your.domain.tld
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-he
he_user: me
he_pass: ******
Netcup
Both the API password and key can be obtained via the following page: https://www.customercontrolpanel.de/daten_aendern.php?sprung=api It is important to set the propagation_seconds to >= 630 seconds due to the slow DNS update of Netcup.
email: [email protected]
domains:
- your.domain.tld
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-netcup
netcup_customer_id: "userid"
netcup_api_key: ****
netcup_api_password: ****
propagation_seconds: "900"
References:
easyDNS
easyDNS REST API access must be requested and granted in order to use this module: https://cp.easydns.com/manage/security/api/signup.php after logging into your account.
email: [email protected]
domains:
- your.domain.tld
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-easydns
easydns_token: 0123456789abcdef
easydns_key: ****
easydns_endpoint: https://rest.easydns.net
Dynu
You can get the API key in the API Credentials area of the Dynu control panel: https://www.dynu.com/ControlPanel/APICredentials
email: [email protected]
domains:
- your.domain.tld
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-dynu
dynu_auth_token: 0123456789abcdef
WebSupport
An identifier and secret key have to be obtained to use this module (see https://admin.websupport.sk/sk/auth/apiKey).
email: [email protected]
domains:
- your.domain.tld
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-websupport
websupport_identifier: <identifier>
websupport_secret_key: <secret_key>
domainoffensive
email: [email protected]
domains:
- your.domain.tld
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-domainoffensive
domainoffensive_token: *****
noris network DNS challenge
email: [email protected]
domains:
- your.domain.tld
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-noris
noris_token: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
propagation_seconds: 240
To obtain the noris_token
follow the instructions as described in our GitHub repository.
You can define the propagation_seconds
explicitly. Otherwise, it will use the default value (currently set to 60
seconds).
Plesk Hosting DNS challenge
email: [email protected]
domains:
- your.domain.tld
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-plesk
plesk_username: your-username
plesk_password: your-password
plesk_api_url: https://plesk.example.com
propagation_seconds: 120
The plesk_username
and plesk_password
are the same as those you use on the login page of your admin panel.
The plesk_api_url
is the base URL of your Plesk admin panel.
You can define the propagation_seconds
explicitly. Otherwise, it will use a custom default value (currently set to 120
seconds). If the provided value is less than 120
, then the value is forced to a minimum of 120
seconds.
Simply.com DNS challenge
email: [email protected]
domains:
- your.domain.tld
certfile: fullchain.pem
keyfile: privkey.pem
challenge: dns
dns:
provider: dns-simply
simply_account_name: Sxxxxxx
simply_api_key: YOUR_API_KEY # Replace 'YOUR_API_KEY' with your actual Simply.com API key.
The simply_account_name
refers to the Simply.com account number (Sxxxxxx), and the simply_api_key
is the account's API key.
The API key assigned to your Simply.com account can be found in your Simply.com Control panel.
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.
dns-azure
dns-cloudns
dns-cloudflare
dns-desec
dns-digitalocean
dns-directadmin
dns-dnsimple
dns-dnsmadeeasy
dns-duckdns
dns-dreamhost
dns-dynu
dns-gehirn
dns-google
dns-hetzner
dns-infomaniak
dns-linode
dns-luadns
dns-njalla
dns-noris
dns-plesk
dns-simply
dns-nsone
dns-ovh
dns-rfc2136
dns-route53
dns-sakuracloud
dns-namecheap
dns-netcup
dns-gandi
dns-transip
dns-inwx
dns-porkbun
dns-easydns
dns-domainoffensive
dns-websupport
Got questions?
You have several options to get them answered:
- The Home Assistant Discord Chat Server.
- The Home Assistant Community Forum.
- Join the Reddit subreddit in /r/homeassistant
- Check out certbots page certbot.
In case you've found a bug, please open an issue on our GitHub.