|
2 | 2 | <html lang="en"> |
3 | 3 | <head> |
4 | 4 | <meta charset="utf-8" /> |
5 | | - <title>HAProxy version 3.2-dev9-33 - Configuration Manual</title> |
| 5 | + <title>HAProxy version 3.2-dev9-37 - Configuration Manual</title> |
6 | 6 | <link href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.min.css" rel="stylesheet" /> |
7 | 7 | <link href="https://raw.githubusercontent.com/thomaspark/bootswatch/v3.3.7/cerulean/bootstrap.min.css" rel="stylesheet" /> |
8 | 8 | <link href="../css/page.css?0.4.2-15" rel="stylesheet" /> |
|
4488 | 4488 | You can use <strong>left</strong> and <strong>right</strong> arrow keys to navigate between chapters.<br> |
4489 | 4489 | </p> |
4490 | 4490 | <p class="text-right"> |
4491 | | - <small>Converted with <a href="https://github.com/cbonte/haproxy-dconv">haproxy-dconv</a> v<b>0.4.2-15</b> on <b>2025/04/03</b></small> |
| 4491 | + <small>Converted with <a href="https://github.com/cbonte/haproxy-dconv">haproxy-dconv</a> v<b>0.4.2-15</b> on <b>2025/04/08</b></small> |
4492 | 4492 | </p> |
4493 | 4493 | </div> |
4494 | 4494 | <!-- /.sidebar --> |
|
4499 | 4499 | <div class="text-center"> |
4500 | 4500 | <h1><a href="http://www.haproxy.org/" title="HAProxy"><img src="../img/HAProxyCommunityEdition_60px.png?0.4.2-15" /></a></h1> |
4501 | 4501 | <h2>Configuration Manual</h2> |
4502 | | - <p><strong>version 3.2-dev9-33</strong></p> |
| 4502 | + <p><strong>version 3.2-dev9-37</strong></p> |
4503 | 4503 | <p> |
4504 | 4504 | 2025/04/02<br> |
4505 | 4505 |
|
@@ -21453,83 +21453,118 @@ <h2 id="chapter-5.1" data-target="5.1"><small><a class="small" href="#5.1">5.1.< |
21453 | 21453 |
|
21454 | 21454 | <crtfile> [\[<sslbindconf> ...\]] [[!]<snifilter> ...] |
21455 | 21455 |
|
21456 | | -sslbindconf supports the following keywords from the bind line |
21457 | | -(see Section 5.1. Bind options): |
21458 | | - |
21459 | | -- <a href="#allow-0rtt">allow-0rtt</a> |
21460 | | -- <a href="#alpn">alpn</a> |
21461 | | -- <a href="#ca-file">ca-file</a> |
21462 | | -- <a href="#ca-verify-file">ca-verify-file</a> |
21463 | | -- <a href="#ciphers">ciphers</a> |
21464 | | -- <a href="#ciphersuites">ciphersuites</a> |
21465 | | -- <a href="#client-sigalgs">client-sigalgs</a> |
21466 | | -- <a href="#crl-file">crl-file</a> |
21467 | | -- <a href="#curves">curves</a> |
21468 | | -- <a href="#ecdhe">ecdhe</a> |
21469 | | -- <a href="#no-alpn">no-alpn</a> |
21470 | | -- <a href="#no-ca-names">no-ca-names</a> |
21471 | | -- <a href="#npn">npn</a> |
21472 | | -- <a href="#sigalgs">sigalgs</a> |
21473 | | -- <a href="#ssl-min-ver">ssl-min-ver</a> |
21474 | | -- <a href="#ssl-max-ver">ssl-max-ver</a> |
21475 | | -- <a href="#verify">verify</a> |
21476 | | - |
21477 | | -sslbindconf also supports the following keywords from the crt-store load |
21478 | | -keyword (see Section 3.12.1. Load options): |
21479 | | - |
21480 | | -- <a href="#crt">crt</a> |
21481 | | -- <a href="#key">key</a> |
21482 | | -- <a href="#ocsp">ocsp</a> |
21483 | | -- <a href="#issuer">issuer</a> |
21484 | | -- <a href="#sctl">sctl</a> |
21485 | | -- <a href="#ocsp-update">ocsp-update</a> |
21486 | | - |
21487 | | -It overrides the configuration set in bind line for the certificate. |
21488 | | - |
21489 | | -Wildcards are supported in the SNI filter. Negative filter are also supported, |
21490 | | -useful in combination with a wildcard filter to exclude a particular SNI, or |
21491 | | -after the first certificate to exclude a pattern from its CN or Subject Alt |
21492 | | -Name (SAN). The certificates will be presented to clients who provide a valid |
21493 | | -TLS Server Name Indication field matching one of the SNI filters. If no SNI |
21494 | | -filter is specified, the CN and SAN are used. This directive may be specified |
21495 | | -multiple times. See the "<span class="dropdown"><a class="dropdown-toggle" data-toggle="dropdown" href="#">crt<span class="caret"></span></a><ul class="dropdown-menu"><li class="dropdown-header">This keyword is available in sections :</li><li><a href="#crt%20%28Load%20options%29">Load options</a></li><li><a href="#crt%20%28Bind%20options%29">Bind options</a></li><li><a href="#crt%20%28Server%20and%20default-server%20options%29">Server and default-server options</a></li></ul></span>" option for more information. The default |
21496 | | -certificate is still needed to meet OpenSSL expectations. If it is not used, |
21497 | | -the 'strict-sni' option may be used. |
21498 | | - |
21499 | | -Multi-cert bundling (see "<a href="#ssl-load-extra-files">ssl-load-extra-files</a>") is supported with crt-list, |
21500 | | -as long as only the base name is given in the crt-list. SNI filter will do |
21501 | | -the same work on all bundled certificates. |
21502 | | - |
21503 | 21456 | Empty lines as well as lines beginning with a hash ('#') will be ignored. |
21504 | 21457 |
|
21505 | | -The first declared certificate of a bind line is used as the default |
21506 | | -certificate, either from crt or crt-list option, which HAProxy should use in |
21507 | | -the TLS handshake if no other certificate matches. This certificate will also |
21508 | | -be used if the provided SNI matches its CN or SAN, even if a matching SNI |
21509 | | -filter is found on any crt-list. The SNI filter !* can be used after the first |
21510 | | -declared certificate to not include its CN and SAN in the SNI tree, so it will |
21511 | | -never match except if no other certificate matches. This way the first |
21512 | | -declared certificate act as a fallback. It is also possible to declare a '*' |
21513 | | -filter, which will allow to chose this certificate as default. When multiple |
21514 | | -default certificates are defined, HAProxy is able to chose the right ECDSA or |
21515 | | -RSA one depending on what the client supports. |
21516 | | - |
21517 | | -When no ALPN is set, the "<span class="dropdown"><a class="dropdown-toggle" data-toggle="dropdown" href="#">bind<span class="caret"></span></a><ul class="dropdown-menu"><li class="dropdown-header">This keyword is available in sections :</li><li><a href="#bind%20%28Log%20forwarding%29">Log forwarding</a></li><li><a href="#bind%20%28Peers%29">Peers</a></li><li><a href="#bind%20%28Alphabetically%20sorted%20keywords%20reference%29">Alphabetically sorted keywords reference</a></li></ul></span>" line's default one is used. If a "<span class="dropdown"><a class="dropdown-toggle" data-toggle="dropdown" href="#">bind<span class="caret"></span></a><ul class="dropdown-menu"><li class="dropdown-header">This keyword is available in sections :</li><li><a href="#bind%20%28Log%20forwarding%29">Log forwarding</a></li><li><a href="#bind%20%28Peers%29">Peers</a></li><li><a href="#bind%20%28Alphabetically%20sorted%20keywords%20reference%29">Alphabetically sorted keywords reference</a></li></ul></span>" line |
21518 | | -has no "<a href="#no-alpn">no-alpn</a>", "<span class="dropdown"><a class="dropdown-toggle" data-toggle="dropdown" href="#">alpn<span class="caret"></span></a><ul class="dropdown-menu"><li class="dropdown-header">This keyword is available in sections :</li><li><a href="#alpn%20%28Bind%20options%29">Bind options</a></li><li><a href="#alpn%20%28Server%20and%20default-server%20options%29">Server and default-server options</a></li></ul></span>" nor "<span class="dropdown"><a class="dropdown-toggle" data-toggle="dropdown" href="#">npn<span class="caret"></span></a><ul class="dropdown-menu"><li class="dropdown-header">This keyword is available in sections :</li><li><a href="#npn%20%28Bind%20options%29">Bind options</a></li><li><a href="#npn%20%28Server%20and%20default-server%20options%29">Server and default-server options</a></li></ul></span>" set, a default value will be used |
21519 | | -depending on the protocol (see "<span class="dropdown"><a class="dropdown-toggle" data-toggle="dropdown" href="#">alpn<span class="caret"></span></a><ul class="dropdown-menu"><li class="dropdown-header">This keyword is available in sections :</li><li><a href="#alpn%20%28Bind%20options%29">Bind options</a></li><li><a href="#alpn%20%28Server%20and%20default-server%20options%29">Server and default-server options</a></li></ul></span>" above). However if the "<span class="dropdown"><a class="dropdown-toggle" data-toggle="dropdown" href="#">bind<span class="caret"></span></a><ul class="dropdown-menu"><li class="dropdown-header">This keyword is available in sections :</li><li><a href="#bind%20%28Log%20forwarding%29">Log forwarding</a></li><li><a href="#bind%20%28Peers%29">Peers</a></li><li><a href="#bind%20%28Alphabetically%20sorted%20keywords%20reference%29">Alphabetically sorted keywords reference</a></li></ul></span>" line has |
21520 | | -a different default, or explicitly disables ALPN using "<a href="#no-alpn">no-alpn</a>", it is |
21521 | | -possible to force a specific value for a certificate. |
21522 | | - |
21523 | | -crt-list file example: |
21524 | | - cert1.pem !* |
21525 | | - # comment |
21526 | | - cert2.pem [alpn h2,http/1.1] |
21527 | | - certW.pem *.domain.tld !secure.domain.tld |
21528 | | - certS.pem [curves X25519:P-256 ciphers ECDHE-ECDSA-AES256-GCM-SHA384] secure.domain.tld |
21529 | | - default.pem.rsa * |
21530 | | - default.pem.ecdsa * |
21531 | | - foo.crt [key bar.pem ocsp foo.ocsp ocsp-update on] foo.bar.com |
21532 | | -</pre><a class="anchor" name="default-crt"></a><a class="anchor" name="5-default-crt"></a><a class="anchor" name="5.1-default-crt"></a><a class="anchor" name="default-crt (Bind and server options)"></a><a class="anchor" name="default-crt (Bind options)"></a><div class="keyword"><b><a class="anchor" name="default-crt"></a><a href="#5.1-default-crt">default-crt</a></b> <span style="color: #080"><cert></span></div><pre class="text">This option does the same as the "<span class="dropdown"><a class="dropdown-toggle" data-toggle="dropdown" href="#">crt<span class="caret"></span></a><ul class="dropdown-menu"><li class="dropdown-header">This keyword is available in sections :</li><li><a href="#crt%20%28Load%20options%29">Load options</a></li><li><a href="#crt%20%28Bind%20options%29">Bind options</a></li><li><a href="#crt%20%28Server%20and%20default-server%20options%29">Server and default-server options</a></li></ul></span>" option, with the difference that this |
| 21458 | +The crt-list can be manipulated dynamically over the stats socket. (See "add |
| 21459 | +ssl crt-list", "del ssl crt-list", "show ssl crt-list" in the management |
| 21460 | +guide). |
| 21461 | + |
| 21462 | +crt-list are usually dedicated files, however a directory loaded with the "<span class="dropdown"><a class="dropdown-toggle" data-toggle="dropdown" href="#">crt<span class="caret"></span></a><ul class="dropdown-menu"><li class="dropdown-header">This keyword is available in sections :</li><li><a href="#crt%20%28Load%20options%29">Load options</a></li><li><a href="#crt%20%28Bind%20options%29">Bind options</a></li><li><a href="#crt%20%28Server%20and%20default-server%20options%29">Server and default-server options</a></li></ul></span>" |
| 21463 | +directive is represented internally as a crt-list. The "<a href="#ssl-f-use">ssl-f-use</a>" directive |
| 21464 | +in a frontend also declares a crt-list linked to this frontend. |
| 21465 | + |
| 21466 | +crtfile: |
| 21467 | + |
| 21468 | + This is the filename of the certificate, or an identifier if it was declared |
| 21469 | + elsewhere (over the CLI or in a crt-store with an alias for example). |
| 21470 | + |
| 21471 | + It is possible to use the same <crtfile> on multiple lines with different |
| 21472 | + options and filters. |
| 21473 | + |
| 21474 | + Multi-cert bundling (see "<a href="#ssl-load-extra-files">ssl-load-extra-files</a>") is supported in a |
| 21475 | + crt-list, as long as only the base name is given in <crtfile>. HAProxy |
| 21476 | + will duplicate the crt-list line internally, adding an algorithm extension |
| 21477 | + (.rsa, .ecdsa, .dsa) when loading the file. |
| 21478 | + |
| 21479 | +sslbindconf: |
| 21480 | + |
| 21481 | + <sslbindconf> supports the following keywords from the bind line (see |
| 21482 | + Section 5.1. Bind options): |
| 21483 | + |
| 21484 | + - <a href="#allow-0rtt">allow-0rtt</a> |
| 21485 | + - <a href="#alpn">alpn</a> |
| 21486 | + - <a href="#ca-file">ca-file</a> |
| 21487 | + - <a href="#ca-verify-file">ca-verify-file</a> |
| 21488 | + - <a href="#ciphers">ciphers</a> |
| 21489 | + - <a href="#ciphersuites">ciphersuites</a> |
| 21490 | + - <a href="#client-sigalgs">client-sigalgs</a> |
| 21491 | + - <a href="#crl-file">crl-file</a> |
| 21492 | + - <a href="#curves">curves</a> |
| 21493 | + - <a href="#ecdhe">ecdhe</a> |
| 21494 | + - <a href="#no-alpn">no-alpn</a> |
| 21495 | + - <a href="#no-ca-names">no-ca-names</a> |
| 21496 | + - <a href="#npn">npn</a> |
| 21497 | + - <a href="#sigalgs">sigalgs</a> |
| 21498 | + - <a href="#ssl-min-ver">ssl-min-ver</a> |
| 21499 | + - <a href="#ssl-max-ver">ssl-max-ver</a> |
| 21500 | + - <a href="#verify">verify</a> |
| 21501 | + |
| 21502 | + <sslbindconf> also supports the following keywords from the crt-store load |
| 21503 | + keyword (see Section 3.12.1. Load options): |
| 21504 | + |
| 21505 | + - <a href="#crt">crt</a> |
| 21506 | + - <a href="#key">key</a> |
| 21507 | + - <a href="#ocsp">ocsp</a> |
| 21508 | + - <a href="#issuer">issuer</a> |
| 21509 | + - <a href="#sctl">sctl</a> |
| 21510 | + - <a href="#ocsp-update">ocsp-update</a> |
| 21511 | + |
| 21512 | + Parameters from the bind line are inherited in <sslbindconf>, if none were |
| 21513 | + specified, the default options are inherited, the parameters specified in |
| 21514 | + <sslbindconf> overwrite those inherited settings. |
| 21515 | + |
| 21516 | +snifilter: |
| 21517 | + |
| 21518 | + When the <snifilter> parameter is used on a crt-list line, the CN and SAN |
| 21519 | + are not used anymore to select the certificate on this line during the |
| 21520 | + handshake but the <snifilter> is used instead. |
| 21521 | + |
| 21522 | + <snifilter> is a list of entries separated by spaces. This list can contain |
| 21523 | + domains, or wildcards. The wildcards are in wildcard DNS format, using a |
| 21524 | + single asterisk as the first character of the entry. It is possible to |
| 21525 | + exclude a domain from a wildcard with a negative filter by specifying a '!' |
| 21526 | + in front of a single domain. Having a ! in front of a * is ignored. Having |
| 21527 | + negative filters without a wildcard on the same line is not supported as |
| 21528 | + well. The special entry '*' is used to specify default certificates, which |
| 21529 | + are used as fallback when no domain matched. |
| 21530 | + |
| 21531 | + The certificates will be presented to clients who provide a valid TLS |
| 21532 | + Server Name Indication field matching one of the SNI filters, or the CN and |
| 21533 | + SAN of a <crtfile>. The matching algorithm first looks for a positive domain |
| 21534 | + entry in the list, if not found it will try to look for a wildcard in the |
| 21535 | + list. If a wilcard match, haproxy checks for a negative filter from the |
| 21536 | + same line and unmatch if necessary. In case of multiple key algorithms |
| 21537 | + (RSA,ECDSA,DSA), HAProxy will try to match one certificate per type and |
| 21538 | + chose the right one depending on what is supported by the client. |
| 21539 | + |
| 21540 | + If no SNI is presented by the client or if no certificate matched, this |
| 21541 | + will fallback to one of the default certificate. To disable the default |
| 21542 | + certificate fallback, the 'strict-sni' option may be used. |
| 21543 | + When multiple default certificates are defined, HAProxy is able to chose |
| 21544 | + the right ECDSA or RSA one depending on what the client supports. |
| 21545 | + |
| 21546 | + The first declared certificate of a bind line is used as a default |
| 21547 | + certificate, either from crt or crt-list option. |
| 21548 | + It is also possible to declare a '*' filter, which will add this |
| 21549 | + certificate to the list of default certificates. To clarify the |
| 21550 | + configuration, the default certificates could be explicited (with a '*' |
| 21551 | + filter) at the beginning of the list, so an implicit default is not added |
| 21552 | + before. |
| 21553 | + |
| 21554 | + The "show ssl sni" command on the stats socket could be used to debug your |
| 21555 | + configuration. (See "show ssl sni" in the management guide) |
| 21556 | +</pre><div class="separator"> |
| 21557 | +<span class="label label-success">Example:</span> |
| 21558 | +<pre class="prettyprint"> |
| 21559 | +<code><span class="comment"># comment</span> |
| 21560 | +default.pem.rsa * |
| 21561 | +default.pem.ecdsa * |
| 21562 | +cert2.pem [alpn h2,http/1.1] |
| 21563 | +certW.pem *.domain.tld !secure.domain.tld |
| 21564 | +certS.pem [curves X25519:P-256 ciphers ECDHE-ECDSA-AES256-GCM-SHA384] secure.domain.tld |
| 21565 | +foo.crt [key bar.pem ocsp foo.ocsp ocsp-update on] foo.bar.com |
| 21566 | +</code></pre> |
| 21567 | +</div><a class="anchor" name="default-crt"></a><a class="anchor" name="5-default-crt"></a><a class="anchor" name="5.1-default-crt"></a><a class="anchor" name="default-crt (Bind and server options)"></a><a class="anchor" name="default-crt (Bind options)"></a><div class="keyword"><b><a class="anchor" name="default-crt"></a><a href="#5.1-default-crt">default-crt</a></b> <span style="color: #080"><cert></span></div><pre class="text">This option does the same as the "<span class="dropdown"><a class="dropdown-toggle" data-toggle="dropdown" href="#">crt<span class="caret"></span></a><ul class="dropdown-menu"><li class="dropdown-header">This keyword is available in sections :</li><li><a href="#crt%20%28Load%20options%29">Load options</a></li><li><a href="#crt%20%28Bind%20options%29">Bind options</a></li><li><a href="#crt%20%28Server%20and%20default-server%20options%29">Server and default-server options</a></li></ul></span>" option, with the difference that this |
21533 | 21568 | certificate will be used as a default one. It is possible to add multiple |
21534 | 21569 | default certificates to have an ECDSA and an RSA one, having more is not |
21535 | 21570 | really useful. |
@@ -32222,7 +32257,7 @@ <h2 id="chapter-11.3" data-target="11.3"><small><a class="small" href="#11.3">11 |
32222 | 32257 | <br> |
32223 | 32258 | <hr> |
32224 | 32259 | <div class="text-right"> |
32225 | | - HAProxy 3.2-dev9-33 – Configuration Manual<br> |
| 32260 | + HAProxy 3.2-dev9-37 – Configuration Manual<br> |
32226 | 32261 | <small>, 2025/04/02</small> |
32227 | 32262 | </div> |
32228 | 32263 | </div> |
|
0 commit comments