dehydrated/docs/domains_txt.md

domains.txt

dehydrated uses the file domains.txt as configuration for which certificates should be requested.

The file should have the following format:

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.

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.

If you want to create different certificate types for the same domain you can use:

*.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:

*.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:

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.