Document wildcards, PREFERRED_CHAIN and FULL_CHAIN_INCLUDE_ROOT

README.md

@@ -1,21 +1,23 @@
-# getssl
+# getssl <!-- omit in toc -->
 
 ![Run all tests](https://github.com/srvrco/getssl/workflows/Run%20all%20tests/badge.svg) ![shellcheck](https://github.com/srvrco/getssl/workflows/shellcheck/badge.svg)
 
 Obtain SSL certificates from the letsencrypt.org ACME server. Suitable
 for automating the process on remote servers.
 
-## Table of Contents
-
+## Table of Contents <!-- omit in toc -->
 - [Features](#features)
 - [Installation](#installation)
 - [Overview](#overview)
 - [Getting started](#getting-started)
+- [Wildcard certificates](#wildcard-certificates)
 - [Automating updates](#automating-updates)
 - [Structure](#structure)
 - [Server-Types](#server-types)
 - [Revoke a certificate](#revoke-a-certificate)
 - [Elliptic curve keys](#elliptic-curve-keys)
+- [Preferred Chain](#preferred-chain)
+- [Full chain](#full-chain)
 - [Issues / problems / help](#issues--problems--help)
 
 ## Features
@@ -163,9 +165,35 @@ Change the server in your config file to get a fully valid certificate.
 dns. The certificate can be used (and checked with getssl) on alternate
 ports.
 
+## Wildcard certificates
+
+`getssl` supports creating wildcard certificates, i.e. _*.example.com_ which allows a single certificate to be used for any domain under *example.com*, e.g. *www.example.com*, *mail.example.com*.  These must be validated using the dns-01 method.
+
+A *partial* example `getssl.cfg` file is:
+
+```sh
+VALIDATE_VIA_DNS=true
+export CPANEL_USERNAME=''
+export CPANEL_URL='https://www.cpanel.host:2083'
+export CPANEL_APITOKEN='1ABC2DEF3GHI4JKL5MNO6PQR7STU8VWX9YZA'
+DNS_ADD_COMMAND=/home/root/getssl/dns_scripts/dns_add_cpanel
+DNS_DEL_COMMAND=/home/root/getssl/dns_scripts/dns_del_cpanel
+```
+
+Create the wildcard certificate (need to use quotes to prevent globbing):
+
+```sh
+getssl "*.example.domain"
+```
+
+You can renew the certificate using `getssl -a` to renew all configured certificates.
+
+You can also specify additional domains in the `SANS` line, e.g. `SANS="www.test.example.com"`.
+This cannot contain any of the domains which would be covered by the wildcard certificate.
+
 ## Automating updates
 
-I use the following cron
+I use the following **cron** job
 
 ```cron
 23  5 * * * /root/scripts/getssl -u -a -q
@@ -353,6 +381,34 @@ key (different of course, don't use the same key for both). prime256v1
 secp521r1 (NIST P-521) is included in the code, but not currently
 supported by Let's Encrypt).
 
+## Preferred Chain
+
+If a CA offers multiple chains then it is possible to select which chain
+is used by using the `PREFERRED_CHAIN` variable in `getssl.cfg` or specifying
+ `--preferred-chain` in the call to `getssl`
+
+This uses wildcard matching so requesting "X1" returns the first certificate
+returned by the CA which contains the text "X1",  Note you may need to escape
+any characters which special characters, e.g.
+` PREFERRED_CHAIN="\(STAGING\) Doctored Durian Root CA X3"`
+
+* Staging options are: "(STAGING) Doctored Durian Root CA X3" and "(STAGING) Pretend Pear X1"
+* Production options are: "ISRG Root X1" and "ISRG Root X2"
+
+## Full chain
+
+Some servers, including those that use Java keystores, will not accept a server certificate if it cannot valid the full chain of signers.
+
+Specifically, Nutanix Prism (Element and Central) will not accept the `fullchain.crt` until the root CA's certificate has been appended to it manually.
+
+If your application requires the full chain, i.e. including the
+root certificate of the CA, then this can be included in the `fullchain.crt` file by
+adding the following line to `getssl.cfg`
+
+```sh
+FULL_CHAIN_INCLUDE_ROOT="true"
+```
+
 ## Issues / problems / help
 
 If you have any issues, please log them at <https://github.com/srvrco/getssl/issues>