Plugin for certbot for a DNS-01 challenge with a DuckDNS domain.

infinityofspace, updated 🕥 2023-03-12 21:02:59

Certbot DNS DuckDNS Plugin

Plugin for certbot for a DNS-01 challenge with a DuckDNS domain.

PyPI - Python Version GitHub

PyPI PyPI - Downloads GitHub Workflow Status

Docker Image Version (latest semver) Docker Image Size (latest semver) GitHub Workflow Status

certbot-dns-duckdns

Table of Contents

  1. About
  2. Installation
    1. Prerequirements
    2. With pip (recommend)
    3. From source
    4. Snap
  3. Usage
    1. Credentials file or cli parameters
    2. Local installation usage
    3. Docker usage
    4. Plugin arguments
  4. FAQ
  5. Third party notices
  6. License

About

certbot_dn_duckdns is a plugin for certbot to create the DNS-01 challenge for a DuckDNS domain. The plugin takes care of setting and deleting the TXT entry via the DuckDNS API.

Installation

Prerequirements

If you want to use the docker image, then you don't need any requirements other than a working docker installation and can proceed directly to the usage

If you prefer the local installation, then you need at least version 3.7 of Python installed. If you want to install this plugin with pip, then you also need pip3 installed.

If you already have certbot installed, make sure you have at least version 1.18.0 installed. When you installed certbot as snap then you have to use the snap installation of the plugin.

You can check what version of certbot is installed with this command:

commandline certbot --version

If you don't have certbot installed yet, then the PyPI version of certbot will be installed automatically during the installation.

Note: If you want to run certbot with root privileges, then you need to install the plugin with root privileges too. Otherwise, certbot cannot find the plugin.

With pip (recommend)

Use the following command to install certbot_dns_duckdns with pip:

commandline pip install certbot_dns_duckdns

You can also very easily update to a newer version:

commandline pip install certbot_dns_duckdns -U

From source

commandline git clone https://github.com/infinityofspace/certbot_dns_duckdns cd certbot_dns_duckdns pip install .

Snap

If you use the certbot as snap package then you have to install certbot_dns_duckdns as a snap too:

commandline snap install certbot-dns-duckdns

Now connect the certbot snap installation with the plugin snap installation:

commandline sudo snap connect certbot:plugin certbot-dns-duckdns

The following command should now list dns-duckdns as an installed plugin:

commandline certbot plugins

Usage

Note: You cannot create certificates for multiple DuckDNS domains with one certbot call. This is because DuckDNS only allows one TXT record. If certificates for several domains should be created at the same time, then the same number of distinct DNS TXT records must be created. To solve the problem, you simply have to make a separate certbot call for each domain.

Note that the certificate generation through Letsencrypt has rate limits. For testing, use the additional argument --staging to solve this problem.

Credentials file or cli parameters

You can either use cli parameters to pass authentication information to certbot:

commandline ... --dns-duckdns-token <your-duckdns-token>

Or to prevent your credentials from showing up in your bash history, you can also create a credentials-file duckdns.ini (the name does not matter) with the following content:

ini dns_duckdns_token=<your-duckdns-token>

And then instead of using the --dns-duckdns-key parameter above you can use

commandline ... --dns-duckdns-credentials </path/to/your/duckdns.ini>

You can also mix these usages, though the cli parameters always take precedence over the ini file.

Local installation usage

To check if the plugin is installed correctly and detected properly by certbot, you can use the following command:

commandline certbot plugins

Below are some examples of how to use the plugin:

Generate a certificate for a DNS-01 challenge of the domain "example.duckdns.org":

commandline certbot certonly \ --non-interactive \ --agree-tos \ --email <your-email> \ --preferred-challenges dns \ --authenticator dns-duckdns \ --dns-duckdns-token <your-duckdns-token> \ --dns-duckdns-propagation-seconds 60 \ -d "example.duckdns.org"

Generate a certificate for a DNS-01 challenge of the subdomain "cloud.example.duckdns.org":

commandline certbot certonly \ --non-interactive \ --agree-tos \ --email <your-email> \ --preferred-challenges dns \ --authenticator dns-duckdns \ --dns-duckdns-token <your-duckdns-token> \ --dns-duckdns-propagation-seconds 60 \ -d "cloud.example.duckdns.org"

Generate a wildcard certificate for a DNS-01 challenge of all subdomains "*.example.duckdns.org":

commandline certbot certonly \ --non-interactive \ --agree-tos \ --email <your-email> \ --preferred-challenges dns \ --authenticator dns-duckdns \ --dns-duckdns-token <your-duckdns-token> \ --dns-duckdns-propagation-seconds 60 \ -d "*.example.duckdns.org"

Generate a certificate for a DNS-01 challenge of the domain "example.duckdns.org" using a credentials file:

commandline certbot certonly \ --non-interactive \ --agree-tos \ --email <your-email> \ --preferred-challenges dns \ --authenticator dns-duckdns \ --dns-duckdns-credentials </path/to/your/duckdns.ini> \ --dns-duckdns-propagation-seconds 60 \ -d "example.duckdns.org"

Generate a certificate for a DNS-01 challenge of the domain "example.duckdns.org" without an account (i.e. without an email address):

commandline certbot certonly \ --non-interactive \ --agree-tos \ --register-unsafely-without-email \ --preferred-challenges dns \ --authenticator dns-duckdns \ --dns-duckdns-token <your-duckdns-token> \ --dns-duckdns-propagation-seconds 60 \ -d "example.duckdns.org"

Generate a staging certificate (i.e. temporary testing certificate) for a DNS-01 challenge of the domain " example.duckdns.org":

commandline certbot certonly \ --non-interactive \ --agree-tos \ --email <your-email> \ --preferred-challenges dns \ --authenticator dns-duckdns \ --dns-duckdns-token <your-duckdns-token> \ --dns-duckdns-propagation-seconds 60 \ -d "example.duckdns.org" \ --staging

DNS-01 Challenges allow using CNAME records or NS records to delegate the challenge response to other DNS zones. For example, this allows you to resolve the DNS challenge for another provider's domain using a duckdns domain. For example, we have abc.duckdns.org as duckdns domain and example.com as our other domain. We might have an existing DNS configuration which look like this: commandline one.example.com. 600 IN CNAME two.example.com. two.example.com. 600 IN CNAME abc.duckdns.org. It chains one.example.com to two.example.com and finally to abc.duckdns.org.

Now we want to issue a DNS-01 challenge for the subdomain "test.example.com". So we create a CNAME record for "_acme-challenge.test.example.com" pointing to "one.example.com". The DNS records now look like this: commandline _acme-challenge.test.example.com. 600 IN CNAME one.example.com. one.example.com. 600 IN CNAME two.example.com. two.example.com. 600 IN CNAME abc.duckdns.org.

Now we use certbot to generate a certificate for the domain test.example.com with the DNS challenge:

commandline certbot certonly \ --non-interactive \ --agree-tos \ --email <your-email> \ --preferred-challenges dns \ --authenticator dns-duckdns \ --dns-duckdns-token <your-duckdns-token> \ --dns-duckdns-propagation-seconds 60 \ -d "test.example.com" \

What happens in the background can be seen very well in the DNS records: commandline _acme-challenge.test.example.com. 600 IN CNAME one.example.com. one.example.com. 600 IN CNAME two.example.com. two.example.com. 600 IN CNAME abc.duckdns.org. abc.duckdns.org. 60 TXT "asduh9asudhßa97sdhap9sudaisudoi"

When validating the DNS challenge value, all CNAME records are now traversed. It starts with _acme-challenge.test.example.com and goes to one.example.com, then to two.example.com and finally to abc.duckdns.org. Here is the validation token stored as TXT record.

The example could also be shortened by directly creating a CNAME entry from _acme-challenge.test.example.com to abc.duckdns.org. So we skip all other CNAME records in between. To make it clear that any CNAME records are traversed during validation, the intermediate parts are added in the previous example.

Try to update all currently generated certificates:

commandline certbot renew

You can find al list of all available certbot cli options in the official documentation of certbot.

Docker usage

You can simply start a new container and use the same certbot commands to obtain a new certificate:

commandline docker run -v "/etc/letsencrypt:/etc/letsencrypt" -v "/var/log/letsencrypt:/var/log/letsencrypt" infinityofspace/certbot_dns_duckdns:latest \ certonly \ --non-interactive \ --agree-tos \ --email <your-email> \ --preferred-challenges dns \ --authenticator dns-duckdns \ --dns-duckdns-token <your-duckdns-token> \ --dns-duckdns-propagation-seconds 60 \ -d "example.duckdns.org"

Or you can use a credentials file:

commandline docker run -v "/etc/letsencrypt:/etc/letsencrypt" -v "/var/log/letsencrypt:/var/log/letsencrypt" -v "/absolute/path/to/your/duckdns.ini:/conf/duckdns.ini" infinityofspace/certbot_dns_duckdns:latest \ certonly \ --non-interactive \ --agree-tos \ --email <your-email> \ --preferred-challenges dns \ --authenticator dns-duckdns \ --dns-duckdns-credentials /conf/duckdns.ini \ --dns-duckdns-propagation-seconds 60 \ -d "example.duckdns.org"

If you want to use the docker image to renew your certificates automatically, you can do this with the host cron, for example. To use this example you must have crontab and cron installed beforehand. Note that depending on the installation you may need to use the crontab of a root user to access the docker daemon or file directories. For example, use the following crontab expression:

0 3 */8 * * docker run --rm -v "/etc/letsencrypt:/etc/letsencrypt" -v "/var/log/letsencrypt:/var/log/letsencrypt" infinityofspace/certbot_dns_duckdns:latest renew

This will start a temporary docker container every 8 days at 3am and tries to renew expiring certificates.

An example for the usage with docker-compose can be found here.

Plugin arguments

```commandline Obtain certificates using a DNS TXT record for DuckDNS domains

--dns-duckdns-propagation-seconds DNS_DUCKDNS_PROPAGATION_SECONDS The number of seconds to wait for DNS to propagate before asking the ACME server to verify the DNS record. (default: 30) --dns-duckdns-credentials DNS_DUCKDNS_CREDENTIALS DuckDNS credentials INI file. (default: None) --dns-duckdns-token DNS_DUCKDNS_TOKEN DuckDNS token (overwrites credentials file) (default: None) --dns-duckdns-no-txt-restore Do not restore the original TXT record (default: False) ```

FAQ

You can the FAQ in the wiki.

Third party notices

All modules used by this project are listed below:

| Name | License | |:------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------:| | certbot | Apache 2.0 | | requests | Apache 2.0 | | setuptools | MIT | | dnspython | ISC |

Furthermore, this readme file contains embeddings of Shields.io.

License

MIT - Copyright (c) 2021-2022 Marvin Heptner

Issues

CNAME of duckdns domain fails to validate regex

opened on 2023-02-13 17:08:52 by diamant-x

https://github.com/infinityofspace/certbot_dns_duckdns/blob/de15d9ffca759531661e16d64d3681b5f3c9b7e9/certbot_dns_duckdns/duckdns/client.py#L10

Hi, I'm trying to use Nginx proxy to emit LetsEncrypt certificates for my custom domains. My domains are CNAME of a subdomain.duckdns.org entity. However, script seems to fail in the referenced code step after traversing the cname route and reaching the duckdns name. In particular, i get the following in the logs (below). Not sure why, as such domain shold be the same for other sites without cname alias.

  • Any ideas?

Thanks!

Command failed: certbot certonly --config "/etc/letsencrypt.ini" --cert-name "npm-7" --agree-tos --email "[email protected]" --domains "subdomain.mydomain.ml" --authenticator dns-duckdns --dns-duckdns-credentials "/etc/letsencrypt/credentials/credentials-7" Saving debug log to /data/logs/letsencrypt/letsencrypt.log Encountered exception during recovery: certbot.errors.PluginError: The domain "_acme-challenge.mysubdomain.duckdns.org" is not valid a duckdns subdomain. The domain "_acme-challenge.mysubdomain.duckdns.org" is not valid a duckdns subdomain. Ask for help or search for solutions at https://community.letsencrypt.org. See the logfile /data/logs/letsencrypt/letsencrypt.log or re-run Certbot with -v for more details.

Releases

v1.3 2023-03-02 10:47:58

This is a maintenance release and does not bring any new features. The docker image has mainly been adapted and improved.

What's Changed

  • Bump docker/build-push-action from 3 to 4 by @dependabot in https://github.com/infinityofspace/certbot_dns_duckdns/pull/127
  • the docker image builds cryptography to include the latest version of cryptography with security fixes
  • added docker image cache during ci build
  • adjusted pypi classifiers labels
  • ci steps and tests uses python 3.11

Notice

  • The docker image builds cryptography in this release, this makes the local build time much longer than in previous versions. Depending on the hardware this takes some time.

Full Changelog: https://github.com/infinityofspace/certbot_dns_duckdns/compare/v1.2.1...v1.3

v1.2.1 2022-12-05 23:45:46

What's Changed

  • fixed pypi release

Full Changelog: https://github.com/infinityofspace/certbot_dns_duckdns/compare/v1.2...v1.2.1

v1.2 2022-12-05 23:25:47

What's Changed

  • Remove the extra "certbot" in renew command by @yifangd in https://github.com/infinityofspace/certbot_dns_duckdns/pull/124
  • Update certbot requirement from <2.0,>=1.18.0 to >=1.18.0,<3.0 by @dependabot in https://github.com/infinityofspace/certbot_dns_duckdns/pull/125
  • Use alpine 3.17 as base image
  • Updated cryptography in docker image

New Contributors

  • @yifangd made their first contribution in https://github.com/infinityofspace/certbot_dns_duckdns/pull/124

Full Changelog: https://github.com/infinityofspace/certbot_dns_duckdns/compare/v1.1...v1.2

v1.1 2022-08-23 12:28:37

What's Changed:

  • minimum certbot version 1.18.0 is required to use the plugin (this requirement was already implicit in the last version v1.0 but has now been added explicitly)

Fixes:

  • fixed requirement issues in the snap app #117 (tanks to @alexzorin for the hint)

Full Changelog: https://github.com/infinityofspace/certbot_dns_duckdns/compare/v1.0...v1.1

v1.0 2022-07-22 10:32:42

We have made it to the first stable v1.0. Thanks for the bug reports, PRs and feature suggestions. Many thanks to all involved.

What's Changed

  • remove zope by @alexzorin in https://github.com/infinityofspace/certbot_dns_duckdns/pull/102
  • Bump actions/setup-python from 3 to 4 by @dependabot in https://github.com/infinityofspace/certbot_dns_duckdns/pull/101
  • Update requests requirement from ~=2.27 to ~=2.28 by @dependabot in https://github.com/infinityofspace/certbot_dns_duckdns/pull/108
  • Update setuptools requirement from ~=60.10 to ~=63.2 by @dependabot in https://github.com/infinityofspace/certbot_dns_duckdns/pull/111
  • Use alpine 3.16 as base image
  • Reduced docker image size for some archs
  • Bump cryptography for docker image from 3.3.2 to 3.4.8
  • bump requests from 2.26 to 2.28
  • Bump dnspython from 2.1 to 2.2

New Contributors

  • @alexzorin made their first contribution in https://github.com/infinityofspace/certbot_dns_duckdns/pull/102

Full Changelog: https://github.com/infinityofspace/certbot_dns_duckdns/compare/v0.9...v1.0

v0.9 2022-05-07 22:32:50

We are getting closer to the first stable version v1.0, with this version we are in the final phase. Please report possible bugs and problems.

New Features

  • feature handle delegated acme challenge by @Nobody84 in https://github.com/infinityofspace/certbot_dns_duckdns/pull/42

What's Changed

  • Bump actions/download-artifact from 2 to 3 by @dependabot in https://github.com/infinityofspace/certbot_dns_duckdns/pull/61
  • Bump actions/upload-artifact from 2 to 3 by @dependabot in https://github.com/infinityofspace/certbot_dns_duckdns/pull/60
  • Bump mccabe from 0.6.1 to 0.7.0 by @dependabot in https://github.com/infinityofspace/certbot_dns_duckdns/pull/45
  • Bump types-python-dateutil from 2.8.9 to 2.8.14 by @dependabot in https://github.com/infinityofspace/certbot_dns_duckdns/pull/76
  • Bump docker/setup-buildx-action from 1 to 2 by @dependabot in https://github.com/infinityofspace/certbot_dns_duckdns/pull/83
  • Bump docker/build-push-action from 2 to 3 by @dependabot in https://github.com/infinityofspace/certbot_dns_duckdns/pull/84
  • Bump docker/login-action from 1 to 2 by @dependabot in https://github.com/infinityofspace/certbot_dns_duckdns/pull/86
  • Bump docker/setup-qemu-action from 1 to 2 by @dependabot in https://github.com/infinityofspace/certbot_dns_duckdns/pull/85
  • Bump cloudflare from 2.8.15 to 2.9.10 by @dependabot in https://github.com/infinityofspace/certbot_dns_duckdns/pull/89
  • Bump awscli from 1.22.75 to 1.23.9 by @dependabot in https://github.com/infinityofspace/certbot_dns_duckdns/pull/90
  • Bump types-setuptools from 57.4.11 to 57.4.14 by @dependabot in https://github.com/infinityofspace/certbot_dns_duckdns/pull/88
  • Bump types-python-dateutil from 2.8.14 to 2.8.15 by @dependabot in https://github.com/infinityofspace/certbot_dns_duckdns/pull/92
  • Bump pygments from 2.11.2 to 2.12.0 by @dependabot in https://github.com/infinityofspace/certbot_dns_duckdns/pull/91
  • Update requests requirement from ~=2.26 to ~=2.27 by @dependabot in https://github.com/infinityofspace/certbot_dns_duckdns/pull/36
  • Update dnspython requirement from ~=2.1 to ~=2.2 by @dependabot in https://github.com/infinityofspace/certbot_dns_duckdns/pull/43
  • improved error handling

Fixes

  • fixed issues with not accepting some valid duckdns domains

New Contributors

  • @Nobody84 made their first contribution in https://github.com/infinityofspace/certbot_dns_duckdns/pull/42

Full Changelog: https://github.com/infinityofspace/certbot_dns_duckdns/compare/v0.8...v0.9

infinityofspace
GitHub Repository

duckdns certbot-dns-plugin dns-01-challange