mirror of
https://github.com/dehydrated-io/dehydrated.git
synced 2026-03-19 15:54:01 +01:00
108 lines
3.4 KiB
Markdown
108 lines
3.4 KiB
Markdown
## domains.txt
|
|
|
|
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 allows to set per certificates options. The options you can change are
|
|
explained in [Per Certificate Config](per-certificate-config.md).
|
|
|
|
If you want to create different certificate types for the same domain
|
|
you can use:
|
|
|
|
```text
|
|
*.service.example.org service.example.org > star_service_example_org_rsa
|
|
*.service.example.org service.example.org > star_service_example_org_ecdsa
|
|
```
|
|
|
|
Then add a config file `certs/star_service_example_org_rsa/config` with
|
|
the value
|
|
|
|
```
|
|
KEY_ALGO="rsa"
|
|
```
|
|
|
|
or respectively
|
|
|
|
```
|
|
KEY_ALGO="ecdsa"
|
|
```
|
|
|
|
### 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
|
|
```
|
|
|
|
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`.
|
|
|
|
**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.
|
|
|
|
### Drop-in directory
|
|
|
|
If a directory named `domains.txt.d` exists in the same location as
|
|
`domains.txt`, the contents of `*.txt` files in that directory are appended to
|
|
the list of domains, in alphabetical order of the filenames. This is useful for
|
|
automation, as it doesn't require editing an existing file to add new domains.
|
|
|
|
Warning: Behaviour of this might change as the naming between `domains.txt.d`
|
|
and the `DOMAINS_D` config variable (which is used for per-certificate
|
|
configuration) is a bit confusing.
|