1.\" $OpenBSD: acme-client.conf.5,v 1.25 2020/05/16 16:58:11 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: May 16 2020 $ 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.El 102.Sh DOMAINS 103The certificates to be obtained through ACME. 104.Bl -tag -width Ds 105.It Ic domain Ar handle Brq ... 106Each domain section begins with the 107.Ic domain 108keyword followed by an identifier for this domain block. 109.El 110.Pp 111It is followed by a block of options enclosed in curly brackets: 112.Bl -tag -width Ds 113.It Ic domain name Ar name 114The 115.Ar name 116to be used as the common name component of the subject of the 117X.509 certificate. 118This is optional. 119If not specified, the 120.Ar handle 121of the domain block will be used as common name. 122.It Ic alternative names Brq ... 123Specify a list of alternative names for which the certificate will be valid. 124The common name is included automatically if this option is present, 125but there is no automatic conversion/inclusion between "www." and 126plain domain name forms. 127.It Ic domain key Ar file Op Ar keytype 128The private key file for which the certificate will be obtained. 129.Ar keytype 130can be 131.Cm rsa 132or 133.Cm ecdsa . 134It defaults to 135.Cm rsa . 136.It Ic domain certificate Ar file 137The filename of the certificate that will be issued. 138This is optional if 139.Ar domain full chain certificate 140is specified. 141.It Ic domain chain certificate Ar file 142The filename in which to store the certificate chain 143that will be returned by the certificate authority. 144It needs to be in the same directory as the 145.Ar domain certificate 146(or in a subdirectory) and can be specified as a relative or absolute path. 147This setting is optional. 148.It Ic domain full chain certificate Ar file 149The filename in which to store the full certificate chain 150that will be returned by the certificate authority. 151It needs to be in the same directory as the 152.Ar domain certificate 153(or in a subdirectory) and can be specified as a relative or absolute path. 154This is a combination of the 155.Ar domain certificate 156and the 157.Ar domain chain certificate 158in one file, and is required by most browsers. 159This is optional if 160.Ar domain certificate 161is specified. 162.It Ic sign with Ar authority 163The certificate authority (as declared above in the 164.Sx AUTHORITIES 165section) to use. 166If this setting is absent, the first authority specified is used. 167.It Ic challengedir Ar path 168The directory in which the challenge file will be stored. 169If it is not specified, a default of 170.Pa /var/www/acme 171will be used. 172.El 173.Sh FILES 174.Bl -tag -width /etc/examples/acme-client.conf -compact 175.It Pa /etc/acme-client.conf 176.Xr acme-client 1 177configuration file. 178.It Pa /etc/examples/acme-client.conf 179Example configuration file. 180.El 181.Sh SEE ALSO 182.Xr acme-client 1 183.Sh HISTORY 184The 185.Nm 186file format first appeared in 187.Ox 6.1 . 188