Re: [PATCH] DOC: give a more accuration description of what check does
On Tue, Apr 28, 2020 at 10:31:42PM +0200, Jerome Magnin wrote: > > - by default, checks are performed on the same address and port as > > configured on the server, using the same encapsulation parameters > > (SSL/TLS, SNI, proxy-protocol header etc). If "port" or "addr" > > directives are set, it is assumed that the server isn't checked on > > the traffic port but on a proxy port that possibly uses a different > > service. In this case, connection headers such as the proxy protocol > > are only sent if "check-send-proxy" is set; SSL/TLS is only used if > > "check-ssl" is used, and similarly the SNI used on the connection > > will be defined by "check-sni". See also "check-ssl", "check-sni" etc. > > This part is not entirely accurate in my experience: > - SNI configured with "sni" on server lines is not used with checks. One > must > set "check-sni", if only because it's almost always 'sni ssl_fc_sni' or > 'sni hdr(host)' which has no meaning in the context of checks. I don't > think > there are ways around this. That's a good point, that's forced by the fact that "sni" takes a dynamic expression while checks cannot and must take a constant. > - the "alpn" setting of a server line is also not used for checks, one must > define it with check-alpn. This will probably change soon now that haproxy > can do h2 checks natively. For this one I don't know :-) OK I'm taking the patch as-is. If anyone who has experienced issues configuring checks could have a look and see if all their issues are properly addressed now, that would be great. Probably that we'd need to have a "checks" section in the config manual at some point. Thanks, Willy
Re: [PATCH] DOC: give a more accuration description of what check does
Hi Willy, On Tue, Apr 28, 2020 at 05:46:08PM +0200, Willy Tarreau wrote: > > Thanks for this, however I don't completely agree with the wording > there (but I do agree that the current one is totally outdated). > > The main point is that users don't configure "handshakes", they > rather define transport protocols (typically SSL) so in the end > this is not necessarily clearer this way and may even lead to new > confusion regarding ssl vs check-ssl for example. > > Probably that it would be better to take this opportunity to > entirely revisit the description of the "check" keyword to cover > the following points: Thanks for the feedback. I've attached an updated patch to this email. > > - by default, checks are performed on the same address and port as > configured on the server, using the same encapsulation parameters > (SSL/TLS, SNI, proxy-protocol header etc). If "port" or "addr" > directives are set, it is assumed that the server isn't checked on > the traffic port but on a proxy port that possibly uses a different > service. In this case, connection headers such as the proxy protocol > are only sent if "check-send-proxy" is set; SSL/TLS is only used if > "check-ssl" is used, and similarly the SNI used on the connection > will be defined by "check-sni". See also "check-ssl", "check-sni" etc. This part is not entirely accurate in my experience: - SNI configured with "sni" on server lines is not used with checks. One must set "check-sni", if only because it's almost always 'sni ssl_fc_sni' or 'sni hdr(host)' which has no meaning in the context of checks. I don't think there are ways around this. - the "alpn" setting of a server line is also not used for checks, one must define it with check-alpn. This will probably change soon now that haproxy can do h2 checks natively. Jérôme >From 6a8e8ecfa1f6c9e8a4d1a5000296f650b45d9bdc Mon Sep 17 00:00:00 2001 From: Jerome Magnin Date: Sun, 26 Apr 2020 14:23:04 +0200 Subject: [PATCH] DOC: give a more accurate description of what check does The documentation for check implies that without an application level check configured, it only enables simple tcp checks. What it actually does is verify that the configured transport layer is available, and that optional application level checks succeed. --- doc/configuration.txt | 61 ++- 1 file changed, 49 insertions(+), 12 deletions(-) diff --git a/doc/configuration.txt b/doc/configuration.txt index 3853d406f..12582d9f2 100644 --- a/doc/configuration.txt +++ b/doc/configuration.txt @@ -12520,18 +12520,55 @@ ca-file server's certificate. check - This option enables health checks on the server. By default, a server is - always considered available. If "check" is set, the server is available when - accepting periodic TCP connections, to ensure that it is really able to serve - requests. The default address and port to send the tests to are those of the - server, and the default source is the same as the one defined in the - backend. It is possible to change the address using the "addr" parameter, the - port using the "port" parameter, the source address using the "source" - address, and the interval and timers using the "inter", "rise" and "fall" - parameters. The request method is define in the backend using the "httpchk", - "smtpchk", "mysql-check", "pgsql-check" and "ssl-hello-chk" options. Please - refer to those options and parameters for more information. See also - "no-check" option. + This option enables health checks on a server: +- when not set, no health checking is performed, and the server is always + considered available. +- when set and no other check method is configured, the server is considered + available when a connection can be established at the highest configured + transport layer. This means TCP by default, or SSL/TLS when "ssl" or + "check-ssl" are set, both possibly combined with connection prefixes such + as a PROXY protocol header when "send-proxy" or "check-send-proxy" are + set. +- when set and an application-level health check is defined, the + application-level exchanges are performed on top of the configured + transport layer and the server is considered available if all of the + exchanges succeed. + + By default, health checks are performed on the same address and port as + configured on the server, using the same encapsulation parameters (SSL/TLS, + proxy-protocol header, etc... ). It is possible to change the destination + address using "addr" and the port using "port". When done, it is assumed the + server isn't checked on the service port, and configured encapsulation + parameters are not reused. One must explicitely set "check-send-proxy" to send + connection headers, "check-ssl" to use SSL/TLS. + + When "sni" or "alpn" are set on the server line, their value is not used for + health checks an
Re: [PATCH] DOC: give a more accuration description of what check does
Hi Jérôme, On Sun, Apr 26, 2020 at 02:34:34PM +0200, Jerome Magnin wrote: > The documentation for check implies that without an optional l7 > check configured, it enables simple tcp checks. What it actually > does is check that every configured handshake on the server line > can be established. Thanks for this, however I don't completely agree with the wording there (but I do agree that the current one is totally outdated). The main point is that users don't configure "handshakes", they rather define transport protocols (typically SSL) so in the end this is not necessarily clearer this way and may even lead to new confusion regarding ssl vs check-ssl for example. Probably that it would be better to take this opportunity to entirely revisit the description of the "check" keyword to cover the following points: - without "check", no check is performed and the server is always considered "up" - when "check" is specified and no check method is defined, the server is considered "up" when a connection can be established at the highest configured transport layer, which means bare TCP by default, or SSL/TLS when "ssl" or "check-ssl" are involved, both possibly combined with possible connection prefixes such as a proxy protocol header - when "check" is specified and an application-level check method is defined, then the application-level exchanges are performed on top of the configured transport layer, all of which must succeed for the server to be reported "up". - by default, checks are performed on the same address and port as configured on the server, using the same encapsulation parameters (SSL/TLS, SNI, proxy-protocol header etc). If "port" or "addr" directives are set, it is assumed that the server isn't checked on the traffic port but on a proxy port that possibly uses a different service. In this case, connection headers such as the proxy protocol are only sent if "check-send-proxy" is set; SSL/TLS is only used if "check-ssl" is used, and similarly the SNI used on the connection will be defined by "check-sni". See also "check-ssl", "check-sni" etc. > # this does a tcp connect + tls handshake > backend foo > server s1 192.168.0.1;443 ssl check beware the semicolon here ^ Be careful below, some lines are slightly longer than the 80 chars limit. > + always considered available. If "check" is set, the server is considered > + available when all the handshakes configured on the server line can be > + established, or when an optional layer 7 health check succeeds. This is to > + ensure that the server is really able to handle requests. The default > address > + and port to send health checks to are those of the server, and the default > + source address is the same as the one defined in the backend. It is > possible > + to change the destination address using the "addr" parameter, the port > using > + the "port" parameter, the source address using the "source" parameter, and > the > + interval and timers using the "inter", "rise" and "fall" parameters. > Optional > + layer 7 checks can be configured with the "httpchk", "smtpchk", > "mysql-check", > + "pgsql-check" and "ssl-hello-check" options. When ssl is configured on the > + server line, "option tcp-check" and "tcp-check connect" can be used to > refrain > + from establishing the tls hanshake during health checks. Please refer to > those > + options and parameters for more information. See also "no-check" and > "check-ssl". Thanks, Willy
[PATCH] DOC: give a more accuration description of what check does
Hi, here's a documentation patch for the check keyword. regards, Jérôme >From 10e90939d9fd1bd4f1e651d679d0b99e8da91afb Mon Sep 17 00:00:00 2001 From: Jerome Magnin Date: Sun, 26 Apr 2020 14:23:04 +0200 Subject: [PATCH] DOC: give a more accurate description of what check does The documentation for check implies that without an optional l7 check configured, it enables simple tcp checks. What it actually does is check that every configured handshake on the server line can be established. # simple tcp connect backend foo server s1 192.168.0.1:80 check # this does a tcp connect + tls handshake backend foo server s1 192.168.0.1;443 ssl check # simple tcp connect is enough for check success backend foo option tcp-check tcp-check connect server s1 192.168.0.1:443 ssl check --- doc/configuration.txt | 38 +++--- 1 file changed, 27 insertions(+), 11 deletions(-) diff --git a/doc/configuration.txt b/doc/configuration.txt index 676d5a075..faf5a54bc 100644 --- a/doc/configuration.txt +++ b/doc/configuration.txt @@ -12112,17 +12112,33 @@ ca-file check This option enables health checks on the server. By default, a server is - always considered available. If "check" is set, the server is available when - accepting periodic TCP connections, to ensure that it is really able to serve - requests. The default address and port to send the tests to are those of the - server, and the default source is the same as the one defined in the - backend. It is possible to change the address using the "addr" parameter, the - port using the "port" parameter, the source address using the "source" - address, and the interval and timers using the "inter", "rise" and "fall" - parameters. The request method is define in the backend using the "httpchk", - "smtpchk", "mysql-check", "pgsql-check" and "ssl-hello-chk" options. Please - refer to those options and parameters for more information. See also - "no-check" option. + always considered available. If "check" is set, the server is considered + available when all the handshakes configured on the server line can be + established, or when an optional layer 7 health check succeeds. This is to + ensure that the server is really able to handle requests. The default address + and port to send health checks to are those of the server, and the default + source address is the same as the one defined in the backend. It is possible + to change the destination address using the "addr" parameter, the port using + the "port" parameter, the source address using the "source" parameter, and the + interval and timers using the "inter", "rise" and "fall" parameters. Optional + layer 7 checks can be configured with the "httpchk", "smtpchk", "mysql-check", + "pgsql-check" and "ssl-hello-check" options. When ssl is configured on the + server line, "option tcp-check" and "tcp-check connect" can be used to refrain + from establishing the tls hanshake during health checks. Please refer to those + options and parameters for more information. See also "no-check" and "check-ssl". + + Example: + # simple tcp connect + backend foo +server s1 192.168.0.1:80 check + # this does a tcp connect + tls handshake + backend foo +server s1 192.168.0.1;443 ssl check + # simple tcp connect is enough for check success + backend foo +option tcp-check +tcp-check connect +server s1 192.168.0.1:443 ssl check check-send-proxy This option forces emission of a PROXY protocol line with outgoing health -- 2.26.2
