acme-client.1 changes are largely similar to my previous attempt [off-list] with some feedback from jsing@ [thanks!] The example has been changed from "example.com" to "www.example.com" in an attempt to make it clear that "domain" is a misnomer.
acme-client.conf.5 stuff is mostly documenting which cert settings are optional. I've removed "(CAs)" as the abbreviation is unused later. "(CN)" has been added because, although unused elsewhere in the man page, it is likely to be seen be anyone examining the subject of a certificate. Ross Index: acme-client.1 =================================================================== RCS file: /cvs/src/usr.sbin/acme-client/acme-client.1,v retrieving revision 1.24 diff -u -p -r1.24 acme-client.1 --- acme-client.1 13 Jun 2018 15:08:24 -0000 1.24 +++ acme-client.1 1 Aug 2018 11:44:27 -0000 @@ -34,9 +34,9 @@ Automatic Certificate Management Environ The options are as follows: .Bl -tag -width Ds .It Fl A -Create a new RSA account key if one does not already exist. +Create a new RSA account key pair if one does not already exist. .It Fl D -Create a new RSA domain key if one does not already exist. +Create a new RSA certificate key pair 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 @@ -44,27 +44,28 @@ Specify an alternative configuration fil .It Fl n No operation: check and print configuration. .It Fl r -Revoke the X509 certificate found in the certificates. +Revoke the certificate. .It Fl v Verbose operation. Specify twice to also trace communication and data transfers. .It Ar domain -The domain name. +The primary DNS name. .El .Pp .Nm looks in its configuration for a .Ar domain -section corresponding to the domain given as command line argument. -It then uses that configuration to retrieve a TLS certificate. +section corresponding to the name given as command line argument. +It then uses that configuration to retrieve an X509 certificate. If the certificate already exists and is less than 30 days from expiry, .Nm will attempt to refresh the signature. -Before a certificate can be requested, an account key needs to be +Before a certificate can be requested, an account key pair needs to be created using the .Fl A argument. -The first time a certificate is requested, the RSA key needs to be created with +The first time a certificate is requested, an RSA key pair needs to be +created for it with .Fl D . .Pp Challenges are used to verify that the submitter has access to the @@ -98,21 +99,21 @@ Default challengedir. returns 1 on failure, 2 if the certificates didn't change (up to date), or 0 if certificates were changed (revoked or updated). .Sh EXAMPLES -To initialize a new account and Domain key: +To initialize new account and certificate key pairs: .Pp -.Dl # acme-client -vAD example.com +.Dl # acme-client -vAD www.example.com .Pp -To create and submit a new key for a single domain, assuming that the +To create and submit a key pair for a certificate, assuming that the web server has already been configured to map the challenge directory as above: .Pp -.Dl # acme-client -vD example.com +.Dl # acme-client -vD www.example.com .Pp A daily .Xr cron 8 -job can renew the certificates: +job can renew the certificate: .Pp -.Dl acme-client example.com && rcctl reload httpd +.Dl acme-client www.example.com && rcctl reload httpd .Sh SEE ALSO .Xr openssl 1 , .Xr acme-client.conf 5 , Index: acme-client.conf.5 =================================================================== RCS file: /cvs/src/usr.sbin/acme-client/acme-client.conf.5,v retrieving revision 1.13 diff -u -p -r1.13 acme-client.conf.5 --- acme-client.conf.5 8 Jul 2018 15:41:17 -0000 1.13 +++ acme-client.conf.5 1 Aug 2018 11:44:27 -0000 @@ -32,7 +32,7 @@ file is divided into the following main User-defined variables may be defined and used later, simplifying the configuration file. .It Sy Authorities -Certificate authorities (CAs) that can be contacted via ACME. +Certificate authorities that can be contacted via ACME. .It Sy Domains Certificate specifications. .El @@ -105,27 +105,33 @@ The certificates to be obtained through .It Ic domain Ar name Brq ... Each domain section begins with the .Ic domain -keyword followed by the name to be used as the common name component +keyword followed by the primary DNS name for the certificate. +This name is used as the Common Name (CN) component of the subject of the X.509 certificate. .El .Pp It is followed by a block of options enclosed in curly brackets: .Bl -tag -width Ds .It Ic alternative names Brq ... -Specify a list of alternative names for which the certificate will be valid. -The common name is included automatically if this option is present, +Specify a list of alternative DNS names for which the certificate will +be valid. +The primary DNS name is included automatically if this option is present, but there is no automatic conversion/inclusion between "www." and plain domain name forms. .It Ic domain key Ar file The private key file for which the certificate will be obtained. .It Ic domain certificate Ar file The filename of the certificate that will be issued. +This is optional if +.Ar domain full chain certificate +is specified. .It Ic domain chain certificate Ar file The filename in which to store the certificate chain that will be returned by the certificate authority. It needs to be in the same directory as the .Ar domain certificate (or in a subdirectory) and can be specified as a relative or absolute path. +This setting is optional. .It Ic domain full chain certificate Ar file The filename in which to store the full certificate chain that will be returned by the certificate authority. @@ -137,10 +143,14 @@ This is a combination of the and the .Ar domain chain certificate in one file, and is required by most browsers. +This is optional if +.Ar domain certificate +is specified. .It Ic sign with Ar authority The certificate authority (as declared above in the .Sx AUTHORITIES section) to use. +If this setting is absent, the first authority specified is used. .It Ic challengedir Ar path The directory in which the challenge file will be stored. If it is not specified, a default of
