From 6a06a4050199df02aa50adedb0bfd1791f532141 Mon Sep 17 00:00:00 2001 From: Willy Tarreau Date: Sun, 15 Jul 2007 20:15:28 +0200 Subject: [PATCH] [DOC] started a new configuration manual This new configuration manual intends to document every known keyword of the configuration language. Right now, it enumerates them all and describes how to use ACLs. --- doc/configuration.txt | 635 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 635 insertions(+) create mode 100644 doc/configuration.txt diff --git a/doc/configuration.txt b/doc/configuration.txt new file mode 100644 index 000000000..9a957fbe2 --- /dev/null +++ b/doc/configuration.txt @@ -0,0 +1,635 @@ + ---------------------- + HAProxy + Configuration Manual + ---------------------- + version 1.3.12 + willy tarreau + 2007/07/15 + + +This document covers the configuration language as implemented in the version +specified above. It does not provide any hint, example or advice. For such +docuemntation, please refer to the Reference Manual or the Architecture Manual. + + +HAProxy's configuration process involves 3 major sources of parameters : + + - the arguments from the command-line, which always take precedence + - the "global" section, which sets process-wide parameters + - the proxies sections which can take form of "defaults", "listen", + "frontend" and "backend". + +1. Global parameters +-------------------- + +Parameters in the "global" section are process-wide and often OS-specific. They +are generally set once for all and do not need being changed once correct. Some +of them have command-line equivalents. + +The following keywords are supported in the "global" section : + + * Process management and security + - chroot + - daemon + - gid + - group + - log + - nbproc + - pidfile + - uid + - ulimit-n + - user + + * Performance tuning + - maxconn + - noepoll + - nokqueue + - nopoll + - nosepoll + - tune.maxpollevents + + * Debugging + - debug + - quiet + - stats + + +1.1) Process management and security +------------------------------------ + +chroot + Changes current directory to and performs a chroot() there before + dropping privileges. This increases the security level in case an unknown + vulnerability would be exploited, since it would make it very hard for the + attacker to exploit the system. This only works when the process is started + with superuser privileges. It is important to ensure that is both + empty and unwritable to anyone. + +daemon + Makes the process fork into background. This is the recommended mode of + operation. It is equivalent to the command line "-D" argument. It can be + disabled by the command line "-db" argument. + +gid + Changes the process' group ID to . It is recommended that the group + ID is dedicated to HAProxy or to a small set of similar daemons. HAProxy must + be started with a user belonging to this group, or with superuser privileges. + See also "group" and "uid". + +group + Similar to "gid" but uses the GID of group name from /etc/group. + See also "gid" and "user". + +log
[max level] + Adds a global syslog server. Up to two global servers can be defined. They + will receive logs for startups and exits, as well as all logs from proxies + configured with "log global".
is an IPv4 address optionally + followed by a colon and an UDP port. If no port is specified, 514 is used + by default (the standard syslog port). must be one of the 24 + standard syslog facilities : + + kern user mail daemon auth syslog lpr news + uucp cron auth2 ftp ntp audit alert cron2 + local0 local1 local2 local3 local4 local5 local6 local7 + + An optional level can be specified to filter outgoing messages. By default, + all messages are sent. If a level is specified, only messages with a severity + at least as important as this level will be sent. 8 levels are known : + + emerg alert crit err warning notice info debug + +nbproc + Creates processes when going daemon. This requires the "daemon" + mode. By default, only one process is created, which is the recommended mode + of operation. For systems limited to small sets of file descriptors per + process, it may be needed to fork multiple daemons. USING MULTIPLE PROCESSES + IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. See also "daemon". + +pidfile + Writes pids of all daemons into file . This option is equivalent to + the "-p" command line argument. The file must be accessible to the user + starting the process. See also "daemon". + +uid + Changes the process' user ID to . It is recommended that the user ID + is dedicated to HAProxy or to a small set of similar daemons. HAProxy must + be started with superuser privileges in order to be able to switch to another + one. See also "gid" and "user". + +ulimit-n + Sets the maximum number of per-process file-descriptors to . By + default, it is automatically computed, so it is recommended not to use this + option. + +user + Similar to "uid" but uses the UID of user name from /etc/passwd. + See also "uid" and "group". + + +1.2) Performance tuning +----------------------- + +maxconn + Sets the maximum per-process number of concurrent connections to . It + is equivalent to the command-line argument "-n". Proxies will stop accepting + connections when this limit is reached. The "ulimit-n" parameter is + automatically adjusted according to this value. See also "ulimit-n". + +noepoll + Disables the use of the "epoll" event polling system on Linux. It is + equivalent to the command-line argument "-de". The next polling system + used will generally be "poll". See also "nosepoll", and "nopoll". + +nokqueue + Disables the use of the "kqueue" event polling system on BSD. It is + equivalent to the command-line argument "-dk". The next polling system + used will generally be "poll". See also "nopoll". + +nopoll + Disables the use of the "poll" event polling system. It is equivalent to the + command-line argument "-dp". The next polling system used will be "select". + It should never be needed to didsable "poll" since it's available on all + platforms supported by HAProxy. See also "nosepoll", and "nopoll" and + "nokqueue". + +nosepoll + Disables the use of the "speculative epoll" event polling system on Linux. It + is equivalent to the command-line argument "-ds". The next polling system + used will generally be "epoll". See also "nosepoll", and "nopoll". + +tune.maxpollevents + Sets the maximum amount of events that can be processed at once in a call to + the polling system. The default value is adapted to the operating system. It + has been noticed that reducing it below 200 tends to slightly decrease + latency at the expense of network bandwidth, and increasing it above 200 + tends to trade latency for slightly increased bandwidth. + + +1.3) Debugging +--------------- + +debug + Enables debug mode which dumps to stdout all exchanges, and disables forking + into background. It is the equivalent of the command-line argument "-d". It + should never be used in a production configuration since it may prevent full + system startup. + +quiet + Do not display any message during startup. It is equivalent to the command- + line argument "-q". + +stats + Dump internal statistics to stdout at regular interval. It is available for + development purposes only and should never be set. + + +2) Proxies +---------- +Proxy configuration can be located in a set of sections : + - defaults + - frontend + - backend + - listen + +A "defaults" section sets default parameters for all other sections following +its declaration. Those default parameters are reset by the next "defaults" +section. See below for the list of parameters which can be set in a "defaults" +section. + +A "frontend" section describes a set of listening sockets accepting client +connections. + +A "backend" section describes a set of servers to which the proxy will connect +to forward incoming connections. + +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. + +The following list of keywords is supported. Most of them may only be used in a +limited set of section types. + +keyword defaults frontend listen backend +----------------------+----------+----------+---------+--------- +acl - X X X +appsession - - X X +balance - - X X +bind - X X - +block - X X X +capture cookie X X X X +capture request header X X X X +capture response header X X X X +clitimeout X X X - +contimeout X X X X +cookie X - X X +default_backend - X X - +disabled - X X X +dispatch - - X X +enabled - X X X +errorfile X X X X +errorloc X X X X +errorloc302 X X X X +errorloc303 X X X X +fullconn X - X X +grace - X X X +log X X X X +maxconn X X X - +mode X X X X +monitor-net X X X - +monitor-uri X X X - +option abortonclose X - X X +option allbackups X - X X +option checkcache X - X X +option clitcpka X X X - +option dontlognull X X X - +option forceclose X - X X +option forwardfor X X X X +option httpchk X - X X +option httpclose X X X X +option httplog X X X X +option logasap X X X - +option persist X - X X +option redispatch X - X X +option smtpchk X - X X +option srvtcpka X - X X +option ssl-hello-chk X - X X +option tcpka X X X X +option tcplog X X X X +option tcpsplice X X X X +option transparent X X X - +redisp X - X X +redispatch X - X X +reqadd - X X X +reqallow - X X X +reqdel - X X X +reqdeny - X X X +reqiallow - X X X +reqidel - X X X +reqideny - X X X +reqipass - X X X +reqirep - X X X +reqisetbe - X X X +reqitarpit - X X X +reqpass - X X X +reqrep - X X X +reqsetbe - X X X +reqtarpit - X X X +retries X - X X +rspadd - X X X +rspdel - X X X +rspdeny - X X X +rspidel - X X X +rspideny - X X X +rspirep - X X X +rsprep - X X X +server - - X X +source X - X X +srvtimeout X - X X +stats auth X X X X +stats enable X X X X +stats realm X X X X +stats scope X X X X +stats uri X X X X +transparent X X X - +use_backend - X X - +usesrc X - X X +----------------------+----------+----------+---------+--------- +keyword defaults frontend listen backend + + +2.1) using ACLs +--------------- + +The use of Access Control Lists (ACL) provides a flexible solution to perform +content switching. The principle is simple : + + - define test criteria with sets of values + - perform actions only if a set of tests is valid + +The actions generally consist in blocking the request, or selecting a backend. + +In order to define a test, the "acl" keyword is used. The syntax is : + + acl [flags] [operator] ... + +This creates an ACL or completes an existing one with new +tests. Those tests apply to the portion of request specified in +and may be adjusted with optional flags [flags]. Some criteria also support +an operator which may be specified before the set of values. The values are +of the type supported by the criterion, and are separated by spaces. + +There is no limit to the number of ACLs. The unused ones do not affect +performance, they just consume a small amount of memory. + +The current flags are currently supported : + + -i : ignore case during matching. + -- : force end of flags. Useful when a string looks like one of the flags. + +Supported types of values are : + - integers or integer ranges + - strings + - regular expressions + - IP addresses and networks + + +2.1.1) Matching integers +------------------------ + +Matching integers is special in that ranges and operators are permitted. Note +that integer matching only applies to positive values. A range is a value +expressed with a lower and an upper bound separated with a colon, both of which +may be omitted. + +For instance, "1024:65535" is a valid range to represent a range of +unprivileged ports, and "1024:" would also work. "0:1023" is a valid +representation of privileged ports, and ":1023" would also work. + +For an easier usage, comparison operators are also supported. Note that using +operators with ranges does not make much sense and is discouraged. Also, it +does not make much sense to perform order comparisons with a set of values. + +Available operators are : + + eq : true if the tested value equals at least one value + ge : true if the tested value is greater than or equal to at least one value + gt : true if the tested value is greater than at least one value + le : true if the tested value is less than or equal to at least one value + lt : true if the tested value is less than at least one value + +For instance, the following ACL matches negative Content-Length headers : + + acl negative-length hdr_val(content-length) lt 0 + + +2.1.2) Matching strings +----------------------- + +String matching applies to verbatim strings as they are passed, with the +exception of the backslash ("\") which makes it possible to escape some +characters such as the space. If the "-i" flag is passed before the first +string, then the matching will be performed ignoring the case. In order +to match the string "-i", either set it second, or pass the "--" flag +before the first string. + + +2.1.3) Matching regular expressions (regexes) +--------------------------------------------- + +Just like with string matching, regex matching applies to verbatim strings as +they are passed, with the exception of the backslash ("\") which makes it +possible to escape some characters such as the space. If the "-i" flag is +passed before the first regex, then the matching will be performed ignoring +the case. In order to match the string "-i", either set it second, or pass +the "--" flag before the first string. + + +2.1.4) Matching IPv4 addresses +---------------------------- + +IPv4 addresses values can be specified either as plain addresses or with a +netmask appended, in which case the IPv4 address matches whenever it is +within the network. Plain addresses may also be replaced with a resolvable +host name, but this practise is generally discouraged as it makes it more +difficult to read configurations. + + +2.1.5) Available matching criteria +---------------------------------- + +always_false + This one never matches. All values and flags are ignored. It may be used as + a temporary replacement for another one when adjusting configurations. + +always_true + This one always matches. All values and flags are ignored. It may be used as + a temporary replacement for another one when adjusting configurations. + +src + Applies to the client's IP address. It is usually used to limit access to + certain resources such as statistics. Note that it is the TCP-level source + address which is used, and not the address of a client behind a proxy. + +src_port + Applies to the client's TCP source port. This has a very limited usage. + +dst + Applies to the local IP address the client connected to. It can be used to + switch to a different backend for some alternative addresses. + +dst_port + Applies to the local port the client connected to. It can be used to switch + to a different backend for some alternative ports. + +dst_conn + Applies to the number of currently established connections on the frontend, + including the one being evaluated. It can be used to either return a sorry + page before hard-blocking, or to use a specific backend to drain the requests + when the farm is considered saturated. + +method + Applies to the method in the HTTP request, eg: "GET". Some predefined ACL + already check for most common methods. + +req_ver + Applies to the version string in the HTTP request, eg: "1.0". Some predefined + ACL already check for versions 1.0 and 1.1. + +path + Returns true when the path part of the request, which starts at the first + slash and ends before the question mark, equals one of the strings. It may be + used to match known files, such as /favicon.ico. + +path_beg + Returns true when the path begins with one of the strings. This can be used to + send certain directory names to alternative backends. + +path_end + Returns true when the path ends with one of the strings. This may be used to + control file name extension. + +path_sub + Returns true when the path contains one of the strings. It can be used to + detect particular patterns in paths, such as "../" for example. See also + "path_dir". + +path_dir + Returns true when one of the strings is found isolated or delimited with + slashes in the path. This is used to perform filename or directory name + matching without the risk of wrong match due to colliding prefixes. See also + "url_dir" and "path_sub". + +path_dom + Returns true when one of the strings is found isolated or delimited with dots + in the path. This may be used to perform domain name matching in proxy + requests. See also "path_sub" and "url_dom". + +path_reg + Returns true when the path matches one of the regular expressions. It can be + used any time, but it is important to remember that regex matching is slower + than other methods. See also "url_reg" and all "path_" criteria. + +url + Applies to the whole URL passed in the request. The only real use is to match + "*", for which there already is a predefined ACL. + +url_beg + Returns true when the URL begins with one of the strings. This can be used to + check whether a URL begins with a slash or with a protocol scheme. + +url_end + Returns true when the URL ends with one of the strings. It has very limited + use. "path_end" should be used instead for filename matching. + +url_sub + Returns true when the URL contains one of the strings. It can be used to + detect particular patterns in query strings for example. See also "path_sub". + +url_dir + Returns true when one of the strings is found isolated or delimited with + slashes in the URL. This is used to perform filename or directory name + matching without the risk of wrong match due to colliding prefixes. See also + "path_dir" and "url_sub". + +url_dom + Returns true when one of the strings is found isolated or delimited with dots + in the URL. This is used to perform domain name matching without the risk of + wrong match due to colliding prefixes. See also "url_sub". + +url_reg + Returns true when the URL matches one of the regular expressions. It can be + used any time, but it is important to remember that regex matching is slower + than other methods. See also "path_reg" and all "url_" criteria. + +hdr +hdr(header) + Note: all the "hdr*" matching criteria either apply to all headers, or to a + particular header whose name is passed between parenthesis and without any + space. The header matching complies with RFC2616, and treats as separate + headers all values delimited by comas. + + The "hdr" criteria returns true if any of the headers matching the criteria + match any of the strings. This can be used to check exact values. For + instance, checking that "connection: close" is set : + + hdr(Connection) -i close + +hdr_beg +hdr_beg(header) + Returns true when one of the headers begins with one of the strings. See + "hdr" for more information on header matching. + +hdr_end +hdr_end(header) + Returns true when one of the headers ends with one of the strings. See "hdr" + for more information on header matching. + +hdr_sub +hdr_sub(header) + Returns true when one of the headers contains one of the strings. See "hdr" + for more information on header matching. + +hdr_dir +hdr_dir(header) + Returns true when one of the headers contains one of the strings either + isolated or delimited by slashes. This is used to perform filename or + directory name matching, and may be used with Referer. See "hdr" for more + information on header matching. + +hdr_dom +hdr_dom(header) + Returns true when one of the headers contains one of the strings either + isolated or delimited by dots. This is used to perform domain name matching, + and may be used with the Host header. See "hdr" for more information on + header matching. + +hdr_reg +hdr_reg(header) + Returns true when one of the headers matches of the regular expressions. It + can be used at any time, but it is important to remember that regex matching + is slower than other methods. See also other "hdr_" criteria, as well as + "hdr" for more information on header matching. + +hdr_val +hdr_val(header) + Returns true when one of the headers starts with a number which matches the + values or ranges specified. This may be used to limit content-length to + acceptable values for example. See "hdr" for more information on header + matching. + +hdr_cnt +hdr_cnt(header) + Returns true when the count of the headers which matches the values or ranges + specified. This is used to detect presence or absence of a specific header, + as well as to block request smugling attacks by rejecting requests which + contain more than one of certain headers. See "hdr" for more information on + header matching. + + +2.1.6) Pre-defined ACLs +----------------------- + +Some predefined ACLs are hard-coded so that they do not have to be declared in +every frontend which needs them. They all have their names in upper case in +order to avoid confusion. Their equivalence is provided below : + +ACL name Equivalent to Usage +---------------+-----------------------------+--------------------------------- +TRUE always_true 1 always match +FALSE always_false 0 never match +LOCALHOST src 127.0.0.1/8 match connection from local host +HTTP_1.0 req_ver 1.0 match HTTP version 1.0 +HTTP_1.1 req_ver 1.1 match HTTP version 1.1 +METH_CONNECT method CONNECT match HTTP CONNECT method +METH_GET method GET HEAD match HTTP GET or HEAD method +METH_HEAD method HEAD match HTTP HEAD method +METH_OPTIONS method OPTIONS match HTTP OPTIONS method +METH_POST method POST match HTTP POST method +METH_TRACE method TRACE match HTTP TRACE method +HTTP_URL_ABS url_reg ^[^/:]*:// match absolute URL with scheme +HTTP_URL_SLASH url_beg / match URL begining with "/" +HTTP_URL_STAR url * match URL equal to "*" +HTTP_CONTENT hdr_val(content-length) gt 0 match an existing content-length +---------------+-----------------------------+--------------------------------- + + +2.1.7) Using ACLs to form conditions +------------------------------------ + +Some actions are only performed upon a valid condition. A condition is a +combination of ACLs with operators. 3 operators are supported : + + - AND (implicit) + - OR (explicit with the "or" keyword or the "||" operator) + - Negation with the exclamation mark ("!") + +A condition is formed as a disjonctive form : + + [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ... + +Such conditions are generally used after an "if" or "unless" statement, +indicating when the condition will trigger the action. + +For instance, to block HTTP requests to the "*" URL with methods other than +"OPTIONS", as well as POST requests without content-length, and GET/HEAD +requests with a content-length greater than 0, and finally every request +which is not either GET/HEAD/POST/OPTIONS ! + + acl missing_cl hdr_cnt(Content-length) eq 0 + block if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl + block if METH_GET HTTP_CONTENT + block unless METH_GET or METH_POST or METH_OPTIONS + +To select a different backend for requests to static contents on the "www" site +and to every request on the "img", "video", "download" and "ftp" hosts : + + acl url_static path_beg /static /images /img /css + acl url_static path_end .gif .png .jpg .css .js + acl host_www hdr_beg(host) -i www + acl host_static hdr_beg(host) -i img. video. download. ftp. + + # now use backend "static" for all static-only hosts, and for static urls + # of host "www". Use backend "www" for the rest. + use_backend static if host_static or host_www url_static + use_backend www if host_www + +See below for the detailed help on the "block" and "use_backend" keywords.