Skip to content

Commit

Permalink
added example for dns challenge delegation to the Readme
Browse files Browse the repository at this point in the history
  • Loading branch information
infinityofspace committed May 7, 2022
1 parent 163092b commit 96fa471
Showing 1 changed file with 67 additions and 2 deletions.
69 changes: 67 additions & 2 deletions Readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,10 +148,10 @@ To check if the plugin is installed correctly and detected properly by certbot,
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
Expand All @@ -166,6 +166,8 @@ certbot certonly \
-d "example.duckdns.org"
```

---

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

```commandline
Expand All @@ -180,6 +182,8 @@ certbot certonly \
-d "cloud.example.duckdns.org"
```

---

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

```commandline
Expand All @@ -194,6 +198,8 @@ certbot certonly \
-d "*.example.duckdns.org"
```

---

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

```commandline
Expand All @@ -208,6 +214,8 @@ certbot certonly \
-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):

Expand All @@ -223,6 +231,8 @@ certbot certonly \
-d "example.duckdns.org"
```

---

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

Expand All @@ -239,12 +249,67 @@ certbot certonly \
--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](https://certbot.eff.org/docs/using.html#certbot-command-line-options) of *certbot*.

Expand Down

0 comments on commit 96fa471

Please sign in to comment.