1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
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 /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 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 /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
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 /usr/local/etc/lfacme .
.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
|
