DOCS: Add explanation of intermediate certs to crt paramater

This change makes the "crt" block of the documentation easier to use
for those not clear on what needs to go in what file, specifically for
those using CAs that require intermediate certificates.

diff --git a/doc/configuration.txt b/doc/configuration.txt
index 805a7ebd2f3a3e4db4c34e630aa7677d3553078b..57ef9c4f998f0b3e4ca763200d885d688b885b18 100644 (file)
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -7174,29 +7174,45 @@ crl-file <crlfile>
   to verify client's certificate.
 
 crt <cert>
-  This setting is only available when support for OpenSSL was built in.
-  It designates a PEM file from which to load both a certificate and the
-  associated private key. This file can be built by concatenating both PEM
-  files into one. If the OpenSSL used supports Diffie-Hellman, parameters
-  present in this file are also loaded. If a directory name is used instead of a
-  PEM file, then all files found in that directory will be loaded. This
-  directive may be specified multiple times in order to load certificates from
-  multiple files or directories. The certificates will be presented to clients
-  who provide a valid TLS Server Name Indication field matching one of their CN
-  or alt subjects. Wildcards are supported, where a wildcard character '*' is
-  used instead of the first hostname component (eg: *.example.org matches
-  www.example.org but not www.sub.example.org). If no SNI is provided by the
-  client or if the SSL library does not support TLS extensions, or if the client
-  provides and SNI which does not match any certificate, then the first loaded
-  certificate will be presented. This means that when loading certificates from
-  a directory, it is highly recommended to load the default one first as a file.
+  This setting is only available when support for OpenSSL was built in. It
+  designates a PEM file containing both the required certificates and any
+  associated private keys. This file can be built by concatenating multiple
+  PEM files into one (e.g. cat cert.pem key.pem > combined.pem). If your CA
+  requires an intermediate certificate, this can also be concatenated into this
+  file.
+
+  If the OpenSSL used supports Diffie-Hellman, parameters present in this file
+  are loaded.
+
+  If a directory name is used instead of a PEM file, then all files found in
+  that directory will be loaded. This directive may be specified multiple times
+  in order to load certificates from multiple files or directories. The
+  certificates will be presented to clients who provide a valid TLS Server Name
+  Indication field matching one of their CN or alt subjects. Wildcards are
+  supported, where a wildcard character '*' is used instead of the first
+  hostname component (eg: *.example.org matches www.example.org but not
+  www.sub.example.org).
+
+  If no SNI is provided by the client or if the SSL library does not support
+  TLS extensions, or if the client provides an SNI hostname which does not
+  match any certificate, then the first loaded certificate will be presented.
+  This means that when loading certificates from a directory, it is highly
+  recommended to load the default one first as a file.
+
   Note that the same cert may be loaded multiple times without side effects.
 
+  Some CAs (such as Godaddy) offer a drop down list of server types that do not
+  include HAProxy when obtaining a certificate. If this happens be sure to
+  choose a webserver that the CA believes requires a intermediate CA (for
+  Godaddy, selection Apache Tomcat will get the correct bundle, but many
+  others, e.g. nginx, result in a wrong bundle that will not work for some
+  clients).
+
 crt-ignore-err <errors>
-  This setting is only available when support for OpenSSL was built in.
-  Sets a comma separated list of errorIDs to ignore during verify at depth == 0.
-  If set to 'all', all errors are ignored. SSL handshake is not abored if an
-  error is ignored.
+  This setting is only available when support for OpenSSL was built in. Sets a
+  comma separated list of errorIDs to ignore during verify at depth == 0.  If
+  set to 'all', all errors are ignored. SSL handshake is not abored if an error
+  is ignored.
 
 defer-accept
   Is an optional keyword which is supported only on certain Linux kernels. It