diff --git a/duckdns/DOCS.md b/duckdns/DOCS.md new file mode 100644 index 0000000..9fe3524 --- /dev/null +++ b/duckdns/DOCS.md @@ -0,0 +1,113 @@ +# Home Assistant Add-on: DuckDNS + +## Installation + +Follow these steps to get the add-on installed on your system: + +1. Navigate in your Home Assistant frontend to **Supervisor** -> **Add-on Store**. +2. Find the "DuckDNS" add-on and click it. +3. Click on the "INSTALL" button. + +## How to use + +1. Visit [DuckDNS.org](https://www.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 add-on. +4. In the DuckDNS add-on 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 + +Add-on configuration: + +```yaml +lets_encrypt: + accept_terms: true + certfile: fullchain.pem + keyfile: privkey.pem +token: sdfj-2131023-dslfjsd-12321 +domains: + - my-domain.duckdns.org +seconds: 300 +``` + +### 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](https://letsencrypt.org/repository/), 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 add-ons 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 add-ons 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: `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://api4.ipify.org/ or https://ipv4.wtfismyip.com/text + +### 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.wtfismyip.com/text + +### 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`. + +### 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, Persona or Reddit. +- A free DuckDNS account is limited to five subdomains. +- At time of writing, Duck DNS' own IPv6 autodetection + [does not actually work][duckdns-faq], 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: + +- The [Home Assistant Discord Chat Server][discord]. +- The Home Assistant [Community Forum][forum]. +- Join the [Reddit subreddit][reddit] in [/r/homeassistant][reddit] + +In case you've found a bug, please [open an issue on our GitHub][issue]. + +[discord]: https://discord.gg/c5DvZ4e +[forum]: https://community.home-assistant.io +[issue]: https://github.com/home-assistant/hassio-addons/issues +[reddit]: https://reddit.com/r/homeassistant +[duckdns]: https://duckdns.org +[duckdns-faq]: https://www.duckdns.org/faqs.jsp diff --git a/duckdns/README.md b/duckdns/README.md index 9ee8a28..848819e 100644 --- a/duckdns/README.md +++ b/duckdns/README.md @@ -8,119 +8,9 @@ Automatically update your Duck DNS IP address with integrated HTTPS support via [Duck DNS][duckdns] is a free service that points a DNS (sub-domains of duckdns.org) to an IP of your choice. This add-on includes support for Let’s Encrypt and automatically creates and renews your certificates. You need to sign up for a Duck DNS account before using this add-on. -## Installation - -Follow these steps to get the add-on installed on your system: - -1. Navigate in your Home Assistant frontend to **Supervisor** -> **Add-on Store**. -2. Find the "DuckDNS" add-on and click it. -3. Click on the "INSTALL" button. - -## How to use - -1. Visit [DuckDNS.org](https://www.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 add-on. -4. In the DuckDNS add-on 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 - -Add-on configuration: - -```yaml -lets_encrypt: - accept_terms: true - certfile: fullchain.pem - keyfile: privkey.pem -token: sdfj-2131023-dslfjsd-12321 -domains: - - my-domain.duckdns.org -seconds: 300 -``` - -### 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](https://letsencrypt.org/repository/), 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 add-ons 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 add-ons 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: `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://api4.ipify.org/ or https://ipv4.wtfismyip.com/text - -### 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.wtfismyip.com/text - -### 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`. - -### 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, Persona or Reddit. -- A free DuckDNS account is limited to five subdomains. -- At time of writing, Duck DNS' own IPv6 autodetection - [does not actually work][duckdns-faq], 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: - -- The [Home Assistant Discord Chat Server][discord]. -- The Home Assistant [Community Forum][forum]. -- Join the [Reddit subreddit][reddit] in [/r/homeassistant][reddit] - -In case you've found a bug, please [open an issue on our GitHub][issue]. - [aarch64-shield]: https://img.shields.io/badge/aarch64-yes-green.svg [amd64-shield]: https://img.shields.io/badge/amd64-yes-green.svg [armhf-shield]: https://img.shields.io/badge/armhf-yes-green.svg [armv7-shield]: https://img.shields.io/badge/armv7-yes-green.svg -[discord]: https://discord.gg/c5DvZ4e -[forum]: https://community.home-assistant.io [i386-shield]: https://img.shields.io/badge/i386-yes-green.svg -[issue]: https://github.com/home-assistant/hassio-addons/issues -[reddit]: https://reddit.com/r/homeassistant [duckdns]: https://duckdns.org -[duckdns-faq]: https://www.duckdns.org/faqs.jsp