flesh this page out a bit to (hopefully) make it more helpful;

sthen suggested adding a random sleep (like we do with spamd) for the
example cron job;

help/ok sthen benno florian

1 files changed, 69 insertions, 47 deletions

diff --git a/usr.sbin/acme-client/acme-client.1 b/usr.sbin/acme-client/acme-client.1
index c0716ce9fda..9d198f7abdc 100644
--- a/usr.sbin/acme-client/acme-client.1
+++ b/usr.sbin/acme-client/acme-client.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: acme-client.1,v 1.28 2019/01/30 21:15:14 jmc Exp $
+.\"	$OpenBSD: acme-client.1,v 1.29 2019/02/03 20:39:35 jmc Exp $
 .\"
 .\" Copyright (c) 2016 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: January 30 2019 $
+.Dd $Mdocdate: February 3 2019 $
 .Dt ACME-CLIENT 1
 .Os
 .Sh NAME
@@ -26,54 +26,41 @@
 .Op Fl f Ar configfile
 .Ar domain
 .Sh DESCRIPTION
-The
-.Nm
-utility is an
-Automatic Certificate Management Environment (ACME) client.
-.Pp
-The options are as follows:
-.Bl -tag -width Ds
-.It Fl A
-Create a new RSA account key if one does not already exist.
-.It Fl D
-Create a new RSA domain key if one does not already exist.
-.It Fl F
-Force updating the certificate signature even if it's too soon.
-.It Fl f Ar configfile
-Specify an alternative configuration file.
-.It Fl n
-No operation: check and print configuration.
-.It Fl r
-Revoke the X.509 certificate.
-.It Fl v
-Verbose operation.
-Specify twice to also trace communication and data transfers.
-.It Ar domain
-The domain name.
-.El
-.Pp
 .Nm
-looks in its configuration for a
+is an
+Automatic Certificate Management Environment (ACME) client:
+it looks in its configuration for a domain section
+corresponding to the
 .Ar domain
-section corresponding to the domain given as command line argument.
-It then uses that configuration to retrieve an X.509 certificate.
-If the certificate already exists and is less than 30 days from expiry,
-.Nm
-will attempt to refresh the signature.
+given as command line argument
+and uses that configuration to retrieve an X.509 certificate
+which can be used to provide domain name validation
+(i.e. prove that the domain is who it says it is).
+The certificates are typically used to provide HTTPS for web servers,
+but can be used in any situation where domain name validation is required
+(such as mail servers).
+.Pp
 Before a certificate can be requested, an account key needs to be
 created using the
 .Fl A
 argument.
 The first time a certificate is requested, a domain key needs to be created with
 .Fl D .
+So a typical invocation the first time it's run would be:
+.Pp
+.Dl # acme-client -ADv example.com
 .Pp
-Challenges are used to verify that the submitter has access to the
-registered domains.
+If the certificate already exists and is less than 30 days from expiry,
 .Nm
-only implements the
+attempts to renew the certificate.
+.Pp
+In order to prove that the client has access to the domain,
+a challenge is issued by the signing authority.
+.Nm
+implements the
 .Dq http-01
 challenge type, where a file is created within a directory accessible
-by a locally-run web server.
+by a locally run web server.
 The default challenge directory
 .Pa /var/www/acme
 can be served by
@@ -86,8 +73,32 @@ location "/.well-known/acme-challenge/*" {
 	request strip 2
 }
 .Ed
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl A
+Create a new RSA account key if one does not already exist.
+.It Fl D
+Create a new RSA domain key if one does not already exist.
+.It Fl F
+Force certificate renewal, even if it's too soon.
+.It Fl f Ar configfile
+Specify an alternative configuration file.
+.It Fl n
+No operation: check and print configuration.
+.It Fl r
+Revoke the X.509 certificate.
+.It Fl v
+Verbose operation.
+Specify twice to also trace communication and data transfers.
+.It Ar domain
+The domain name.
+.El
 .Sh FILES
 .Bl -tag -width "/etc/acme-client.conf" -compact
+.It Pa /etc/acme
+Private keys for
+.Nm .
 .It Pa /etc/acme-client.conf
 Default configuration.
 .It Pa /var/www/acme
@@ -95,8 +106,10 @@ Default challengedir.
 .El
 .Sh EXIT STATUS
 .Nm
-returns 1 on failure, 2 if the certificates didn't change (up to date),
-or 0 if certificates were changed (revoked or updated).
+returns 0 if certificates were changed (revoked or updated),
+1 on failure,
+or
+2 if the certificates didn't change (up to date).
 .Sh EXAMPLES
 Example configuration files for
 .Nm
@@ -107,16 +120,25 @@ are provided in
 and
 .Pa /etc/examples/httpd.conf .
 .Pp
-To enable TLS in
-.Xr httpd 8 :
+To generate a certificate for example.com and use it to provide HTTPS,
+create
+.Pa acme-client.conf
+and
+.Pa httpd.conf
+and run:
 .Pp
-.Dl # acme-client -vAD example.com && rcctl reload httpd
+.Dl # acme-client -ADv example.com && rcctl reload httpd
 .Pp
-A daily
+A
 .Xr cron 8
-job can renew the certificate:
-.Pp
-.Dl acme-client example.com && rcctl reload httpd
+job can renew the certificate as necessary.
+On renewal,
+.Xr httpd 8
+is reloaded:
+.Bd -literal -offset indent
+0	*	*	*	*	sleep $((RANDOM \e% 2048)) && \e
+	acme-client example.com && rcctl reload httpd
+.Ed
 .Sh SEE ALSO
 .Xr openssl 1 ,
 .Xr acme-client.conf 5 ,