From: Willy Tarreau Date: Wed, 14 May 2025 13:54:58 +0000 (+0200) Subject: DOC: config: move the extraneous sections out of the "global" definition X-Git-Tag: v3.2-dev16~7 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e24b77e7;p=thirdparty%2Fhaproxy.git DOC: config: move the extraneous sections out of the "global" definition Due to some historic mistakes that have spread to newly added sections, a number of of recently added small sections found themselves described under section 3 "global parameters" which is specific to "global" section keywords. This is highly confusing, especially given that sections 3.1, 3.2, 3.3 and 3.10 directly start with keywords valid in the global section, while others start with keywords that describe a new section. Let's just create a new chapter "12. other sections" and move them all there. 3.10 "HTTPclient tuning" however was moved to 3.4 as it's really a definition of the global options assigned to the HTTP client. The "programs" that are going away in 3.3 were moved at the end to avoid a renumbering later. Another nice benefit is that it moves a lot of text that was previously keeping the global and proxies sections apart. --- diff --git a/doc/configuration.txt b/doc/configuration.txt index c2ad7f9ee..d2d7e2cfe 100644 --- a/doc/configuration.txt +++ b/doc/configuration.txt @@ -52,21 +52,11 @@ Summary 2.9.3. Protocol prefixes 2.10. Examples -3. Global parameters +3. Global section 3.1. Process management and security 3.2. Performance tuning 3.3. Debugging -3.3.1. Traces -3.4. Userlists -3.5. Mailers -3.6. Programs (deprecated) -3.7. HTTP-errors -3.8. Rings -3.9. Log forwarding -3.10. HTTPClient tuning -3.11. Certificate Storage -3.11.1. Load options -3.12. ACME +3.4. HTTPClient tuning 4. Proxies 4.1. Proxy keywords matrix @@ -149,6 +139,18 @@ Summary 11.1. Stick-tables declaration 11.2. Peers declaration +12. Other sections +12.1. Traces +12.2. Userlists +12.3. Mailers +12.4. HTTP-errors +12.5. Rings +12.6. Log forwarding +12.7. Certificate Storage +12.7.1. Load options +12.8. ACME +12.9. Programs (deprecated) + 1. Quick reminder about HTTP ---------------------------- @@ -938,7 +940,7 @@ existing variables, not empty ones. user "$HAPROXY_USER" Some variables are defined by HAProxy, they can be used in the configuration -file, or could be inherited by a program (See 3.6. Programs). These variables +file, or could be inherited by a program (See 12.9. Programs). These variables are listed in the matrix below, and they are classified among four categories: * usable: the variable is accessible from the configuration, either to be @@ -953,7 +955,7 @@ are listed in the matrix below, and they are classified among four categories: described in section 9.3 "Unix Sockets commands" of the management guide. * exported: variable is exported to launch programs in a modified environment - (See section 3.6 "Programs"). Note that this does not apply to external + (See section 12.9 "Programs"). Note that this does not apply to external checks which have their own rules regarding exported variables. There also two subcategories "master" and "worker", respectively marked 'M' and @@ -5197,2017 +5199,1715 @@ zero-warning report errors in such a case. This option is equivalent to command line argument "-dW". -3.3.1. Traces -------------- +3.4. HTTPClient tuning +---------------------- -For debugging purpose, it is possible to activate traces on an HAProxy's -subsystem. This will dump debug messages about a specific subsystem. It is a -very powerful tool to diagnose issues. Traces can be dynamically configured via -the CLI. It is also possible to predefined some settings in the configuration -file, in dedicated "traces" sections. More details about traces can be found in -the management guide. It remains a developer tools used during complex -debugging sessions. It is pretty verbose and have a cost, so use it with -caution. And because it is a developer tool, there is no warranty about the -backward compatibility of this section. +HTTPClient is an internal HTTP library, it can be used by various subsystems, +for example in LUA scripts. HTTPClient is not used in the data path, in other +words it has nothing with HTTP traffic passing through HAProxy. -traces - Starts a new traces section. One or multiple "traces" section may be - used. All direcitives are evaluated in the declararion order, the last ones - overriding previous ones. +httpclient.resolvers.disabled + Disable the DNS resolution of the httpclient. Prevent the creation of the + "default" resolvers section. -trace - Configures on "trace" subsystem. Each of them can be found in the management - manual, and follow the exact same syntax. Any output that the "trace" - command would produce will be emitted during the parsing step of the - section. Most of the time these will be errors and warnings, but certain - incomplete commands might list permissible choices. This command is not meant - for regular use, it will generally only be suggested by developers along - complex debugging sessions. It is important to keep in mind that depending on - the trace level and details, enabling traces can severely degrade the global - performance. Please refer to the management manual for the statements syntax. + Default value is off. - Example: - ring buf1 - size 10485760 # 10MB - format timed - backing-file /tmp/h1.traces +httpclient.resolvers.id + This option defines the resolvers section with which the httpclient will try + to resolve. - ring buf2 - size 10485760 # 10MB - format timed - backing-file /tmp/h2.traces + Default option is the "default" resolvers ID. By default, if this option is + not used, it will simply disable the resolving if the section is not found. - traces - trace h1 sink buf1 level developer verbosity complete start now - trace h2 sink buf1 level developer verbosity complete start now + However, when this option is explicitly enabled it will trigger a + configuration error if it fails to load. -3.4. Userlists --------------- -It is possible to control access to frontend/backend/listen sections or to -http stats by allowing only authenticated and authorized users. To do this, -it is required to create at least one userlist and to define users. +httpclient.resolvers.prefer + This option allows to chose which family of IP you want when resolving, + which is convenient when IPv6 is not available on your network. Default + option is "ipv6". -userlist - Creates new userlist with name . Many independent userlists can be - used to store authentication & authorization data for independent customers. +httpclient.retries + This option allows to configure the number of retries attempt of the + httpclient when a request failed. This does the same as the "retries" keyword + in a backend. -group [users ,,(...)] - Adds group to the current userlist. It is also possible to - attach users to this group by using a comma separated list of names - proceeded by "users" keyword. + Default value is 3. -user [password|insecure-password ] - [groups ,,(...)] - Adds user to the current userlist. Both secure (encrypted) and - insecure (unencrypted) passwords can be used. Encrypted passwords are - evaluated using the crypt(3) function, so depending on the system's - capabilities, different algorithms are supported. For example, modern Glibc - based Linux systems support MD5, SHA-256, SHA-512, and, of course, the - classic DES-based method of encrypting passwords. +httpclient.ssl.ca-file + This option defines the ca-file which should be used to verify the server + certificate. It takes the same parameters as the "ca-file" option on the + server line. - Attention: Be aware that using encrypted passwords might cause significantly - increased CPU usage, depending on the number of requests, and the algorithm - used. For any of the hashed variants, the password for each request must - be processed through the chosen algorithm, before it can be compared to the - value specified in the config file. Most current algorithms are deliberately - designed to be expensive to compute to achieve resistance against brute - force attacks. They do not simply salt/hash the clear text password once, - but thousands of times. This can quickly become a major factor in HAProxy's - overall CPU consumption, and can even lead to application crashes! + By default and when this option is not used, the value is + "@system-ca" which tries to load the CA of the system. If it fails the SSL + will be disabled for the httpclient. - To address the high CPU usage of hash functions, one approach is to reduce - the number of rounds of the hash function (SHA family algorithms) or decrease - the "cost" of the function, if the algorithm supports it. + However, when this option is explicitly enabled it will trigger a + configuration error if it fails. - As a side note, musl (e.g. Alpine Linux) implementations are known to be - slower than their glibc counterparts when calculating hashes, so you might - want to consider this aspect too. +httpclient.ssl.verify [none|required] + Works the same way as the verify option on server lines. If specified to 'none', + servers certificates are not verified. Default option is "required". - Example: - userlist L1 - group G1 users tiger,scott - group G2 users xdb,scott + By default and when this option is not used, the value is + "required". If it fails the SSL will be disabled for the httpclient. - user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91 - user scott insecure-password elgato - user xdb insecure-password hello + However, when this option is explicitly enabled it will trigger a + configuration error if it fails. - userlist L2 - group G1 - group G2 +httpclient.timeout.connect + Set the maximum time to wait for a connection attempt by default for the + httpclient. - user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1 - user scott insecure-password elgato groups G1,G2 - user xdb insecure-password hello groups G2 + Arguments : + is the timeout value specified in milliseconds by default, but + can be in any other unit if the number is suffixed by the unit, + as explained at the top of this document. - Please note that both lists are functionally identical. + The default value is 5000ms. -3.5. Mailers ------------- -It is possible to send email alerts when the state of servers changes. -If configured email alerts are sent to each mailer that is configured -in a mailers section. Email is sent to mailers through Lua (see -examples/lua/mailers.lua). +4. Proxies +---------- -mailers - Creates a new mailer list with the name . It is an - independent section which is referenced by one or more proxies. +Proxy configuration can be located in a set of sections : + - defaults [] [ from ] + - frontend [ from ] + - backend [ from ] + - listen [ from ] -mailer : - Defines a mailer inside a mailers section. +A "frontend" section describes a set of listening sockets accepting client +connections. - Example: - global - # mailers.lua file as provided in the git repository - # adjust path as needed - lua-load examples/lua/mailers.lua +A "backend" section describes a set of servers to which the proxy will connect +to forward incoming connections. - mailers mymailers - mailer smtp1 192.168.0.1:587 - mailer smtp2 192.168.0.2:587 +A "listen" section defines a complete proxy with its frontend and backend +parts combined in one section. It is generally useful for TCP-only traffic. - backend mybackend - mode tcp - balance roundrobin +A "defaults" section resets all settings to the documented ones and presets new +ones for use by subsequent sections. All of "frontend", "backend" and "listen" +sections always take their initial settings from a defaults section, by default +the latest one that appears before the newly created section. It is possible to +explicitly designate a specific "defaults" section to load the initial settings +from by indicating its name on the section line after the optional keyword +"from". While "defaults" section do not impose a name, this use is encouraged +for better readability. It is also the only way to designate a specific section +to use instead of the default previous one. Since "defaults" section names are +optional, by default a very permissive check is applied on their name and these +are even permitted to overlap. However if a "defaults" section is referenced by +any other section, its name must comply with the syntax imposed on all proxy +names, and this name must be unique among the defaults sections. Please note +that regardless of what is currently permitted, it is recommended to avoid +duplicate section names in general and to respect the same syntax as for proxy +names. This rule might be enforced in a future version. In addition, a warning +is emitted if a defaults section is explicitly used by a proxy while it is also +implicitly used by another one because it is the last one defined. It is highly +encouraged to not mix both usages by always using explicit references or by +adding a last common defaults section reserved for all implicit uses. - email-alert mailers mymailers - email-alert from test1@horms.org - email-alert to test2@horms.org +Note that it is even possible for a defaults section to take its initial +settings from another one, and as such, inherit settings across multiple levels +of defaults sections. This can be convenient to establish certain configuration +profiles to carry groups of default settings (e.g. TCP vs HTTP or short vs long +timeouts) but can quickly become confusing to follow. - server srv1 192.168.0.30:80 - server srv2 192.168.0.31:80 +All proxy names must be formed from upper and lower case letters, digits, +'-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are +case-sensitive, which means that "www" and "WWW" are two different proxies. -timeout mail