1.\" $OpenBSD: acme-client.1,v 1.42 2023/05/16 09:02:50 espie Exp $ 2.\" 3.\" Copyright (c) 2016 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: May 16 2023 $ 18.Dt ACME-CLIENT 1 19.Os 20.Sh NAME 21.Nm acme-client 22.Nd ACME client 23.Sh SYNOPSIS 24.Nm acme-client 25.Op Fl Fnrv 26.Op Fl f Ar configfile 27.Ar handle 28.Sh DESCRIPTION 29.Nm 30is an 31Automatic Certificate Management Environment (ACME) client: 32it looks in its configuration for a domain section 33corresponding to the 34.Ar handle 35given as command line argument 36and uses that configuration to retrieve an X.509 certificate 37which can be used to provide domain name validation 38(i.e. prove that the domain is who it says it is). 39The certificates are typically used to provide HTTPS for web servers, 40but can be used in any situation where domain name validation is required 41(such as mail servers). 42.Pp 43If the certificate already exists and is less than 30 days from expiry, 44.Nm 45attempts to renew the certificate. 46.Pp 47In order to prove that the client has access to the domain, 48a challenge is issued by the signing authority. 49.Nm 50implements the 51.Dq http-01 52challenge type, where a file is created within a directory accessible 53by a locally run web server. 54The default challenge directory 55.Pa /var/www/acme 56can be served by 57.Xr httpd 8 58with this location block, 59which will properly map response challenges: 60.Bd -literal -offset indent 61location "/.well-known/acme-challenge/*" { 62 root "/acme" 63 request strip 2 64} 65.Ed 66.Pp 67The options are as follows: 68.Bl -tag -width Ds 69.It Fl F 70Force certificate renewal, even if it has more than 30 days 71validity. 72.It Fl f Ar configfile 73Specify an alternative configuration file. 74.It Fl n 75No operation: check and print configuration. 76.It Fl r 77Revoke the X.509 certificate. 78.It Fl v 79Verbose operation. 80Specify twice to also trace communication and data transfers. 81.It Ar handle 82The handle of the domain section of the configuration that contains the 83details of the certificate to be created, renewed or revoked. 84.El 85.Sh FILES 86.Bl -tag -width "/etc/acme-client.conf" -compact 87.It Pa /etc/acme 88Private keys for 89.Nm . 90.It Pa /etc/acme-client.conf 91Default configuration. 92.It Pa /var/www/acme 93Default challengedir. 94.El 95.Sh EXIT STATUS 96.Nm 97returns 0 if certificates were changed (revoked or updated), 981 on failure, 99or 1002 if the certificates didn't change (up to date). 101.Sh EXAMPLES 102Example configuration files for 103.Nm 104and 105.Xr httpd 8 106are provided in 107.Pa /etc/examples/acme-client.conf 108and 109.Pa /etc/examples/httpd.conf . 110.Pp 111To generate a certificate for example.com and use it to provide HTTPS, 112create 113.Pa acme-client.conf 114and 115.Pa httpd.conf 116and run: 117.Pp 118.Dl # acme-client -v example.com && rcctl reload httpd 119.Pp 120A 121.Xr cron 8 122job can renew the certificate as necessary. 123On renewal, 124.Xr httpd 8 125is reloaded: 126.Bd -literal -offset indent 127~ * * * * acme-client example.com && rcctl reload httpd 128.Ed 129.Sh SEE ALSO 130.Xr openssl 1 , 131.Xr acme-client.conf 5 , 132.Xr httpd.conf 5 , 133.Xr ssl 8 134.Sh STANDARDS 135.Rs 136.%A R. Barnes 137.%A J. Hoffman-Andrews 138.%A D. McCarney 139.%A J. Kasten 140.%D March 2019 141.%R RFC 8555 142.%T Automatic Certificate Management Environment (ACME) 143.Re 144.Sh HISTORY 145The 146.Nm 147utility first appeared in 148.Ox 6.1 . 149.Sh AUTHORS 150The 151.Nm 152utility was written by 153.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . 154.Sh CAVEATS 155The usual ACME service providers are notoriously picky about 156authenticating rules, and yield fairly long time-outs after just a 157few invalid attempts. 158It is strongly suggested to first validate a configuration with a 159staging server before moving an official certificate validation 160workflow to 161.Xr crontab 5 162status. 163