From: William Lallemand Date: Tue, 21 May 2024 09:51:56 +0000 (+0200) Subject: DOC: configuration: rework the crt-store load documentation X-Git-Tag: v3.0-dev13~63 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=4bb6ea5d0016b91d1e98a49cce956a60b85e517b;p=thirdparty%2Fhaproxy.git DOC: configuration: rework the crt-store load documentation The load keyword from the documentation has its own section to be readable (like the server or bind options section). The ocsp-update keyword was move from the bind section to the crt-list load one. --- diff --git a/doc/configuration.txt b/doc/configuration.txt index f2e7494bf7..b17b33a471 100644 --- a/doc/configuration.txt +++ b/doc/configuration.txt @@ -60,6 +60,7 @@ Summary 3.10. Log forwarding 3.11. HTTPClient tuning 3.12. Certificate Storage +3.12.1. Load options 4. Proxies 4.1. Proxy keywords matrix @@ -4814,39 +4815,8 @@ key-base section is ignored. load [crt ] [param*] - Load SSL files in the certificate storage. - - Arguments: - - alias Optional argument. Allow to name the certificate with an - alias, so it can be referenced with it in the - configuration. An alias must be prefixed with '@/' when - called elsewhere in the configuration. - - crt This argument is mandatory, it loads a PEM which must - contain the public certificate but could also contain - the intermediate certificates and the private key. - If no private key is provided in this file, a key can be - provided with the "key" keyword. - - key This argument is optional. Load a private key in PEM - format. If a private key was already defined in "crt", - it will overwrite it. - - ocsp This argument is optional, it loads an OCSP response in - DER format. It can be updated with the CLI. - - issuer This argument is optional. Load the OCSP issuer in PEM - format. In order to identify which certificate an OCSP - Response applies to, the issuer's certificate is necessary. - If the issuer's certificate is not found in the "crt" file, - it could be loaded from a file with this argument. - - sctl This argument is optional. Support for Certificate - Transparency (RFC6962) TLS extension is enabled. The file - must contain a valid Signed Certificate Timestamp List, - as described in RFC. File is parsed to check basic syntax, - but no signatures are verified. + Load SSL files in the certificate storage. For the parameter list, see section + "3.12.1. Load options" Example: @@ -4866,6 +4836,139 @@ Example: frontend in2 bind *:443 ssl crt "@web/site1" crt "site2.crt" crt "@web/site3" crt "@web/site4.crt" +3.12.1. Load options +-------------------- + +Load SSL files in the certificate storage. The load keyword can take multiple +parameters which are listed below. These keywords are also usable in a +crt-list. + +crt + This argument is mandatory, it loads a PEM which must contain the public + certificate but could also contain the intermediate certificates and the + private key. If no private key is provided in this file, a key can be provided + with the "key" keyword. + +alias + Optional argument. Allow to name the certificate with an alias, so it can be + referenced with it in the configuration. An alias must be prefixed with '@/' + when called elsewhere in the configuration. + +key + This argument is optional. Load a private key in PEM format. If a private key + was already defined in "crt", it will overwrite it. + +ocsp + This argument is optional, it loads an OCSP response in DER format. It can + be updated with the CLI. + +issuer + This argument is optional. Load the OCSP issuer in PEM format. In order to + identify which certificate an OCSP Response applies to, the issuer's + certificate is necessary. If the issuer's certificate is not found in the + "crt" file, it could be loaded from a file with this argument. + +sctl + This argument is optional. Support for Certificate Transparency (RFC6962) TLS + extension is enabled. The file must contain a valid Signed Certificate + Timestamp List, as described in RFC. File is parsed to check basic syntax, + but no signatures are verified. + +ocsp-update [ off | on ] + Enable automatic OCSP response update when set to 'on', disable it otherwise. + Its value defaults to 'off'. + To enable the OCSP auto update on a bind line, you can use this option in a + crt-store or you can use the global option "tune.ocsp-update.mode". + If a given certificate is used in multiple crt-lists with different values of + the 'ocsp-update' set, an error will be raised. Likewise, if a certificate + inherits from the global option on a bind line and has an incompatible + explicit 'ocsp-update' option set in a crt-list, the same error will be + raised. + + Examples: + + Here is an example configuration enabling it with a crt-list: + + haproxy.cfg: + frontend fe + bind :443 ssl crt-list haproxy.list + + haproxy.list: + server_cert.pem [ocsp-update on] foo.bar + + Here is an example configuration enabling it with a crt-store: + + haproxy.cfg: + + crt-store + load crt foobar.pem ocsp-update on + + frontend fe + bind :443 ssl crt foobar.pem + + When the option is set to 'on', we will try to get an ocsp response whenever + an ocsp uri is found in the frontend's certificate. The only limitation of + this mode is that the certificate's issuer will have to be known in order for + the OCSP certid to be built. + Each OCSP response will be updated at least once an hour, and even more + frequently if a given OCSP response has an expire date earlier than this one + hour limit. A minimum update interval of 5 minutes will still exist in order + to avoid updating too often responses that have a really short expire time or + even no 'Next Update' at all. Because of this hard limit, please note that + when auto update is set to 'on', any OCSP response loaded during init will + not be updated until at least 5 minutes, even if its expire time ends before + now+5m. This should not be too much of a hassle since an OCSP response must + be valid when it gets loaded during init (its expire time must be in the + future) so it is unlikely that this response expires in such a short time + after init. + On the other hand, if a certificate has an OCSP uri specified and no OCSP + response, setting this option to 'on' for the given certificate will ensure + that the OCSP response gets fetched automatically right after init. + The default minimum and maximum delays (5 minutes and 1 hour respectively) + can be configured by the "tune.ssl.ocsp-update.maxdelay" and + "tune.ssl.ocsp-update.mindelay" global options. + + Whenever an OCSP response is updated by the auto update task or following a + call to the "update ssl ocsp-response" CLI command, a dedicated log line is + emitted. It follows a dedicated format that contains the following header + "" and is followed by specific OCSP-related information: + - the path of the corresponding frontend certificate + - a numerical update status + - a textual update status + - the number of update failures for the given response + - the number of update successes for the givan response + See "show ssl ocsp-updates" CLI command for a full list of error codes and + error messages. This line is emitted regardless of the success or failure of + the concerned OCSP response update. + The OCSP request/response is sent and received through an http_client + instance that has the dontlog-normal option set and that uses the regular + HTTP log format in case of error (unreachable OCSP responder for instance). + If such an error occurs, another log line that contains HTTP-related + information will then be emitted alongside the "regular" OCSP one (which will + likely have "HTTP error" as text status). But if a purely HTTP error happens + (unreachable OCSP responder for instance), an extra log line that follows the + regular HTTP log-format will be emitted. + Here are two examples of such log lines, with a successful OCSP update log + line first and then an example of an HTTP error with the two different lines + (lines were spit and the URL was shortened for readability): + <133>Mar 6 11:16:53 haproxy[14872]: /path_to_cert/foo.pem 1 \ + "Update successful" 0 1 + + <133>Mar 6 11:18:55 haproxy[14872]: /path_to_cert/bar.pem 2 \ + "HTTP error" 1 0 + <133>Mar 6 11:18:55 haproxy[14872]: -:- [06/Mar/2023:11:18:52.200] \ + -/- 2/0/-1/-1/3009 503 217 - - SC-- 0/0/0/0/3 0/0 {} \ + "GET http://127.0.0.1:12345/MEMwQT HTTP/1.1" + + Troubleshooting: + A common error that can happen with let's encrypt certificates is if the DNS + resolution provides an IPv6 address and your system does not have a valid + outgoing IPv6 route. In such a case, you can either create the appropriate + route or set the "httpclient.resolvers.prefer ipv4" option in the global + section. + In case of "OCSP response check failure" error, you might want to check that + the issuer certificate that you provided is valid. + 4. Proxies ---------- @@ -16255,91 +16358,6 @@ npn at the time of writing this. It is possible to enable both NPN and ALPN though it probably doesn't make any sense out of testing. -ocsp-update [ off | on ] (crt-list only) - Enable automatic OCSP response update when set to 'on', disable it otherwise. - Its value defaults to 'off'. - Please note that for now, this option can only be used in a crt-list line, it - cannot be used directly on a bind line. It lies in this "Bind options" - section because it is still a frontend option. For now, the only way to - enable OCSP auto update on a bind line certificate is via the global option - "tune.ocsp-update.mode". - If a given certificate is used in multiple crt-lists with different values of - the 'ocsp-update' set, an error will be raised. Likewise, if a certificate - inherits from the global option on a bind line and has an incompatible - explicit 'ocsp-update' option set in a crt-list, the same error will be - raised. - Here is an example configuration enabling it: - - haproxy.cfg: - frontend fe - bind :443 ssl crt-list haproxy.list - - haproxy.list: - server_cert.pem [ocsp-update on] foo.bar - - When the option is set to 'on', we will try to get an ocsp response whenever - an ocsp uri is found in the frontend's certificate. The only limitation of - this mode is that the certificate's issuer will have to be known in order for - the OCSP certid to be built. - Each OCSP response will be updated at least once an hour, and even more - frequently if a given OCSP response has an expire date earlier than this one - hour limit. A minimum update interval of 5 minutes will still exist in order - to avoid updating too often responses that have a really short expire time or - even no 'Next Update' at all. Because of this hard limit, please note that - when auto update is set to 'on', any OCSP response loaded during init will - not be updated until at least 5 minutes, even if its expire time ends before - now+5m. This should not be too much of a hassle since an OCSP response must - be valid when it gets loaded during init (its expire time must be in the - future) so it is unlikely that this response expires in such a short time - after init. - On the other hand, if a certificate has an OCSP uri specified and no OCSP - response, setting this option to 'on' for the given certificate will ensure - that the OCSP response gets fetched automatically right after init. - The default minimum and maximum delays (5 minutes and 1 hour respectively) - can be configured by the "tune.ssl.ocsp-update.maxdelay" and - "tune.ssl.ocsp-update.mindelay" global options. - - Whenever an OCSP response is updated by the auto update task or following a - call to the "update ssl ocsp-response" CLI command, a dedicated log line is - emitted. It follows a dedicated format that contains the following header - "" and is followed by specific OCSP-related information: - - the path of the corresponding frontend certificate - - a numerical update status - - a textual update status - - the number of update failures for the given response - - the number of update successes for the givan response - See "show ssl ocsp-updates" CLI command for a full list of error codes and - error messages. This line is emitted regardless of the success or failure of - the concerned OCSP response update. - The OCSP request/response is sent and received through an http_client - instance that has the dontlog-normal option set and that uses the regular - HTTP log format in case of error (unreachable OCSP responder for instance). - If such an error occurs, another log line that contains HTTP-related - information will then be emitted alongside the "regular" OCSP one (which will - likely have "HTTP error" as text status). But if a purely HTTP error happens - (unreachable OCSP responder for instance), an extra log line that follows the - regular HTTP log-format will be emitted. - Here are two examples of such log lines, with a successful OCSP update log - line first and then an example of an HTTP error with the two different lines - (lines were spit and the URL was shortened for readability): - <133>Mar 6 11:16:53 haproxy[14872]: /path_to_cert/foo.pem 1 \ - "Update successful" 0 1 - - <133>Mar 6 11:18:55 haproxy[14872]: /path_to_cert/bar.pem 2 \ - "HTTP error" 1 0 - <133>Mar 6 11:18:55 haproxy[14872]: -:- [06/Mar/2023:11:18:52.200] \ - -/- 2/0/-1/-1/3009 503 217 - - SC-- 0/0/0/0/3 0/0 {} \ - "GET http://127.0.0.1:12345/MEMwQT HTTP/1.1" - - Troubleshooting: - A common error that can happen with let's encrypt certificates is if the DNS - resolution provides an IPv6 address and your system does not have a valid - outgoing IPv6 route. In such a case, you can either create the appropriate - route or set the "httpclient.resolvers.prefer ipv4" option in the global - section. - In case of "OCSP response check failure" error, you might want to check that - the issuer certificate that you provided is valid. - prefer-client-ciphers Use the client's preference when selecting the cipher suite, by default the server's preference is enforced. This option is also available on