HTTPS for Home Assistant with DuckDNS and dnsmasq

Andrea Leandri
5 days ago
4 min read

Skill level: Beginner to Intermediate | Time to complete: 45-60 minutes

What you'll build: Secure HTTPS access to Home Assistant from anywhere using a free DuckDNS subdomain and a free Let's Encrypt SSL certificate, plus a dnsmasq configuration that makes the same URL work seamlessly from inside your home network too.

Why You Need This

By default, Home Assistant is accessible only on your local network at something like http://192.168.x.XX:8123. That means the Companion App cannot reach your instance when away from home, Alexa and Jarvis cannot call back to HA via webhooks, and any integration that needs HA reachable from the internet simply will not work.

This guide gives you a permanent free hostname (yourname.duckdns.org) that always points to your home IP, a free auto-renewing SSL certificate, working HTTPS on port 8123 (the approach when your ISP blocks port 443 - common with Dutch residential fiber including Glasoperator), and a local DNS override so the DuckDNS URL also works from inside your home network.

How It All Fits Together

From outside your home: your phone types yourname.duckdns.org:8123, DuckDNS resolves it to your home public IP, your router forwards port 8123 to HA Green, HA serves the page over HTTPS using the Let's Encrypt certificate.

From inside your home: dnsmasq on your router intercepts the DNS query and returns the local IP (192.168.X.XX) directly, so the connection goes straight to HA Green without leaving the house. Without this, many routers block the hairpin NAT pattern and the connection fails or is slow.

Part 1: Create a DuckDNS Account and Subdomain

Go to duckdns.org and sign in with Google or GitHub (completely free, no credit card). Choose a subdomain name - something like yourname-home or myhomeassistant - type it in the subdomain field and click Add Domain. Your full address will be yourname.duckdns.org.

Copy your token from the dashboard - a long string of letters and numbers. You will need it in Part 2.

Part 2: Install and Configure the DuckDNS Add-on

Settings -> Add-ons -> Add-on Store -> search DuckDNS. Install the DuckDNS add-on by the Home Assistant team. In the Configuration tab:

lets_encrypt:
  accept_terms: true
  certfile: fullchain.pem
  keyfile: privkey.pem
token: YOUR_DUCKDNS_TOKEN_HERE
domains:
  - yourname.duckdns.org
hours: 24
seconds: 300

Start the add-on, enable Start on boot and Watchdog. Check the Log tab - you should see Your certificate and chain have been saved at: /ssl/fullchain.pem. This confirms Let's Encrypt issued your certificate successfully.

If the certificate request fails: Let's Encrypt needs port 80 open briefly for domain validation. Add a temporary port 80 forwarding rule on your router pointing to HA Green, restart the add-on, then remove the rule once the cert is issued.

Part 3: Set Up Port Forwarding on Your Router

Log into your router (usually http://192.168.X.1). For a Zyxel EX5601-T1 (my modem): Advanced -> NAT -> Port Forwarding -> Add.

Name: HA HTTPS | Protocol: TCP | External port: 8123 | Internal IP: 192.168.X.XX (your HA Green's local IP) | Internal port: 8123

Save and apply. Then test external access: on your phone with WiFi off (so on 4G or 5G), open https://yourname.duckdns.org:8123. You should see the HA login page with a padlock icon. If you do, the certificate is working and port forwarding is correct.

Why port 8123 and not 443? Glasoperator and many Dutch ISPs block inbound port 443 on residential lines. Port 8123 works fine - the connection is still fully encrypted HTTPS regardless of port number.

Part 4: Update configuration.yaml for HTTPS

Open File Editor - /config/configuration.yaml and add (or extend if already existing) these blocks:

http:
  ssl_certificate: /ssl/fullchain.pem
  ssl_key: /ssl/privkey.pem
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1
    - ::1

homeassistant:
  external_url: "https://yourname.duckdns.org:8123"

Save, run Developer Tools -> YAML -> Check Configuration, then do a full HA restart. HTTPS configuration requires a full restart, not just a config reload.

Part 5: Fix Local Access with dnsmasq

Without this step, your DuckDNS URL may work from outside but fail from inside your home - many routers do not support hairpin NAT (connecting to your own public IP from inside the network). dnsmasq fixes this at the DNS level.

Option A: dnsmasq via your router (recommended)

On Zyxel routers look for: Advanced -> DNS -> Local DNS Records (may also be called Static DNS, Custom DNS Entries, or DNS Override). Add an entry: Hostname = yourname.duckdns.org, IP Address = 192.168.X.XX. Save. All devices on your network will now resolve the DuckDNS hostname to your local HA Green IP directly.

Option B: dnsmasq as an HA add-on

If your router does not support custom DNS entries, install the dnsmasq add-on from the HA add-on store. Configure it:

defaults:
  - 8.8.8.8
  - 8.8.4.4
hosts:
  - host: yourname.duckdns.org
    ip: 192.168.X.XX

Start it and enable Start on boot. Then in your router DHCP settings, set Primary DNS Server to 192.168.X.XX so all devices use dnsmasq for DNS resolution.

Note: if HA Green goes offline, DNS resolution for your whole network will fail until it comes back. Keep the watchdog enabled.

Part 6: Update the HA Companion App

Companion App - Settings - App Configuration - Home Assistant URL. Set External URL to https://yourname.duckdns.org:8123. With dnsmasq in place you can use the same DuckDNS URL for both local and external, since it now resolves correctly from inside the network too.

What This Unlocks

When you will step into more advanced integration an SSL connection is a must and probably the only one supported. You will see it coming back in the following posts if you are interested in applying them:

Jarvis AI Voice Assistant: Haaska requires HA reachable externally for Alexa account linking
Presence Detection: Companion App needs external access to report location when away from home
WhatsApp Notifications: the WhatsApp add-on calls back to HA via webhooks

Troubleshooting

Certificate request fails: Temporarily open port 80 forwarding to HA Green, restart the add-on, remove the rule after cert is issued.
External access times out: Check port forwarding rule is saved and active. Some Zyxel routers need a firewall rule in addition to port forwarding.
Works externally but not from home WiFi: dnsmasq entry is missing or not active. Confirm entry was saved and flush DNS on your device.
Browser shows certificate warning: Let's Encrypt cert did not issue. Check DuckDNS add-on log for errors.
HA will not start after adding http: block: YAML syntax error. Run Check Configuration before restarting. Check for duplicate http: blocks or indentation errors.

Guide written by a Home Assistant enthusiast in Utrecht. The combination of DuckDNS, Let's Encrypt, and dnsmasq is battle-tested on Glasoperator fiber - port 8123 works perfectly despite the ISP blocking 443.