.\" This source code is released into the public domain.
.Dd June 3, 2025
.Dt DOMAINS.CONF 5
.Os
.Sh NAME
.Nm domains.conf
.Nd lfacme domains configuration file
.Sh SYNOPSIS
.Pa /usr/local/etc/lfacme/domains.conf
.Sh DESCRIPTION
The
.Nm
file is used to configure the certificates that
.Nm 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 internally by
.Nm lfacme
in 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.
.Pp
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.
.Pp
If the certificate name is
.Dq * ,
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
.Dq * ,
which will replace the previously set options.
.Pp
The following options may be set:
.Bl -tag -width indent
.It Sy type Ns Li = Ns Ar keytype
Configure the private key type.
The
.Ar keytype
argument may be
.Dq ec
to generate a secp384r1 ECDSA key, or
.Dq rsa
to generate a 3072-bit RSA key.
If not specified, the default value is
.Dq ec .
.It Sy challenge Ns Li = Ns Ar filename
Invoke
.Ar filename
to handle ACME challenges for this certificate.
If
.Ar filename
begins with a
.Sq /
character, then it is assumed to be an absolute path,
otherwise it will be searched for in
.Pa /usr/local/share/lfacme/challenge
and
.Pa /usr/local/etc/lfacme/challenge .
.Pp
The challenge script is passed to
.Xr uacme 1 ;
see the uacme documentation for details on the calling convention.
.Pp
Two challenge scripts are provided with
.Nm lfacme :
.Bl -tag -width kerberos
.It Sy http
Use HTTP-based validation.
This requires
.Va ACME_HTTP_CHALLENGE_DIR
to be set in
.Xr acme.conf 5 .
This is the default challenge handler.
.It Sy kerberos
Use DNS-based validation with
.Xr nsupdate 1
using Kerberos authentication.
This requires
.Va ACME_KERBEROS_PRINCIPAL
to be set in
.Xr acme.conf 5 .
.El
.It Sy hook Ns Li = Ns Ar filename
Invoke
.Ar filename
when this certificate is issued or renewed.
If
.Ar filename
begins with a
.Sq /
character, then it is assumed to be an absolute path,
otherwise it is relative to the
.Va ACME_HOOKDIR
configured in
.Xr acme.conf 5 .
This option may be specified multiple times.
.Pp
The hook will be called with a single argument,
which may be one of the following:
.Bl -tag -width newcert
.It Sy newcert
A certificate has been issued or renewed.
.El
.Pp
The following environment variables will be set when running the hook script:
.Bl -tag -width LFACME_CERTFILE
.It Sy LFACME_CERT
The identifier of the certificate, i.e. the first field in
.Nm .
This is not necessarily the certificate's common name.
.It Sy LFACME_CERTFILE
The path of a file which contains the public certificate and any issuer
certificates, in PEM format.
.It Sy LFACME_KEYFILE
The path of a file which contains the private key file in PEM format.
.El
.El
.Sh EXAMPLES
Set the key type to
.Dq rsa
for all certificates.
.Bd -literal -offset indent
*	type=rsa
.Ed
.Pp
Issue a certificate for
.Dq example.org
using the default options.
We don't provide any SANs, so the certificate name is used as the domain.
.Bd -literal -offset indent
example.org
.Ed
.Pp
Issue a certificate for
.Dq example.org
with some SANs.
Notice that because we specify one SAN, we now have to specify all of them.
.Bd -literal -offset indent
example.org	example.org www.example.org
.Ed
.Pp
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.
.Bd -literal -offset indent
smtp-ec		smtp.example.org	type=ec  hook=install-smtp-cert
smtp-rsa	smtp.example.org	type=rsa hook=install-smtp-cert
.Ed
.Pp
Issue a certificate for a server and run multiple hooks.
.Bd -literal -offset indent
server.example.org	hook=nginx hook=postfix hook=node-exporter
.Ed
.Sh SEE ALSO
.Xr acme.conf 5 ,
.Xr lfacme-renew 8