DOC: crt: advise to move away from cert bundle

especially when starting to use `new ssl cert` runtime API, it might
become a bit confusing for users to mix bundle and single cert,
especially when it comes to use the commit command:
e.g.:
- start the process with `crt` loading a bundle
- use `set ssl cert my_cert.pem.ecdsa`: API detects it as a replacement
  of a bundle.
- `commit` has to be done on the bundle: `commit ssl cert my_cert.pem`

however:
- add a new cert: `new ssl cert my_cert.pem.rsa`: added as a single
  certificate
- `commit` has to be done on the certificate: `commit ssl cert
  my_cert.pem.rsa`

this should resolve github issue #872

this should probably be backported in >= v2.2 in order to encourage
people to move away from bundle certificates loading.

Signed-off-by: William Dauchy <w.dauchy@criteo.com>

diff --git a/doc/configuration.txt b/doc/configuration.txt
index 97ff2e499651da9c5240d4cb8f8508f52b16097f..87f35e9846ad9dfffec2d26232f85c348905a435 100644 (file)
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -12560,10 +12560,15 @@ crt <cert>
   connecting with "ecdsa.example.com" will only be able to use ECDSA cipher
   suites. With BoringSSL and Openssl >= 1.1.1 multi-cert is natively supported,
   no need to bundle certificates. ECDSA certificate will be preferred if client
-  support it.
+  supports it.
 
   If a directory name is given as the <cert> argument, haproxy will
   automatically search and load bundled files in that directory.
+  It is however recommended to move away from bundle loading, especially if you
+  want to use the runtime API to load new certificate which does not support
+  bundle. A recommended way to migrate is to set `ssl-load-extra-file`
+  parameter to `none` in global config so that each certificate is loaded as a
+  single one.
 
   OSCP files (.ocsp) and issuer files (.issuer) are supported with multi-cert
   bundling. Each certificate can have its own .ocsp and .issuer file. At this

diff --git a/doc/management.txt b/doc/management.txt
index adbad95d346d4bf46c80a27cad9b88038da4e9b8..42e8ddbcab5f26061ff3c456fae1dc1a6339849a 100644 (file)
--- a/doc/management.txt
+++ b/doc/management.txt
@@ -1725,6 +1725,10 @@ new ssl cert <filename>
   Create a new empty SSL certificate store to be filled with a certificate and
   added to a directory or a crt-list. This command should be used in
   combination with "set ssl cert" and "add ssl crt-list".
+  Note that bundle certificates are not supported; it is recommended to use
+  `ssl-load-extra-file none` in global config to avoid loading certificates as
+  bundle and then mixing with single certificates in the runtime API. This will
+  avoid confusion, especailly when it comes to the `commit` command.
 
 prompt
   Toggle the prompt at the beginning of the line and enter or leave interactive