diff --git a/doc/configuration.txt b/doc/configuration.txt index 0166e2d9a..c2ad7f9ee 100644 --- a/doc/configuration.txt +++ b/doc/configuration.txt @@ -58,16 +58,15 @@ Summary 3.3. Debugging 3.3.1. Traces 3.4. Userlists -3.5. Peers -3.6. Mailers -3.7. Programs (deprecated) -3.8. HTTP-errors -3.9. Rings -3.10. Log forwarding -3.11. HTTPClient tuning -3.12. Certificate Storage -3.12.1. Load options -3.13. ACME +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 4. Proxies 4.1. Proxy keywords matrix @@ -146,6 +145,10 @@ Summary 10.2. Default parameters 10.3. Limitations +11. Stick-tables and Peers +11.1. Stick-tables declaration +11.2. Peers declaration + 1. Quick reminder about HTTP ---------------------------- @@ -935,7 +938,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.7. Programs). These variables +file, or could be inherited by a program (See 3.6. 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 @@ -950,7 +953,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.7 "Programs"). Note that this does not apply to external + (See section 3.6 "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 @@ -5300,197 +5303,7 @@ user [password|insecure-password ] Please note that both lists are functionally identical. -3.5. Peers ----------- -It is possible to propagate entries of any data-types in stick-tables between -several HAProxy instances over TCP connections in a multi-master fashion. Each -instance pushes its local updates and insertions to remote peers. The pushed -values overwrite remote ones without aggregation. - -One exception is the data type "conn_cur" which is never learned from peers by -default as it is supposed to reflect local values. Earlier versions used to -synchronize it by default which was known to cause negative values in active- -active setups, and always-growing values upon reloads or active-passive -switches because the local value would reflect more connections than locally -present. However there are some setups where it could be relevant to learn -this value from peers, for instance when the table is a passive remote table -solely used to learn/monitor data from it without relying on it for write- -oriented operations or updates. To achieve this, the "recv-only" keyword can -be added on the table declaration. In any case, the "conn_cur" info is always -pushed so that monitoring systems can watch it. - -Interrupted exchanges are automatically detected and recovered from the last -known point. In addition, during a soft restart, the old process connects to -the new one using such a TCP connection to push all its entries before the new -process tries to connect to other peers. That ensures very fast replication -during a reload, it typically takes a fraction of a second even for large -tables. - -Note that Server IDs are used to identify servers remotely, so it is important -that configurations look similar or at least that the same IDs are forced on -each server on all participants. - -peers - Creates a new peer list with name . It is an independent section, - which is referenced by one or more stick-tables. - -bind [
]:port [param*] -bind / [param*] - Defines the binding parameters of the local peer of this "peers" section. - Such lines are not supported with "peer" line in the same "peers" section. - -disabled - Disables a peers section. It disables both listening and any synchronization - related to this section. This is provided to disable synchronization of stick - tables without having to comment out all "peers" references. - -default-bind [param*] - Defines the binding parameters for the local peer, excepted its address. - -default-server [param*] - Change default options for a server in a "peers" section. - - Arguments: - is a list of parameters for this server. The "default-server" - keyword accepts an important number of options and has a complete - section dedicated to it. In a peers section, the transport - parameters of a "default-server" line are supported. Please refer - to section 5 for more details, and the "server" keyword below in - this section for some of the restrictions. - - See also: "server" and section 5 about server options - -enabled - This re-enables a peers section which was previously disabled via the - "disabled" keyword. - -log [len ] [format ] [sample :] - [ []] - "peers" sections support the same "log" keyword as for the proxies to - log information about the "peers" listener. See "log" option for proxies for - more details. - -peer [
]:port [param*] -peer / [param*] - Defines a peer inside a peers section. - If is set to the local peer name (by default hostname, or forced - using "-L" command line option or "localpeer" global configuration setting), - HAProxy will listen for incoming remote peer connection on the provided - address. Otherwise, the address defines where to connect to in order to join - the remote peer, and is used at the protocol level to identify and - validate the remote peer on the server side. - - During a soft restart, local peer address is used by the old instance to - connect the new one and initiate a complete replication (teaching process). - - It is strongly recommended to have the exact same peers declaration on all - peers and to only rely on the "-L" command line argument or the "localpeer" - global configuration setting to change the local peer name. This makes it - easier to maintain coherent configuration files across all peers. - - You may want to reference some environment variables in the address - parameter, see section 2.3 about environment variables. - - Note: "peer" keyword may transparently be replaced by "server" keyword (see - "server" keyword explanation below). - -server [
:] [param*] -server [/] [param*] - As previously mentioned, "peer" keyword may be replaced by "server" keyword - with a support for all "server" parameters found in 5.2 paragraph that are - related to transport settings. If the underlying peer is local, the address - parameter must not be present; it must be provided on a "bind" line (see - "bind" keyword of this "peers" section). - - A number of "server" parameters are irrelevant for "peers" sections. Peers by - nature do not support dynamic host name resolution nor health checks, hence - parameters like "init_addr", "resolvers", "check", "agent-check", or "track" - are not supported. Similarly, there is no load balancing nor stickiness, thus - parameters such as "weight" or "cookie" have no effect. - - Example: - # The old way. - peers mypeers - peer haproxy1 192.168.0.1:1024 - peer haproxy2 192.168.0.2:1024 - peer haproxy3 10.2.0.1:1024 - - backend mybackend - mode tcp - balance roundrobin - stick-table type ip size 20k peers mypeers - stick on src - - server srv1 192.168.0.30:80 - server srv2 192.168.0.31:80 - - Example: - peers mypeers - bind 192.168.0.1:1024 ssl crt mycerts/pem - default-server ssl verify none - server haproxy1 #local peer - server haproxy2 192.168.0.2:1024 - server haproxy3 10.2.0.1:1024 - -shards - - In some configurations, one would like to distribute the stick-table contents - to some peers in place of sending all the stick-table contents to each peer - declared in the "peers" section. In such cases, "shards" specifies the - number of peer involved in this stick-table contents distribution. - See also "shard" server parameter. - -table type {ip | integer | string [len ] | binary [len ]} - size [expire ] [write-to ] [nopurge] [store ]* - [recv-only] - - Configure a stickiness table for the current section. This line is parsed - exactly the same way as the "stick-table" keyword in others section, except - for the "peers" argument which is not required here and with an additional - mandatory first parameter to designate the stick-table. Contrary to others - sections, there may be several "table" lines in "peers" sections (see also - "stick-table" keyword). - - Also be aware of the fact that "peers" sections have their own stick-table - namespaces to avoid collisions between stick-table names identical in - different "peers" section. This is internally handled prepending the "peers" - sections names to the name of the stick-tables followed by a '/' character. - If somewhere else in the configuration file you have to refer to such - stick-tables declared in "peers" sections you must use the prefixed version - of the stick-table name as follows: - - peers mypeers - peer A ... - peer B ... - table t1 ... - - frontend fe1 - tcp-request content track-sc0 src table mypeers/t1 - - This is also this prefixed version of the stick-table names which must be - used to refer to stick-tables through the CLI. - - About "peers" protocol, as only "peers" belonging to the same section may - communicate with each others, there is no need to do such a distinction. - Several "peers" sections may declare stick-tables with the same name. - This is shorter version of the stick-table name which is sent over the network. - There is only a '/' character as prefix to avoid stick-table name collisions between - stick-tables declared as backends and stick-table declared in "peers" sections - as follows in this weird but supported configuration: - - peers mypeers - peer A ... - peer B ... - table t1 type string size 10m store gpc0 - - backend t1 - stick-table type string size 10m store gpc0 peers mypeers - - Here "t1" table declared in "mypeers" section has "mypeers/t1" as global name. - "t1" table declared as a backend as "t1" as global name. But at peer protocol - level the former table is named "/t1", the latter is again named "t1". - -3.6. Mailers +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 @@ -5536,7 +5349,7 @@ timeout mail