From: John L. Villalovos <openstack.org@sodarock.com>
Date: Wed, 14 Mar 2018 05:50:47 +0000 (-0700)
Subject: Improve documentation on wildcards
X-Git-Tag: v0.6.2~15
X-Git-Url: http://git.ipfire.org/gitweb/gitweb.cgi?a=commitdiff_plain;h=7c40c727a0e933382d72fa689ff3bea294895326;p=thirdparty%2Fdehydrated.git

Improve documentation on wildcards

Improve the documentation on how to use wildcard domains.

Also give more examples in the docs/examples/domains.txt file.
---

diff --git a/docs/domains_txt.md b/docs/domains_txt.md
index db65d93..6a8915e 100644
--- a/docs/domains_txt.md
+++ b/docs/domains_txt.md
@@ -1,22 +1,72 @@
-### domains.txt
+## domains.txt
 
-dehydrated uses the file `domains.txt` as configuration for which certificates should be requested.
+dehydrated uses the file `domains.txt` as configuration for which certificates
+should be requested.
 
 The file should have the following format:
 
 ```text
+example.org
 example.com www.example.com
 example.net www.example.net wiki.example.net
+```
+
+This states that there are the following certificates:
+  * `example.org` without any *alternative names*
+  * `example.com` with an *alternative name* of `www.example.com`
+  * `example.net` with the *alternative names*: `www.example.net` and
+    `wiki.example.net`
+
+### Aliases
+
+You can define an *alias* for your certificate which will (instead of the
+primary domain) be used as the directory name under your `CERTDIR` and for a
+per-certificate lookup. This is done using the `>` character.  This allows
+multiple certificates with identical sets of domains but different
+configuration to exist.
+
+Here is an example of using an *alias* called `certalias` for creating the
+certificate for `example.net` with *alternative names* `www.example.net` and
+`wiki.example.net`. The certificate will be stored in the directory `certalias`
+under your `CERTDIR`.
+
+```text
 example.net www.example.net wiki.example.net > certalias
 ```
 
-This states that there should be two certificates `example.com` and `example.net`,
-with the other domains in the corresponding line being their alternative names.
+### Wildcards
+
+Support for wildcards was added by the ACME v2 protocol.
+
+Certificates with a wildcard domain as the first (or only) name require an
+*alias* to be set.  *Aliases* can't start with `*.`.
+
+For example to create the wildcard for `*.service.example.com` your
+`domains.txt` could use the *alias* method like this:
+
+```text
+*.service.example.com > star_service_example_com
+```
+
+This creates a wildcard certificate for only `*.service.example.com` and will
+store it in the directory `star_service_example_com` under your `CERTDIR`. As a
+note this certificate will **NOT** be valid for `service.example.com` but only
+for `*.service.example.com`. So it would, for example, be valid for
+`foo.service.example.com`.
+
+
+Another way to create it is using *alternative names*. For example your
+`domains.txt` could do this:
+
+```text
+service.example.com *.service.example.com
+eggs.example.com *.ham.example.com
+```
 
-You can define an alias for your certificate which will (instead of the primary domain) be
-used as directory name under your certdir and for a per-certificate lookup.
-This allows multiple certificates with identical sets of domains but different configuration
-to exist.
+This creates two certificates one for `service.example.com` with an
+*alternative name* of `*.service.example.com` and a second certificate for
+`eggs.example.com` with an *alternative name* of `*.ham.example.com`.
 
-Certificates with a wildcard domain as first (or only) name require an alias to be set.
-Aliases can't start with `*.`.
+**Note:** The first certificate is valid for both `service.example.com` and for
+`*.service.example.com` which can be a useful way to create wildcard
+certificates.
diff --git a/docs/examples/domains.txt b/docs/examples/domains.txt
index 50b4816..39acaf3 100644
--- a/docs/examples/domains.txt
+++ b/docs/examples/domains.txt
@@ -1,2 +1,30 @@
+# Create certificate for 'example.org' with an alternative name of
+# 'www.example.org'. It will be stored in the directory ${CERT_DIR}/example.org
 example.org www.example.org
+
+# Create certificate for 'example.com' with alternative names of
+# 'www.example.com' & 'wiki.example.com'. It will be stored in the directory
+# ${CERT_DIR}/example.com
 example.com www.example.com wiki.example.com
+
+# Using the alias 'certalias' create certificate for 'example.net' with
+# alternate name 'www.example.net' and store it in the directory
+# ${CERTDIR}/certalias
+example.net www.example.net > certalias
+
+# Using the alias 'service_example_com' create a wildcard certificate for
+# '*.service.example.com' and store it in the directory
+# ${CERTDIR}/service_example_com
+# NOTE: It is NOT a certificate for 'service.example.com'
+*.service.example.com > service_example_com
+
+# Using the alias 'star_service_example_org' create a wildcard certificate for
+# '*.service.example.org' with an alternative name of `service.example.org'
+# and store it in the directory ${CERTDIR}/star_service_example_org
+# NOTE: It is a certificate for 'service.example.org'
+*.service.example.org service.example.org  > star_service_example_org
+
+# Create a certificate for 'service.example.net' with an alternative name of
+# '*.service.example.net' (which is a wildcard domain) and store it in the
+# directory ${CERTDIR}/service.example.net
+service.example.net *.service.example.net