allow PREFIX to be customised

1 files changed, 164 insertions, 0 deletions

diff --git a/domains.conf.5.in b/domains.conf.5.in
new file mode 100644
index 0000000..4ac27db
--- /dev/null
+++ b/domains.conf.5.in
@@ -0,0 +1,164 @@
+.\" 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 __CONFDIR__/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 by
+.Nm 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.
+.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 __LIBDIR__/challenge
+and
+.Pa __CONFDIR__/challenge .
+.Pp
+The challenge script is passed to
+.Xr uacme 1 ;
+see the uacme documentation for details on the calling convention.
+.Pp
+The following challenge scripts are provided with
+.Nm lfacme :
+.Bl -tag -width kerberos
+.It Sy http
+Use HTTP-based validation.
+See
+.Xr lfacme-http 5 .
+This is the default challenge handler.
+.It Sy dns
+Use DNS-based validation with
+.Xr nsupdate 1 .
+See
+.Xr lfacme-dns 5 .
+.It Sy kerberos
+Use DNS-based validation with
+.Xr nsupdate 1
+using Kerberos authentication.
+See
+.Xr lfacme-kerberos 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_CONFDIR
+The
+.Nm lfacme
+configuration directory, e.g.
+.Pa __CONFDIR__ .
+.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