1.\" $OpenBSD: acme-client.conf.5,v 1.29 2021/01/11 07:23:42 jmc Exp $ 2.\" 3.\" Copyright (c) 2005 Esben Norby <norby@openbsd.org> 4.\" Copyright (c) 2004 Claudio Jeker <claudio@openbsd.org> 5.\" Copyright (c) 2003, 2004 Henning Brauer <henning@openbsd.org> 6.\" Copyright (c) 2002 Daniel Hartmeier <dhartmei@openbsd.org> 7.\" 8.\" Permission to use, copy, modify, and distribute this software for any 9.\" purpose with or without fee is hereby granted, provided that the above 10.\" copyright notice and this permission notice appear in all copies. 11.\" 12.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 13.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 14.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 15.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 16.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 17.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 18.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 19.\" 20.Dd $Mdocdate: January 11 2021 $ 21.Dt ACME-CLIENT.CONF 5 22.Os 23.Sh NAME 24.Nm acme-client.conf 25.Nd acme-client configuration file 26.Sh DESCRIPTION 27The 28.Nm 29file is divided into the following main sections: 30.Bl -tag -width xxxx 31.It Sy Macros 32User-defined variables may be defined and used later, simplifying the 33configuration file. 34.It Sy Authorities 35Certificate authorities (CAs) that can be contacted via ACME. 36.It Sy Domains 37Certificate specifications. 38.El 39.Pp 40Additional configuration files can be included with the 41.Ic include 42keyword, for example: 43.Bd -literal -offset indent 44include "/etc/acme-client.sub.conf" 45.Ed 46.Pp 47The current line can be extended over multiple lines using a backslash 48.Pq Sq \e . 49Comments can be put anywhere in the file using a hash mark 50.Pq Sq # , 51and extend to the end of the current line. 52Care should be taken when commenting out multi-line text: 53the comment is effective until the end of the entire block. 54.Pp 55Argument names not beginning with a letter, digit, underscore, or '/' 56must be quoted. 57.Sh MACROS 58Macros can be defined that will later be expanded in context. 59Macro names must start with a letter, digit, or underscore, 60and may contain any of those characters. 61Macro names may not be reserved words. 62Macros are not expanded inside quotes. 63.Pp 64For example: 65.Bd -literal -offset indent 66api_url="https://acme-v02.api.letsencrypt.org/directory" 67authority letsencrypt { 68 api url $api_url 69 account key "/etc/acme/letsencrypt-privkey.pem" 70} 71.Ed 72.Sh AUTHORITIES 73The configured certificate authorities. 74.Pp 75Each authority section starts with a declaration of the name identifying a 76certificate authority. 77.Bl -tag -width Ds 78.It Ic authority Ar name Brq ... 79The 80.Ar name 81is a string used to reference this certificate authority. 82.El 83.Pp 84It is followed by a block of options enclosed in curly brackets: 85.Bl -tag -width Ds 86.It Ic account key Ar file Op Ar keytype 87Specify a 88.Ar file 89used to identify the user of this certificate authority. 90.Ar keytype 91can be 92.Cm rsa 93or 94.Cm ecdsa . 95It defaults to 96.Cm rsa . 97.It Ic api url Ar url 98Specify the 99.Ar url 100under which the ACME API is reachable. 101.It Ic contact Ar contact 102Optional 103.Ar contact 104URLs that the authority can use to contact the client for issues related to 105this account. 106.El 107.Sh DOMAINS 108The certificates to be obtained through ACME. 109.Bl -tag -width Ds 110.It Ic domain Ar handle Brq ... 111Each domain section begins with the 112.Ic domain 113keyword followed by an identifier for this domain block. 114.El 115.Pp 116It is followed by a block of options enclosed in curly brackets: 117.Bl -tag -width Ds 118.It Ic domain name Ar name 119The 120.Ar name 121to be used as the common name component of the subject of the 122X.509 certificate. 123This is optional. 124If not specified, the 125.Ar handle 126of the domain block will be used as common name. 127.It Ic alternative names Brq ... 128A list of alternative names, 129comma or space separated, 130for which the certificate will be valid. 131The common name is included automatically if this option is present, 132but there is no automatic conversion/inclusion between "www." and 133plain domain name forms. 134.It Ic domain key Ar file Op Ar keytype 135The private key file for which the certificate will be obtained. 136.Ar keytype 137can be 138.Cm rsa 139or 140.Cm ecdsa . 141It defaults to 142.Cm rsa . 143If the key file does not exist, 144.Xr acme-client 1 145will generate a key itself (4096-bit for 146.Cm rsa 147or secp384r1 for 148.Cm ecdsa ) . 149.It Ic domain certificate Ar file 150The filename of the certificate that will be issued. 151This is optional if 152.Ar domain full chain certificate 153is specified. 154A backup with name 155.Ar file.1 156is created if 157.Ar file 158exists. 159.It Ic domain chain certificate Ar file 160The filename in which to store the certificate chain 161that will be returned by the certificate authority. 162It needs to be in the same directory as the 163.Ar domain certificate 164(or in a subdirectory) and can be specified as a relative or absolute path. 165This setting is optional. 166A backup with name 167.Ar file.1 168is created if 169.Ar file 170exists. 171.It Ic domain full chain certificate Ar file 172The filename in which to store the full certificate chain 173that will be returned by the certificate authority. 174It needs to be in the same directory as the 175.Ar domain certificate 176(or in a subdirectory) and can be specified as a relative or absolute path. 177This is a combination of the 178.Ar domain certificate 179and the 180.Ar domain chain certificate 181in one file, and is required by most browsers. 182This is optional if 183.Ar domain certificate 184is specified. 185A backup with name 186.Ar file.1 187is created if 188.Ar file 189exists. 190.It Ic sign with Ar authority 191The certificate authority (as declared above in the 192.Sx AUTHORITIES 193section) to use. 194If this setting is absent, the first authority specified is used. 195.It Ic challengedir Ar path 196The directory in which the challenge file will be stored. 197If it is not specified, a default of 198.Pa /var/www/acme 199will be used. 200.El 201.Sh FILES 202.Bl -tag -width /etc/examples/acme-client.conf -compact 203.It Pa /etc/acme-client.conf 204.Xr acme-client 1 205configuration file. 206.It Pa /etc/examples/acme-client.conf 207Example configuration file. 208.El 209.Sh SEE ALSO 210.Xr acme-client 1 211.Sh HISTORY 212The 213.Nm 214file format first appeared in 215.Ox 6.1 . 216