---------------------- HAProxy Configuration Manual ---------------------- version 1.3.13 willy tarreau 2007/10/18 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 - stats * Performance tuning - maxconn - noepoll - nokqueue - nopoll - nosepoll - tune.maxpollevents - spread-checks * Debugging - debug - quiet 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". stats socket [{uid | user} ] [{gid | group} ] [mode ] Creates a UNIX socket in stream mode at location . Any previously existing socket will be backed up then replaced. Connections to this socket will get a CSV-formated output of the process statistics in response to the "show stat" command followed by a line feed. On platforms which support it, it is possible to restrict access to this socket by specifying numerical IDs after "uid" and "gid", or valid user and group names after the "user" and "group" keywords. It is also possible to restrict permissions on the socket by passing an octal value after the "mode" keyword (same syntax as chmod). Depending on the platform, the permissions on the socket will be inherited from the directory which hosts it, or from the user the process is started with. stats timeout The default timeout on the stats socket is set to 10 seconds. It is possible to change this value with "stats timeout". The value must be passed in milliseconds. stats maxconn By default, the stats socket is limited to 10 concurrent connections. It is possible to change this value with "stats maxconn". 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. spread-checks <0..50, in percent> Sometimes it is desirable to avoid sending health checks to servers at exact intervals, for instance when many logical servers are located on the same physical server. With the help of this parameter, it becomes possible to add some randomness in the check interval between 0 and +/- 50%. A value between 2 and 5 seems to show good results. The default value remains at 0. 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". 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 nolinger X 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 stats enable X - X X stats realm X - X X stats refresh X - X X stats scope X - X X stats uri X - X X stats hide-version 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.