NAME

domains.conf — lfacme domains configuration file

SYNOPSIS

/usr/local/etc/lfacme/domains.conf

DESCRIPTION

The domains.conf file is used to configure the certificates that lfacme will issue or renew. Each line specifies one certificate as a series of whitespace-separated fields. The first field is the certificate name, which is used by lfacme to create the certificate filename but is not part of the certificate itself. The remaining fields are either certificate options or subject alt names for the certificate.

If no subject alt names are provided, then the certificate name is used as the common name and subject alt name. Otherwise, the first subject alt name is used as the common name.

If the certificate name is “*”, then this line will not cause a certificate to be issued; instead, any options set on this line will apply to all following lines, or until another line with the certificate name “*”, which will replace the previously set options.

The following options may be set:

type=keytype

Configure the private key type. The keytype argument may be “ec” to generate a secp384r1 ECDSA key, or “rsa” to generate a 3072-bit RSA key. If not specified, the default value is “ec”.

challenge=filename

Invoke filename to handle ACME challenges for this certificate. If filename begins with a ‘/’ character, then it is assumed to be an absolute path, otherwise it will be searched for in /usr/local/share/lfacme/challenge and /usr/local/etc/lfacme/challenge.

The challenge script is passed to uacme(1); see the uacme documentation for details on the calling convention.

The following challenge scripts are provided with lfacme:

http

Use HTTP-based validation. See lfacme-http(5). This is the default challenge handler.

dns

Use DNS-based validation with nsupdate(1). See lfacme-dns(5).

kerberos

Use DNS-based validation with nsupdate(1) using Kerberos authentication. See lfacme-kerberos(5).

hook=filename

Invoke filename when this certificate is issued or renewed. If filename begins with a ‘/’ character, then it is assumed to be an absolute path, otherwise it is relative to the LFACME_HOOKDIR configured in acme.conf(5). This option may be specified multiple times.

The hook will be called with a single argument, which may be one of the following:

newcert

A certificate has been issued or renewed.

The following environment variables will be set when running the hook script:

LFACME_CONFDIR

The lfacme configuration directory, e.g. /usr/local/etc/lfacme.

LFACME_CERT

The identifier of the certificate, i.e. the first field in domains.conf. This is not necessarily the certificate's common name.

LFACME_CERTFILE

The path of a file which contains the public certificate and any issuer certificates, in PEM format.

LFACME_KEYFILE

The path of a file which contains the private key file in PEM format.

EXAMPLES

Set the key type to “rsa” for all certificates.

*	type=rsa

Issue a certificate for “example.org” using the default options. We don't provide any SANs, so the certificate name is used as the domain.

example.org

Issue a certificate for “example.org” with some SANs. Notice that because we specify one SAN, we now have to specify all of them.

example.org	example.org www.example.org

Issue two certificates for an SMTP server, one EC and one RSA. Some older SMTP clients still don't like EC certs. Run a hook after the certificate is (re)issued.

smtp-ec		smtp.example.org	type=ec  hook=install-smtp-cert
smtp-rsa	smtp.example.org	type=rsa hook=install-smtp-cert

Issue a certificate for a server and run multiple hooks.

server.example.org	hook=nginx hook=postfix hook=node-exporter

SEE ALSO

acme.conf(5), lfacme-renew(8)