Effortless encryption with Let's Encrypt and DuckDNS


When Let’s Encrypt launched we were estatic: finally an easy and free way for our users to securely access their homes remotely. Let’s Encrypt signifianctly lowered the bar to get and renew SSL certificates. However, this process could still be quite an obstacle for our users. It required opening ports on the router and remembering to renew the certificate every so often.

Thanks to a blog post by Andreas Gohr I realized that DuckDNS supports setting TXT records, making it compatible with the DNS-01 challenge of Let’s Encrypt. The DNS-01 challenge is using the DNS record of the domain instead of interacting with the server. This means that it’s not needed for the user to open any ports!

I have worked together with Pascal Vizeli on updating the DuckDNS add-on for Hass.io and today we’re proud to announce it now includes automatic generation and updating of Let’s Encrypt certificates for your DuckDNS domain. The only thing that you have to add to your DuckDNS configuration is that you accept the Let’s Encrypt terms of service and point Home Assistant at the generated certificates and you’re good to go. No other work is required.

To get started today, start with making sure that you have Hass.io installed. After that, go to the Hass.io panel in Home Assistant, open the add-on store, scroll down to DuckDNS and install it. In the DuckDNS settings change “accept_terms” to true and start it.

Next up is to configure Home Assistant with the config below and restart it. You’re now good to go! Make sure to use the right protocol when browsing to your instance: https://<your_domain>.duckdns.org. Happy secure controlling your house!

# Example configuration.yaml entry for the HTTP component
  ssl_certificate: /ssl/fullchain.pem
  ssl_key: /ssl/privkey.pem

If you’re not using Hass.io, check out the blog post by Andreas for instructions.

If you enjoy the free service provided by DuckDNS and Let’s Encrypt, consider donating to their cause:

More information:

This is a companion discussion topic for the original entry at https://home-assistant.io/blog/2017/09/27/effortless-encryption-with-lets-encrypt-and-duckdns/

DuckDNS and Letsencrypt - Not encrypted!

I have followed the above instructions but am receiving the error below and can not start the addon

this is what is in my options:
“lets_encrypt”: {
“accept_terms”: true,
“certfile”: “fullchain.pem”,
“keyfile”: “privkey.pem”
“token”: null,
“domains”: [
“seconds”: 300

And this is the error I get:

not a valid value for dictionary value @ data[‘options’]. Got {‘lets_encrypt’: {‘accept_terms’: True, ‘certfile’: ‘fullchain.pem’, ‘keyfile’: ‘privkey.pem’}, ‘token’: None, ‘domains’: [None], ‘seconds’: 300}


You don’t have the correct value for domains. Check the docs


Did you get this solved? If so how? I get that it seems to be missing domains, but how is that created?


Like @balloob said, follow the docs and insert the token and domain you generate at DuckDNS.org, @Matthew_Noecker just left them as ”null”.


I had duckdns setup and had configured letsencrypt. It worked but I’m not a big fan of duckdns. No real control of my DNS name. So I looked for a better option. Google domains. Not free only 12 dollars a year but they support the dyndns protocol so you can use your own domain name for accessing your network. You can create subsites and forwards. You can also use the DNS txt records to get a letsencrypt SSL certificate as well. To me the 12 dollars is well worth it!


That sounds slick - any chance you could do a more detailed write up?


I actually used this article to setup SSL on my OMV NAS and then scripted utilities to convert & push the certificate to my LEDE router, Emby and a few other things I wanted to use with SSL.


Okay - thanks. I was just in doubt of whether to do anything on duckdns first or that also was a part of the add-on. Reading only the blog suggested the latter.

Do I still need to do some port forwarding or is it only opening ports that is not needed (or is those two the same)?


Yep, if you have ‘base_url:’ with the port number on the end you’ll need to forward 8123 to 8123 on your pi, if you have just the duckDNS address with no port it’s 443 to 8123.


Sure, Just fyi… im not the best at explaining step by step but here we go… its really simple first go to https://domains.google.com and setup your domain that you want. Then once you log in you with click on the dns icon…

Then scroll down to synthetic records and choose the dynamic dns setting from the dropdown…

This will allow you to create a subdomain… so like homeassistant.yourdomain.com

Once that is created you will get a generated username and password. These will be used to setup the dyndns service on your home router.

As long as your router support the dyndns service you will choose that and then for the server address you will enter in domains.google.com then use the username and password from your custom domain subsite…

After this is setup and working you then can use any of letsencrypts online tool to verify the domain. I used https://www.sslforfree.com/ you want to add your main domain yourdomain.com and any subsite… homeassistant.yourdomain.com to the list of sites you want included in the ssl certificate. Then you can use the option to verify the domain by dns txt record. The site will pretty much walk you through what to do. Once you get the dns txt record you will add this to the custom resource records on your google domain. Dont worry about the TTL googles default is 1h but it takes less than that to verify. After that you can copy the cert and key txt into a seperate txt doc and save it as a pem file for home assistant. After you do that you just need to copy those files to the correct location and you should be able to get up and running. You can use the same cert for any other systems you have running on your network as long as the site and subsites are in there.


I have installed duckdns and configured it according t the instructions here and other places.

It basically works for me using ssl/htps everywhere but on the iOS home assistant app. When using the app I get an invalid certificate message and the app refuses to connect. I have imported the full chain.pem file to my iPhone and allowed it to be used for SSL, but the app still fails to connect and shows the same error.

Is there anyone else out there with this problem? Is there anyone out there with a working iOS app using duckdns and SSL? If so, did you do anything special to make it work?

Thank you.



Thanks for the above guide. I followed the steps and was able to get the cert files. You mentioned about the correct location of the file. Does it need to be in specific location?

Also there were 3 cert files, which one are we to use?

I get error that HA can’t access pem files in config folder.

Please help


My HA PI is hard lined into my Google WiFi router but I also have an ISP modem which external ip address am I supposed to use my ISP? Or the Google WiFi


I am hoping to find a poiner to why I can’t get SSL to work.
I have a static IP and my own domain.
Installed the LetsEncrypt addon.
Setup NAT from MyStaticIP:447->hassio:8123 (that is not a typo, 443 is in use)
https://hasio.local:8123 works correctly
SSLChecker says the certificates are valid and tcpdump shows the cert being passed when a request comes in on https://MyDomain.com:447
But if I go to https://MyDomain.com:447 from outside my network, I always get:

   Home Assistant had trouble
   connecting to the server.

Which must be coming from something running on the Pi. I’ve tried a number of things in the http section of the config file. Currently it looks like:

  ssl_certificate: /ssl/fullchain.pem
  ssl_key: /ssl/privkey.pem
  # server_port: 8123
  # Secrets are defined in the file secrets.yaml
  api_password: !secret http_password
  # Uncomment this if you are using SSL/TLS, running in Docker container, etc.
  # base_url: example.duckdns.org:8123
  base_url: https://MyDomain.com:447

How do I get past this?.


My let’s encrypt is using 443 and from outside my lan, it just use https://domain_name.com, without port number.


443 is in use on that address so I’m using 447


You’ve only got one external IP address but you don’t need it to set this up, that’s what duckdns looks after for you.


I run my own DNS servers and have static IP addresses - No DuckDNS here.

The problem appears to be that Home Assistant is not quite correct in it’s html and this causes lynx to fail. I was using lynx to test so that I could see how things work from an out of state machine.

I’ll try to file a bug on this.

The whole objective was to get Google Assistant to work and it still fails.


i changed the default location of my cert files… the one you need is the key and the chain file. As soon as i added those to the folder i specified in my configuration file it picked up and everything worked fine. You added the root and sub domain name when you created your cert right? So prefix.domain.com and domain.com that should allow the cert to work.