Skip to content

DOCS.md

Latest commit

 

History

History
159 lines (107 loc) · 6.04 KB

DOCS.md

File metadata and controls

159 lines (107 loc) · 6.04 KB
Raw

Home Assistant App: DuckDNS

Installation

Follow these steps to get the app (formerly known as add-on) installed on your system:

  1. In Home Assistant, go to Settings > Apps > Install app.
  2. Find the "DuckDNS" app and click it.
  3. Click on the "INSTALL" button.

How to use

  1. Visit DuckDNS.org and create an account by logging in through any of the available account services (Google, Github, Twitter, Persona, Reddit).
  2. In the Domains section, type the name of the subdomain you wish to register and click add domain.
  3. If registration was a success, the subdomain is listed in the Domains section along with current ip being the public IP address of the device you are currently using to access duckdns.org. The IP address will be updated by the DuckDNS app.
  4. In the DuckDNS app configuration, perform the following:
    • Copy the DuckDNS token (listed at the top of the page where account details are displayed) from duckdns.org and paste into the token option.
    • Update the domains option with the full domain name you registered. E.g., my-domain.duckdns.org.

Configuration

App configuration:

lets_encrypt:
  accept_terms: true
  certfile: fullchain.pem
  keyfile: privkey.pem
token: sdfj-2131023-dslfjsd-12321
domains:
  - my-domain.duckdns.org
aliases: []
seconds: 300

Additionally, you'll need to configure the Home Assistant Core to pick up the SSL certificates. This is done by setting the following configuration for the HTTP integration configuration in your configuration.yaml:

http:
  ssl_certificate: /ssl/fullchain.pem
  ssl_key: /ssl/privkey.pem

Option group lets_encrypt

The following options are for the option group: lets_encrypt. These settings only apply to Let's Encrypt SSL certificates.

Option lets_encrypt.accept_terms

Once you have read and accepted the Let's Encrypt Subscriber Agreement, change value to true in order to use Let's Encrypt services.

Option lets_encrypt.certfile

The name of the certificate file generated by Let's Encrypt. The file is used for SSL by Home Assistant apps and is recommended to keep the filename as-is (fullchain.pem) for compatibility.

Note: The file is stored in /ssl/, which is the default for Home Assistant

Option lets_encrypt.keyfile

The name of the private key file generated by Let's Encrypt. The private key file is used for SSL by Home Assistant apps and is recommended to keep the filename as-is (privkey.pem) for compatibility.

Note: The file is stored in /ssl/, which is the default for Home Assistant

Option lets_encrypt.algo

Public key algorithm that will be used.

Supported values: rsa, prime256v1 and secp384r1.

The default is secp384r1

Option: ipv4 (optional)

By default, Duck DNS will auto detect your IPv4 address and use that. This option allows you to override the auto-detection and specify an IPv4 address manually.

If you specify a URL here, contents of the resource it points to will be fetched and used as the address. This enables getting the address using a service like https://api.ipify.org/ or https://ipv4.text.wtfismyip.com

Option: ipv6 (optional)

By default, Duck DNS will auto detect your IPv6 address and use that. This option allows you to override the auto-detection and specify an IPv6 address manually.

If you specify a URL here, contents of the resource it points to will be fetched and used as the address. This enables getting the address using a service like https://api6.ipify.org/ or https://ipv6.text.wtfismyip.com

Option: token

The DuckDNS authentication token found at the top of the DuckDNS account landing page. The token is required to make any changes to the subdomains registered to your account.

Option: domains

A list of DuckDNS subdomains registered under your account. An acceptable naming convention is my-domain.duckdns.org. Wildcard certificates can also be issued by using the syntax *.my-domain.duckdns.org > my-domain.duckdns.org.

Option: aliases (optional)

A list aliases of domains configured on the domains option. This is useful in cases where you would like to use your own domain. Create a CNAME record to point at the DuckDNS subdomain and set this value accordingly. It is recommended to set the TTL value on your CNAME to a low value, typically under 60.

For example:

domains:
  - my-domain.duckdns.org
aliases:
  - domain: ha.my-domain.com
    alias: my-domain.duckdns.org

Don't add your custom domain name to the domains array. For certificate creation, all unique domains and aliases are used.

Also, don't forget to make sure the dns-01 challenge can reach Duckdns. It might be required to add a specific CNAME for that:

CNAME _acme-challenge.<own-domain>    _acme-challenge.<domain>.duckdns.org
CNAME                 <own-domain>                    <domain>.duckdns.org

Option: seconds

The number of seconds to wait before updating DuckDNS subdomains and renewing Let's Encrypt certificates.

Known issues and limitations

  • To log in, DuckDNS requires a free account from any of the following services: Google, Github, Twitter or Persona.
  • A free DuckDNS account is limited to five subdomains.
  • At time of writing, Duck DNS' own IPv6 autodetection does not actually work, but you can use the URL option for ipv6 to get around this, read on.

Support

Got questions?

You have several options to get them answered:

In case you've found a bug, please open an issue on our GitHub.