1.\" $OpenBSD: acme-client.conf.5,v 1.2 2016/09/18 21:53:41 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: September 18 2016 $ 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 29config file is divided into three 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 35TLS authorities that can be contacted via ACME. 36.It Sy Domains 37Domains that the user wants to receive TLS certificates for. 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 66le="letsencrypt" 67domain example.com { 68 sign with $le 69} 70.Ed 71.Sh AUTHORITIES 72The configured certificate authorities. 73.Pp 74Each authority section starts with a declaration of the name identifying a 75certificate authority. 76.Bl -tag -width Ds 77.It Ic authority Ar name Brq ... 78The 79.Ar name 80is a string used to reference this certificate authority. 81.El 82.Pp 83It is followed by a block of options enclosed in curly brackets: 84.Bl -tag -width Ds 85.It Ic account key Ar file 86Specify a 87.Ar file 88used to identify the user of this CA. 89.It Ic agreement url Ar url 90Specify the 91.Ar url 92of a contract under which the certificates are supplied by the certificate 93authority. 94.It Ic api url Ar url 95Specify the 96.Ar url 97under which the ACME API is reachable. 98.El 99.Pp 100An example authority block: 101.Bd -literal -offset indent 102authority letsencrypt { 103 agreement url https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2016.pdf 104 api url "https://acme-v01.api.letsencrypt.org/directory" 105 account key /etc/ssl/private/my-acme.key 106} 107.Ed 108.Sh DOMAINS 109The domains that are configured to obtain SSL certificates through ACME. 110.Bl -tag -width Ds 111.It Ic domain Ar name Brq ... 112Each domain section begins with the 113.Ic domain 114keyword followed by the domain name. 115.El 116.Pp 117It is followed by a block of options enclosed in curly brackets: 118.Bl -tag -width Ds 119.It Ic alternative names Brq ... 120Specify a list of alternative names the certificate will be valid for. 121.It Ic domain key Ar file 122The private key file for which the certificate will be obtained. 123.It Ic domain certificate Ar file 124The filename of the certificate that will be issued. 125.It Ic sign with Ar authority 126the certificate authority (as declared above in the 127.Sx AUTHORITIES 128section) to use for this domain is selected. 129.El 130.Pp 131An example domain declaration looks like this: 132.Bd -literal -offset indent 133domain example.com { 134 alternative names { secure.example.com } 135 domain key /etc/ssl/private/example.com.key 136 domain certificate /etc/ssl/example.com.crt 137 sign with letsencrypt 138} 139.Ed 140.Sh FILES 141.Bl -tag -width "/etc/acme-client.conf" -compact 142.It Pa /etc/acme-client.conf 143.Xr acme-client 1 144configuration file 145.El 146.Sh SEE ALSO 147.Xr acme-client 1 148.Sh HISTORY 149The 150.Nm 151file format first appeared in 152.Ox 6.1 . 153