diff --git a/.gitignore b/.gitignore index d747444..2825d07 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,4 @@ *.dvi *.ps *.xml +node_modules/ diff --git a/version-1-5/make.js b/version-1-5/tex.js similarity index 96% rename from version-1-5/make.js rename to version-1-5/tex.js index 96d5152..c5ab6e9 100644 --- a/version-1-5/make.js +++ b/version-1-5/tex.js @@ -1,9 +1,8 @@ /* - * HAProxy configuration book builder + * HAProxy configuration book builder for LaTeX * run it in node.js * $ node make.js * - * var m = require('make'); var parts = m.split_chapters(m.text); filenames = m.writeFiles(parts) */ var fs = require('fs'); @@ -53,7 +52,7 @@ var split_chapters = module.exports.split_chapters = function(text) { }; -var hasIndents = function(text) { +var hasIndents = function(text) { // identify tables too return text.match(/^( |----+)/mg) !== null; }; diff --git a/version-1-5/tex/configuration.pdf b/version-1-5/tex/configuration.pdf index 566f5c9..316d552 100644 Binary files a/version-1-5/tex/configuration.pdf and b/version-1-5/tex/configuration.pdf differ diff --git a/version-1-5/tex/configuration.tex b/version-1-5/tex/configuration.tex index 96abfc3..3b4ae83 100644 --- a/version-1-5/tex/configuration.tex +++ b/version-1-5/tex/configuration.tex @@ -35,6 +35,8 @@ \usepackage{multicol} %\usepackage{makeidx} %\usepackage{showidx} +\usepackage{longtable} +\usepackage{dashrule} \usepackage{hyperref} % For creating hyperlinks in cross references diff --git a/version-1-5/tex/ed_04--proxies.tex b/version-1-5/tex/ed_04--proxies.tex new file mode 100644 index 0000000..83a7bf7 --- /dev/null +++ b/version-1-5/tex/ed_04--proxies.tex @@ -0,0 +1,50 @@ +% This is generated content +% Section 4. + +\chapter{Proxies} + +Proxy configuration can be located in a set of sections: +\begin{itemize} +\item \keyword{defaults} \param{name} +\item \keyword{frontend} \param{name} +\item \keyword{backend} \param{name} +\item \keyword{listen} \param{name} +\end{itemize} + +A \keyword{defaults} section sets default parameters for all other sections following +its declaration. Those default parameters are reset by the next \keyword{defaults} +section. See below for the list of parameters which can be set in a \keyword{defaults} +section. The name is optional but its use is encouraged for better readability. + + +A \keyword{frontend} section describes a set of listening sockets accepting client +connections. + + +A \keyword{backend} section describes a set of servers to which the proxy will connect +to forward incoming connections. + + +A \keyword{listen} section defines a complete proxy with its frontend and backend +parts combined in one section. It is generally useful for TCP-only traffic. + + +All proxy names must be formed from upper and lower case letters, digits, +\CHAR{-} (dash), \CHAR{\_} (underscore) , \CHAR{.} (dot) and \CHAR{:} (colon). ACL names are +case-sensitive, which means that \CHAR{www} and \CHAR{WWW} are two different proxies. + + +Historically, all proxy names could overlap, it just caused troubles in the +logs. Since the introduction of content switching, it is mandatory that two +proxies with overlapping capabilities (frontend/backend) have different names. +However, it is still permitted that a frontend and a backend share the same +name, as this configuration seems to be commonly encountered. + + +Right now, two major proxy modes are supported: \texttt{tcp}, also known as layer 4, +and \texttt{http}, also known as layer 7. In layer 4 mode, HAProxy simply forwards +bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the +protocol, and can interact with it by allowing, blocking, switching, adding, +modifying, or removing arbitrary contents in requests or responses, based on +arbitrary criteria. + diff --git a/version-1-5/tex/ed_04-01--proxy-keywords-matrix.tex b/version-1-5/tex/ed_04-01--proxy-keywords-matrix.tex new file mode 100644 index 0000000..b485ce8 --- /dev/null +++ b/version-1-5/tex/ed_04-01--proxy-keywords-matrix.tex @@ -0,0 +1,176 @@ +% This is generated content +% Section 4.1. + +\section{Proxy keywords matrix} + +\newcommand{\NO}{--} +\newcommand{\YES}{$\times$} +\newcommand{\optnopr}{ $\neg$} +\newcommand{\deprecated}[1]{\textsl{{\color{gray}#1}}} +\newcommand{\depword}[1]{\texttt{\deprecated{#1}}} + +The following list of keywords is supported. Most of them may only be used in a +limited set of section types. Some of them are marked as \deprecated{deprecated} because +they are inherited from an old syntax which may be confusing or functionally +limited, and there are new recommended keywords to replace them. Keywords +marked with\optnopr{} can be optionally inverted using the \texttt{no} prefix, +eg.~\texttt{no option contstats}. This makes sense when the option has been enabled by default +and must be disabled for a specific instance. Such options may also be prefixed +with \emph{default} in order to restore default settings regardless of what has been +specified in a previous \keyword{defaults} section. + +\begin{longtable}{ l c c c c } +\hline +\textbf{keyword} & +\textbf{defaults} & \textbf{frontend} & \textbf{listen} & \textbf{backend} \\ \hline \hline +\endhead +\keyword{acl} & \NO & \YES & \YES & \YES \\ +\keyword{appsession} & \NO & \NO & \YES & \YES \\ +\keyword{backlog} & \YES & \YES & \YES & \NO \\ +\keyword{balance} & \YES & \NO & \YES & \YES \\ +\keyword{bind} & \NO & \YES & \YES & \NO \\ +\keyword{bind-process} & \YES & \YES & \YES & \YES \\ +\keyword{block} & \NO & \YES & \YES & \YES \\ +\keyword{capture cookie} & \NO & \YES & \YES & \NO \\ +\keyword{capture request header} & \NO & \YES & \YES & \NO \\ +\keyword{capture response header} & \NO & \YES & \YES & \NO \\ +\depword{clitimeout} & \YES & \YES & \YES & \NO \\ +\depword{contimeout} & \YES & \NO & \YES & \YES \\ +\keyword{cookie} & \YES & \NO & \YES & \YES \\ +\keyword{default-server} & \YES & \NO & \YES & \YES \\ +\keyword{default\_backend} & \YES & \YES & \YES & \NO \\ +\keyword{description} & \NO & \YES & \YES & \YES \\ +\keyword{disabled} & \YES & \YES & \YES & \YES \\ +\keyword{dispatch} & \NO & \NO & \YES & \YES \\ +\keyword{enabled} & \YES & \YES & \YES & \YES \\ +\keyword{errorfile} & \YES & \YES & \YES & \YES \\ +\keyword{errorloc} & \YES & \YES & \YES & \YES \\ +\keyword{errorloc302} & \YES & \YES & \YES & \YES \\ +\keyword{errorloc303} & \YES & \YES & \YES & \YES \\ +\keyword{force-persist} & \NO & \YES & \YES & \YES \\ +\keyword{fullconn} & \YES & \NO & \YES & \YES \\ +\keyword{grace} & \YES & \YES & \YES & \YES \\ +\keyword{hash-type} & \YES & \NO & \YES & \YES \\ +\keyword{http-check disable-on-404} & \YES & \NO & \YES & \YES \\ +\keyword{http-check expect} & \NO & \NO & \YES & \YES \\ +\keyword{http-check send-state} & \YES & \NO & \YES & \YES \\ +\keyword{http-request} & \NO & \YES & \YES & \YES \\ +\keyword{id} & \NO & \YES & \YES & \YES \\ +\keyword{ignore-persist} & \NO & \YES & \YES & \YES \\ +\keyword{log}\optnopr & \YES & \YES & \YES & \YES \\ +\keyword{maxconn} & \YES & \YES & \YES & \NO \\ +\keyword{mode} & \YES & \YES & \YES & \YES \\ +\keyword{monitor fail} & \NO & \YES & \YES & \NO \\ +\keyword{monitor-net} & \YES & \YES & \YES & \NO \\ +\keyword{monitor-uri} & \YES & \YES & \YES & \NO \\ +\keyword{option abortonclose}\optnopr & \YES & \NO & \YES & \YES \\ +\keyword{option accept-invalid-http-request}\optnopr & \YES & \YES & \YES & \NO \\ +\keyword{option accept-invalid-http-response}\optnopr & \YES & \NO & \YES & \YES \\ +\keyword{option allbackups}\optnopr & \YES & \NO & \YES & \YES \\ +\keyword{option checkcache}\optnopr & \YES & \NO & \YES & \YES \\ +\keyword{option clitcpka}\optnopr & \YES & \YES & \YES & \NO \\ +\keyword{option contstats}\optnopr & \YES & \YES & \YES & \NO \\ +\keyword{option dontlog-normal}\optnopr & \YES & \YES & \YES & \NO \\ +\keyword{option dontlognull}\optnopr & \YES & \YES & \YES & \NO \\ +\keyword{option forceclose}\optnopr & \YES & \YES & \YES & \YES \\ +\keyword{option forwardfor} & \YES & \YES & \YES & \YES \\ +\keyword{option http-no-delay}\optnopr & \YES & \YES & \YES & \YES \\ +\keyword{option http-pretend-keepalive}\optnopr & \YES & \YES & \YES & \YES \\ +\keyword{option http-server-close}\optnopr & \YES & \YES & \YES & \YES \\ +\keyword{option http-use-proxy-header}\optnopr & \YES & \YES & \YES & \NO \\ +\keyword{option httpchk} & \YES & \NO & \YES & \YES \\ +\keyword{option httpclose}\optnopr & \YES & \YES & \YES & \YES \\ +\keyword{option httplog} & \YES & \YES & \YES & \YES \\ +\keyword{option http\_proxy}\optnopr & \YES & \YES & \YES & \YES \\ +\keyword{option independant-streams}\optnopr & \YES & \YES & \YES & \YES \\ +\keyword{option ldap-check} & \YES & \NO & \YES & \YES \\ +\keyword{option log-health-checks}\optnopr & \YES & \NO & \YES & \YES \\ +\keyword{option log-separate-errors}\optnopr & \YES & \YES & \YES & \NO \\ +\keyword{option logasap}\optnopr & \YES & \YES & \YES & \NO \\ +\keyword{option mysql-check} & \YES & \NO & \YES & \YES \\ +\keyword{option pgsql-check} & \YES & \NO & \YES & \YES \\ +\keyword{option nolinger}\optnopr & \YES & \YES & \YES & \YES \\ +\keyword{option originalto} & \YES & \YES & \YES & \YES \\ +\keyword{option persist}\optnopr & \YES & \NO & \YES & \YES \\ +\keyword{option redispatch}\optnopr & \YES & \NO & \YES & \YES \\ +\keyword{option redis-check} & \YES & \NO & \YES & \YES \\ +\keyword{option smtpchk} & \YES & \NO & \YES & \YES \\ +\keyword{option socket-stats}\optnopr & \YES & \YES & \YES & \NO \\ +\keyword{option splice-auto}\optnopr & \YES & \YES & \YES & \YES \\ +\keyword{option splice-request}\optnopr & \YES & \YES & \YES & \YES \\ +\keyword{option splice-response}\optnopr & \YES & \YES & \YES & \YES \\ +\keyword{option srvtcpka}\optnopr & \YES & \NO & \YES & \YES \\ +\keyword{option ssl-hello-chk} & \YES & \NO & \YES & \YES \\ +\keyword{option tcp-smart-accept}\optnopr & \YES & \YES & \YES & \NO \\ +\keyword{option tcp-smart-connect}\optnopr & \YES & \NO & \YES & \YES \\ +\keyword{option tcpka} & \YES & \YES & \YES & \YES \\ +\keyword{option tcplog} & \YES & \YES & \YES & \YES \\ +\keyword{option transparent}\optnopr & \YES & \NO & \YES & \YES \\ +\keyword{persist rdp-cookie} & \YES & \NO & \YES & \YES \\ +\keyword{rate-limit sessions} & \YES & \YES & \YES & \NO \\ +\keyword{redirect} & \NO & \YES & \YES & \YES \\ +\depword{redisp} & \YES & \NO & \YES & \YES \\ +\depword{redispatch} & \YES & \NO & \YES & \YES \\ +\keyword{reqadd} & \NO & \YES & \YES & \YES \\ +\keyword{reqallow} & \NO & \YES & \YES & \YES \\ +\keyword{reqdel} & \NO & \YES & \YES & \YES \\ +\keyword{reqdeny} & \NO & \YES & \YES & \YES \\ +\keyword{reqiallow} & \NO & \YES & \YES & \YES \\ +\keyword{reqidel} & \NO & \YES & \YES & \YES \\ +\keyword{reqideny} & \NO & \YES & \YES & \YES \\ +\keyword{reqipass} & \NO & \YES & \YES & \YES \\ +\keyword{reqirep} & \NO & \YES & \YES & \YES \\ +\keyword{reqisetbe} & \NO & \YES & \YES & \YES \\ +\keyword{reqitarpit} & \NO & \YES & \YES & \YES \\ +\keyword{reqpass} & \NO & \YES & \YES & \YES \\ +\keyword{reqrep} & \NO & \YES & \YES & \YES \\ +\keyword{reqsetbe} & \NO & \YES & \YES & \YES \\ +\keyword{reqtarpit} & \NO & \YES & \YES & \YES \\ +\keyword{retries} & \YES & \NO & \YES & \YES \\ +\keyword{rspadd} & \NO & \YES & \YES & \YES \\ +\keyword{rspdel} & \NO & \YES & \YES & \YES \\ +\keyword{rspdeny} & \NO & \YES & \YES & \YES \\ +\keyword{rspidel} & \NO & \YES & \YES & \YES \\ +\keyword{rspideny} & \NO & \YES & \YES & \YES \\ +\keyword{rspirep} & \NO & \YES & \YES & \YES \\ +\keyword{rsprep} & \NO & \YES & \YES & \YES \\ +\keyword{server} & \NO & \NO & \YES & \YES \\ +\keyword{source} & \YES & \NO & \YES & \YES \\ +\depword{srvtimeout} & \YES & \NO & \YES & \YES \\ +\keyword{stats admin} & \NO & \NO & \YES & \YES \\ +\keyword{stats auth} & \YES & \NO & \YES & \YES \\ +\keyword{stats enable} & \YES & \NO & \YES & \YES \\ +\keyword{stats hide-version} & \YES & \NO & \YES & \YES \\ +\keyword{stats http-request} & \NO & \NO & \YES & \YES \\ +\keyword{stats realm} & \YES & \NO & \YES & \YES \\ +\keyword{stats refresh} & \YES & \NO & \YES & \YES \\ +\keyword{stats scope} & \YES & \NO & \YES & \YES \\ +\keyword{stats show-desc} & \YES & \NO & \YES & \YES \\ +\keyword{stats show-legends} & \YES & \NO & \YES & \YES \\ +\keyword{stats show-node} & \YES & \NO & \YES & \YES \\ +\keyword{stats uri} & \YES & \NO & \YES & \YES \\ +\keyword{stick match} & \NO & \NO & \YES & \YES \\ +\keyword{stick on} & \NO & \NO & \YES & \YES \\ +\keyword{stick store-request} & \NO & \NO & \YES & \YES \\ +\keyword{stick store-response} & \NO & \NO & \YES & \YES \\ +\keyword{stick-table} & \NO & \NO & \YES & \YES \\ +\keyword{tcp-request connection} & \NO & \YES & \YES & \NO \\ +\keyword{tcp-request content} & \NO & \YES & \YES & \YES \\ +\keyword{tcp-request inspect-delay} & \NO & \YES & \YES & \YES \\ +\keyword{tcp-response content} & \NO & \NO & \YES & \YES \\ +\keyword{tcp-response inspect-delay} & \NO & \NO & \YES & \YES \\ +\keyword{timeout check} & \YES & \NO & \YES & \YES \\ +\keyword{timeout client} & \YES & \YES & \YES & \NO \\ +\depword{timeout clitimeout} & \YES & \YES & \YES & \NO \\ +\keyword{timeout connect} & \YES & \NO & \YES & \YES \\ +\depword{timeout contimeout} & \YES & \NO & \YES & \YES \\ +\keyword{timeout http-keep-alive} & \YES & \YES & \YES & \YES \\ +\keyword{timeout http-request} & \YES & \YES & \YES & \YES \\ +\keyword{timeout queue} & \YES & \NO & \YES & \YES \\ +\keyword{timeout server} & \YES & \NO & \YES & \YES \\ +\depword{timeout srvtimeout} & \YES & \NO & \YES & \YES \\ +\keyword{timeout tarpit} & \YES & \YES & \YES & \YES \\ +\depword{transparent} & \YES & \NO & \YES & \YES \\ +\keyword{use\_backend} & \NO & \YES & \YES & \NO \\ +\end{longtable} + diff --git a/version-1-5/tex/ed_04-02--alphabetically-sorted-keywords-reference.tex b/version-1-5/tex/ed_04-02--alphabetically-sorted-keywords-reference.tex index 2705767..953b2d4 100644 --- a/version-1-5/tex/ed_04-02--alphabetically-sorted-keywords-reference.tex +++ b/version-1-5/tex/ed_04-02--alphabetically-sorted-keywords-reference.tex @@ -3,11 +3,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} -\begin{verbatim} - This section provides a description of each keyword and its usage. - +\begin{verbatim} acl [flags] [operator] ... Declare or complete an access list. May be used in sections : defaults | frontend | listen | backend @@ -16,10 +14,13 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} acl invalid_src src 0.0.0.0/7 224.0.0.0/3 acl invalid_src src_port 0:1023 acl local_dst hdr(host) -i localhost +\end{verbatim} +\begin{verbatim} See section 7 about ACL usage. +\end{verbatim} - +\begin{verbatim} appsession len timeout [request-learn] [prefix] [mode ] Define session stickiness on an existing application cookie. @@ -28,14 +29,20 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} Arguments : this is the name of the cookie used by the application and which HAProxy will have to learn for each new session. +\end{verbatim} +\begin{verbatim} this is the max number of characters that will be memorized and checked in each cookie value. +\end{verbatim} +\begin{verbatim} this is the time after which the cookie will be removed from memory if unused. If no unit is specified, this time is in milliseconds. +\end{verbatim} +\begin{verbatim} request-learn If this option is specified, then haproxy will be able to learn the cookie found in the request in case the server does not @@ -43,17 +50,25 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} PHPSESSID cookies, or when haproxy's session expires before the application's session and the correct server is selected. It is recommended to specify this option to improve reliability. +\end{verbatim} +\begin{verbatim} prefix When this option is specified, haproxy will match on the cookie prefix (or URL parameter prefix). The appsession value is the data following this prefix. +\end{verbatim} +\begin{verbatim} Example : appsession ASPSESSIONID len 64 timeout 3h prefix +\end{verbatim} +\begin{verbatim} This will match the cookie ASPSESSIONIDXXXX=XXXXX, the appsession value will be XXXX=XXXXX. +\end{verbatim} +\begin{verbatim} mode This option allows to change the URL parser mode. 2 modes are currently supported : - path-parameters : @@ -64,7 +79,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} - query-string : In this mode, the parser will look for the appsession in the query string. +\end{verbatim} +\begin{verbatim} When an application cookie is defined in a backend, HAProxy will check when the server sets such a cookie, and will store its value in a table, and associate it with the server's identifier. Up to characters from @@ -74,20 +91,29 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} server associated with this value. Otherwise, the load balancing algorithm is applied. Cookies are automatically removed from memory when they have been unused for a duration longer than . +\end{verbatim} +\begin{verbatim} The definition of an application cookie is limited to one per backend. +\end{verbatim} +\begin{verbatim} Note : Consider not using this feature in multi-process mode (nbproc > 1) unless you know what you do : memory is not shared between the processes, which can result in random behaviours. +\end{verbatim} +\begin{verbatim} Example : appsession JSESSIONID len 52 timeout 3h +\end{verbatim} +\begin{verbatim} See also : "cookie", "capture cookie", "balance", "stick", "stick-table", "ignore-persist", "nbproc" and "bind-process". +\end{verbatim} - +\begin{verbatim} backlog Give hints to the system about the approximate listen backlog desired size May be used in sections : defaults | frontend | listen | backend @@ -95,8 +121,10 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} Arguments : is the number of pending connections. Depending on the operating system, it may represent the number of already acknowledged - connections, of non-acknowledged ones, or both. + connections, of non-acknowledged ones, or both. +\end{verbatim} +\begin{verbatim} In order to protect against SYN flood attacks, one solution is to increase the system's SYN backlog size. Depending on the system, sometimes it is just tunable via a system parameter, sometimes it is not adjustable at all, and @@ -105,14 +133,19 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} to the listen() syscall. On systems which can make use of this value, it can sometimes be useful to be able to specify a different value, hence this backlog parameter. +\end{verbatim} +\begin{verbatim} On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is used as a hint and the system accepts up to the smallest greater power of two, and never more than some limits (usually 32768). +\end{verbatim} +\begin{verbatim} See also : "maxconn" and the target operating system's tuning guide. +\end{verbatim} - +\begin{verbatim} balance [ ] balance url_param [check_post []] Define the load balancing algorithm to be used in a backend. @@ -123,7 +156,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} balancing. This only applies when no persistence information is available, or when a connection is redispatched to another server. may be one of the following : +\end{verbatim} +\begin{verbatim} roundrobin Each server is used in turns, according to their weights. This is the smoothest and fairest algorithm when the server's processing time remains equally distributed. This algorithm @@ -136,7 +171,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} receiving traffic. This is normal, though very rare. It is indicated here in case you would have the chance to observe it, so that you don't worry. +\end{verbatim} +\begin{verbatim} static-rr Each server is used in turns, according to their weights. This algorithm is as similar to roundrobin except that it is static, which means that changing a server's weight on the @@ -145,7 +182,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} up, it is always immediately reintroduced into the farm, once the full map is recomputed. It also uses slightly less CPU to run (around -1%). +\end{verbatim} +\begin{verbatim} leastconn The server with the lowest number of connections receives the connection. Round-robin is performed within groups of servers of the same load to ensure that all servers will be used. Use @@ -154,7 +193,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} suited for protocols using short sessions such as HTTP. This algorithm is dynamic, which means that server weights may be adjusted on the fly for slow starts for instance. +\end{verbatim} +\begin{verbatim} source The source IP address is hashed and divided by the total weight of the running servers to designate which server will receive the request. This ensures that the same client IP @@ -168,7 +209,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} static by default, which means that changing a server's weight on the fly will have no effect, but this can be changed using "hash-type". +\end{verbatim} +\begin{verbatim} uri The left part of the URI (before the question mark) is hashed and divided by the total weight of the running servers. The result designates which server will receive the request. This @@ -179,7 +222,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} in an HTTP backend. This algorithm is static by default, which means that changing a server's weight on the fly will have no effect, but this can be changed using "hash-type". +\end{verbatim} +\begin{verbatim} This algorithm support two optional parameters "len" and "depth", both followed by a positive integer number. These options may be helpful when it is needed to balance servers @@ -188,41 +233,51 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} characters at the beginning of the URI to compute the hash. Note that having "len" set to 1 rarely makes sense since most URIs start with a leading "/". +\end{verbatim} +\begin{verbatim} The "depth" parameter indicates the maximum directory depth to be used to compute the hash. One level is counted for each slash in the request. If both parameters are specified, the evaluation stops when either is reached. +\end{verbatim} +\begin{verbatim} url_param The URL parameter specified in argument will be looked up in the query string of each HTTP GET request. +\end{verbatim} +\begin{verbatim} If the modifier "check_post" is used, then an HTTP POST - request entity will be searched for the parameter argument, - when it is not found in a query string after a question mark - ('?') in the URL. Optionally, specify a number of octets to - wait for before attempting to search the message body. If the - entity can not be searched, then round robin is used for each - request. For instance, if your clients always send the LB - parameter in the first 128 bytes, then specify that. The - default is 48. The entity data will not be scanned until the - required number of octets have arrived at the gateway, this - is the minimum of: (default/max_wait, Content-Length or first - chunk length). If Content-Length is missing or zero, it does - not need to wait for more data than the client promised to - send. When Content-Length is present and larger than - , then waiting is limited to and it is - assumed that this will be enough data to search for the - presence of the parameter. In the unlikely event that - Transfer-Encoding: chunked is used, only the first chunk is - scanned. Parameter values separated by a chunk boundary, may - be randomly balanced if at all. + request entity will be searched for the parameter argument, + when it is not found in a query string after a question mark + ('?') in the URL. Optionally, specify a number of octets to + wait for before attempting to search the message body. If the + entity can not be searched, then round robin is used for each + request. For instance, if your clients always send the LB + parameter in the first 128 bytes, then specify that. The + default is 48. The entity data will not be scanned until the + required number of octets have arrived at the gateway, this + is the minimum of: (default/max_wait, Content-Length or first + chunk length). If Content-Length is missing or zero, it does + not need to wait for more data than the client promised to + send. When Content-Length is present and larger than + , then waiting is limited to and it is + assumed that this will be enough data to search for the + presence of the parameter. In the unlikely event that + Transfer-Encoding: chunked is used, only the first chunk is + scanned. Parameter values separated by a chunk boundary, may + be randomly balanced if at all. +\end{verbatim} +\begin{verbatim} If the parameter is found followed by an equal sign ('=') and a value, then the value is hashed and divided by the total weight of the running servers. The result designates which server will receive the request. +\end{verbatim} +\begin{verbatim} This is used to track user identifiers in requests and ensure that a same user ID will always be sent to the same server as long as no server goes up or down. If no value is found or if @@ -231,22 +286,30 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} backend. This algorithm is static by default, which means that changing a server's weight on the fly will have no effect, but this can be changed using "hash-type". +\end{verbatim} +\begin{verbatim} hdr() The HTTP header will be looked up in each HTTP request. Just as with the equivalent ACL 'hdr()' function, the header name in parenthesis is not case sensitive. If the header is absent or if it does not contain any value, the roundrobin algorithm is applied instead. +\end{verbatim} +\begin{verbatim} An optional 'use_domain_only' parameter is available, for reducing the hash algorithm to the main domain part with some specific headers such as 'Host'. For instance, in the Host value "haproxy.1wt.eu", only "1wt" will be considered. +\end{verbatim} +\begin{verbatim} This algorithm is static by default, which means that changing a server's weight on the fly will have no effect, but this can be changed using "hash-type". +\end{verbatim} +\begin{verbatim} rdp-cookie rdp-cookie() The RDP cookie (or "mstshash" if omitted) will be @@ -257,29 +320,43 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} same user (or the same session ID) to the same server. If the cookie is not found, the normal roundrobin algorithm is used instead. +\end{verbatim} +\begin{verbatim} Note that for this to work, the frontend must ensure that an RDP cookie is already present in the request buffer. For this you must use 'tcp-request content accept' rule combined with a 'req_rdp_cookie_cnt' ACL. +\end{verbatim} +\begin{verbatim} This algorithm is static by default, which means that changing a server's weight on the fly will have no effect, but this can be changed using "hash-type". +\end{verbatim} - See also the rdp_cookie pattern fetch function. +\begin{verbatim} + See also the rdp_cookie pattern fetch function. +\end{verbatim} +\begin{verbatim} is an optional list of arguments which may be needed by some algorithms. Right now, only "url_param" and "uri" support an optional argument. +\end{verbatim} +\begin{verbatim} balance uri [len ] [depth ] balance url_param [check_post []] +\end{verbatim} +\begin{verbatim} The load balancing algorithm of a backend is set to roundrobin when no other algorithm, mode nor option have been set. The algorithm may only be set once for each backend. +\end{verbatim} +\begin{verbatim} Examples : balance roundrobin balance url_param userid @@ -287,43 +364,62 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} balance hdr(User-Agent) balance hdr(host) balance hdr(Host) use_domain_only +\end{verbatim} +\begin{verbatim} Note: the following caveats and limitations on using the "check_post" extension with "url_param" must be considered : +\end{verbatim} +\begin{verbatim} - all POST requests are eligible for consideration, because there is no way to determine if the parameters will be found in the body or entity which may contain binary data. Therefore another method may be required to restrict consideration of POST requests that have no URL parameters in the body. (see acl reqideny http_end) +\end{verbatim} +\begin{verbatim} - using a value larger than the request buffer size does not make sense and is useless. The buffer size is set at build time, and defaults to 16 kB. +\end{verbatim} +\begin{verbatim} - Content-Encoding is not supported, the parameter search will probably fail; and load balancing will fall back to Round Robin. +\end{verbatim} +\begin{verbatim} - Expect: 100-continue is not supported, load balancing will fall back to Round Robin. +\end{verbatim} +\begin{verbatim} - Transfer-Encoding (RFC2616 3.6.1) is only supported in the first chunk. If the entire parameter value is not present in the first chunk, the selection of server is undefined (actually, defined by how little actually appeared in the first chunk). +\end{verbatim} +\begin{verbatim} - This feature does not support generation of a 100, 411 or 501 response. +\end{verbatim} +\begin{verbatim} - In some cases, requesting "check_post" MAY attempt to scan the entire contents of a message body. Scanning normally terminates when linear white space or control characters are found, indicating the end of what might be a URL parameter list. This is probably not a concern with SGML type message bodies. +\end{verbatim} +\begin{verbatim} See also : "dispatch", "cookie", "appsession", "transparent", "hash-type" and "http_proxy". +\end{verbatim} - +\begin{verbatim} bind [
]: [, ...] bind [
]: [, ...] interface bind [
]: [, ...] mss @@ -345,7 +441,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} listen on. If unset, all IPv4 addresses of the system will be listened on. The same will apply for '*' or the system's special address "0.0.0.0". The IPv6 equivalent is '::'. +\end{verbatim} +\begin{verbatim} is either a unique TCP port, or a port range for which the proxy will accept connections for the IP address specified above. The port is mandatory for TCP listeners. Note that in @@ -355,7 +453,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} - a dash-delimited ports range explicitly stating the lower and upper bounds (ex: '2000-2100') which are included in the range. +\end{verbatim} +\begin{verbatim} Particular care must be taken against port ranges, because every couple consumes one socket (= a file descriptor), so it's easy to consume lots of descriptors @@ -365,7 +465,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} to ports lower than 1024 generally require particular privileges to start the program, which are independant of the 'uid' parameter. +\end{verbatim} +\begin{verbatim} is a UNIX socket path beginning with a slash ('/'). This is alternative to the TCP listening port. Haproxy will then receive UNIX connections on the socket located at this place. @@ -374,7 +476,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} the global section. Note that the total length of the prefix followed by the socket path cannot exceed some system limits for UNIX sockets, which commonly are set to 107 characters. +\end{verbatim} +\begin{verbatim} is an optional physical interface name. This is currently only supported on Linux. The interface must be a physical interface, not an aliased interface. When specified, all @@ -385,7 +489,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} Note that binding to a physical interface requires root privileges. This parameter is only compatible with TCP sockets. +\end{verbatim} +\begin{verbatim} is an optional TCP Maximum Segment Size (MSS) value to be advertised on incoming connections. This can be used to force a lower MSS for certain specific ports, for instance for @@ -400,39 +506,55 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} will indicate by how much to reduce the incoming connection's advertised MSS for outgoing segments. This parameter is only compatible with TCP sockets. +\end{verbatim} +\begin{verbatim} is a persistent value for socket ID. Must be positive and unique in the proxy. An unused value will automatically be assigned if unset. Can only be used when defining only a single socket. +\end{verbatim} +\begin{verbatim} is an optional name provided for stats +\end{verbatim} +\begin{verbatim} is the octal mode used to define access permissions on the UNIX socket. It can also be set by default in the global section's "unix-bind" statement. Note that some platforms simply ignore this. +\end{verbatim} +\begin{verbatim} is the name of user that will be marked owner of the UNIX socket. It can also be set by default in the global section's "unix-bind" statement. Note that some platforms simply ignore this. +\end{verbatim} +\begin{verbatim} is the name of a group that will be used to create the UNIX socket. It can also be set by default in the global section's "unix-bind" statement. Note that some platforms simply ignore this. +\end{verbatim} +\begin{verbatim} is the uid of user that will be marked owner of the UNIX socket. It can also be set by default in the global section's "unix-bind" statement. Note that some platforms simply ignore this. +\end{verbatim} +\begin{verbatim} is the gid of a group that will be used to create the UNIX socket. It can also be set by default in the global section's "unix-bind" statement. Note that some platforms simply ignore this. +\end{verbatim} +\begin{verbatim} transparent is an optional keyword which is supported only on certain Linux kernels. It indicates that the addresses will be bound even if they do not belong to the local machine. Any packet @@ -443,7 +565,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} the specified port. This keyword is available only when HAProxy is built with USE_LINUX_TPROXY=1. This parameter is only compatible with TCP sockets. +\end{verbatim} +\begin{verbatim} defer-accept is an optional keyword which is supported only on certain Linux kernels. It states that a connection will only be accepted once some data arrive on it, or at worst after the @@ -457,7 +581,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} never accepted until the client talks. This can cause issues with front firewalls which would see an established connection while the proxy will only see it in SYN_RECV. +\end{verbatim} +\begin{verbatim} accept-proxy is an optional keyword which enforces use of the PROXY protocol over any connection accepted by this listener. The PROXY protocol dictates the layer 3/4 addresses of the @@ -470,23 +596,30 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} can be used as an efficient and reliable alternative to the X-Forwarded-For mechanism which is not always reliable and not even always usable. +\end{verbatim} +\begin{verbatim} It is possible to specify a list of address:port combinations delimited by commas. The frontend will then listen on all of these addresses. There is no fixed limit to the number of addresses and ports which can be listened on in a frontend, as well as there is no limit to the number of "bind" statements in a frontend. +\end{verbatim} +\begin{verbatim} Example : listen http_proxy bind :80,:443 bind 10.0.0.1:10080,10.0.0.1:10443 bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy +\end{verbatim} +\begin{verbatim} See also : "source", "option forwardfor", "unix-bind" and the PROXY protocol documentation. +\end{verbatim} - +\begin{verbatim} bind-process [ all | odd | even | ] ... Limit visibility of an instance to a certain set of processes numbers. May be used in sections : defaults | frontend | listen | backend @@ -494,71 +627,99 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} Arguments : all All process will see this instance. This is the default. It may be used to override a default value. +\end{verbatim} +\begin{verbatim} odd This instance will be enabled on processes 1,3,5,...31. This option may be combined with other numbers. +\end{verbatim} +\begin{verbatim} even This instance will be enabled on processes 2,4,6,...32. This option may be combined with other numbers. Do not use it with less than 2 processes otherwise some instances might be missing from all processes. +\end{verbatim} +\begin{verbatim} number The instance will be enabled on this process number, between 1 and 32. You must be careful not to reference a process number greater than the configured global.nbproc, otherwise some instances might be missing from all processes. +\end{verbatim} +\begin{verbatim} This keyword limits binding of certain instances to certain processes. This is useful in order not to have too many processes listening to the same ports. For instance, on a dual-core machine, it might make sense to set 'nbproc 2' in the global section, then distributes the listeners among 'odd' and 'even' instances. +\end{verbatim} +\begin{verbatim} At the moment, it is not possible to reference more than 32 processes using this keyword, but this should be more than enough for most setups. Please note that 'all' really means all processes and is not limited to the first 32. +\end{verbatim} +\begin{verbatim} If some backends are referenced by frontends bound to other processes, the backend automatically inherits the frontend's processes. +\end{verbatim} +\begin{verbatim} Example : listen app_ip1 bind 10.0.0.1:80 bind-process odd +\end{verbatim} +\begin{verbatim} listen app_ip2 bind 10.0.0.2:80 bind-process even +\end{verbatim} +\begin{verbatim} listen management bind 10.0.0.3:80 bind-process 1 2 3 4 +\end{verbatim} +\begin{verbatim} See also : "nbproc" in global section. +\end{verbatim} - +\begin{verbatim} block { if | unless } Block a layer 7 request if/unless a condition is matched May be used in sections : defaults | frontend | listen | backend no | yes | yes | yes +\end{verbatim} +\begin{verbatim} The HTTP request will be blocked very early in the layer 7 processing if/unless is matched. A 403 error will be returned if the request is blocked. The condition has to reference ACLs (see section 7). This is typically used to deny access to certain sensitive resources if some conditions are met or not met. There is no fixed limit to the number of "block" statements per instance. +\end{verbatim} +\begin{verbatim} Example: acl invalid_src src 0.0.0.0/7 224.0.0.0/3 acl invalid_src src_port 0:1023 acl local_dst hdr(host) -i localhost block if invalid_src || local_dst +\end{verbatim} +\begin{verbatim} See section 7 about ACL usage. +\end{verbatim} - +\begin{verbatim} capture cookie len Capture and log a cookie in the request and in the response. May be used in sections : defaults | frontend | listen | backend @@ -569,35 +730,48 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} sign ('='). The full name will appear in the logs, which is useful with application servers which adjust both the cookie name and value (eg: ASPSESSIONXXXXX). +\end{verbatim} +\begin{verbatim} is the maximum number of characters to report in the logs, which include the cookie name, the equal sign and the value, all in the standard "name=value" form. The string will be truncated on the right if it exceeds . +\end{verbatim} +\begin{verbatim} Only the first cookie is captured. Both the "cookie" request headers and the "set-cookie" response headers are monitored. This is particularly useful to check for application bugs causing session crossing or stealing between users, because generally the user's cookies can only change on a login page. +\end{verbatim} +\begin{verbatim} When the cookie was not presented by the client, the associated log column will report "-". When a request does not cause a cookie to be assigned by the server, a "-" is reported in the response column. +\end{verbatim} +\begin{verbatim} The capture is performed in the frontend only because it is necessary that the log format does not change for a given frontend depending on the backends. This may change in the future. Note that there can be only one "capture cookie" statement in a frontend. The maximum capture length is configured in the sources by default to 64 characters. It is not possible to specify a capture in a "defaults" section. +\end{verbatim} +\begin{verbatim} Example: capture cookie ASPSESSION len 32 +\end{verbatim} +\begin{verbatim} See also : "capture request header", "capture response header" as well as section 8 about logging. +\end{verbatim} - +\begin{verbatim} capture request header len Capture and log the first occurrence of the specified request header. May be used in sections : defaults | frontend | listen | backend @@ -608,11 +782,15 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} appear in the requests, with the first letter of each word in upper case. The header name will not appear in the logs, only the value is reported, but the position in the logs is respected. +\end{verbatim} +\begin{verbatim} is the maximum number of characters to extract from the value and report in the logs. The string will be truncated on the right if it exceeds . +\end{verbatim} +\begin{verbatim} Only the first value of the last occurrence of the header is captured. The value will be added to the logs between braces ('{}'). If multiple headers are captured, they will be delimited by a vertical bar ('|') and will appear @@ -622,26 +800,35 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} "Content-length" when uploads are supported, "User-agent" to quickly differentiate between real users and robots, and "X-Forwarded-For" in proxied environments to find where the request came from. +\end{verbatim} +\begin{verbatim} Note that when capturing headers such as "User-agent", some spaces may be logged, making the log analysis more difficult. Thus be careful about what you log if you know your log parser is not smart enough to rely on the braces. +\end{verbatim} +\begin{verbatim} There is no limit to the number of captured request headers, but each capture is limited to 64 characters. In order to keep log format consistent for a same frontend, header captures can only be declared in a frontend. It is not possible to specify a capture in a "defaults" section. +\end{verbatim} +\begin{verbatim} Example: capture request header Host len 15 capture request header X-Forwarded-For len 15 capture request header Referrer len 15 +\end{verbatim} +\begin{verbatim} See also : "capture cookie", "capture response header" as well as section 8 about logging. +\end{verbatim} - +\begin{verbatim} capture response header len Capture and log the first occurrence of the specified response header. May be used in sections : defaults | frontend | listen | backend @@ -652,11 +839,15 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} appear in the response, with the first letter of each word in upper case. The header name will not appear in the logs, only the value is reported, but the position in the logs is respected. +\end{verbatim} +\begin{verbatim} is the maximum number of characters to extract from the value and report in the logs. The string will be truncated on the right if it exceeds . +\end{verbatim} +\begin{verbatim} Only the first value of the last occurrence of the header is captured. The result will be added to the logs between braces ('{}') after the captured request headers. If multiple headers are captured, they will be delimited by @@ -665,20 +856,27 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} string. Common uses for response header captures include the "Content-length" header which indicates how many bytes are expected to be returned, the "Location" header to track redirections. +\end{verbatim} +\begin{verbatim} There is no limit to the number of captured response headers, but each capture is limited to 64 characters. In order to keep log format consistent for a same frontend, header captures can only be declared in a frontend. It is not possible to specify a capture in a "defaults" section. +\end{verbatim} +\begin{verbatim} Example: capture response header Content-length len 9 capture response header Location len 15 +\end{verbatim} +\begin{verbatim} See also : "capture cookie", "capture request header" as well as section 8 about logging. +\end{verbatim} - +\begin{verbatim} clitimeout (deprecated) Set the maximum inactivity time on the client side. May be used in sections : defaults | frontend | listen | backend @@ -687,7 +885,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} is the timeout value is 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. +\end{verbatim} +\begin{verbatim} The inactivity timeout applies when the client is expected to acknowledge or send data. In HTTP mode, this timeout is particularly important to consider during the first phase, when the client sends the request, and during the @@ -699,21 +899,28 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} situations to debug. It is a good practice to cover one or several TCP packet losses by specifying timeouts that are slightly above multiples of 3 seconds (eg: 4 or 5 seconds). +\end{verbatim} +\begin{verbatim} This parameter is specific to frontends, but can be specified once for all in "defaults" sections. This is in fact one of the easiest solutions not to forget about it. An unspecified timeout results in an infinite timeout, which is not recommended. Such a usage is accepted and works but reports a warning during startup because it may results in accumulation of expired sessions in the system if the system's timeouts are not configured either. +\end{verbatim} +\begin{verbatim} This parameter is provided for compatibility but is currently deprecated. Please use "timeout client" instead. +\end{verbatim} +\begin{verbatim} See also : "timeout client", "timeout http-request", "timeout server", and "srvtimeout". +\end{verbatim} - +\begin{verbatim} contimeout (deprecated) Set the maximum time to wait for a connection attempt to a server to succeed. May be used in sections : defaults | frontend | listen | backend @@ -722,7 +929,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} is the timeout value is 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. +\end{verbatim} +\begin{verbatim} If the server is located on the same LAN as haproxy, the connection should be immediate (less than a few milliseconds). Anyway, it is a good practice to cover one or several TCP packet losses by specifying timeouts that are @@ -730,22 +939,29 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} connect timeout also presets the queue timeout to the same value if this one has not been specified. Historically, the contimeout was also used to set the tarpit timeout in a listen section, which is not possible in a pure frontend. +\end{verbatim} +\begin{verbatim} This parameter is specific to backends, but can be specified once for all in "defaults" sections. This is in fact one of the easiest solutions not to forget about it. An unspecified timeout results in an infinite timeout, which is not recommended. Such a usage is accepted and works but reports a warning during startup because it may results in accumulation of failed sessions in the system if the system's timeouts are not configured either. +\end{verbatim} +\begin{verbatim} This parameter is provided for backwards compatibility but is currently deprecated. Please use "timeout connect", "timeout queue" or "timeout tarpit" instead. +\end{verbatim} +\begin{verbatim} See also : "timeout connect", "timeout queue", "timeout tarpit", "timeout server", "contimeout". +\end{verbatim} - +\begin{verbatim} cookie [ rewrite | insert | prefix ] [ indirect ] [ nocache ] [ postonly ] [ preserve ] [ domain ]* [ maxidle ] [ maxlife ] @@ -762,7 +978,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} backends are subject to be used by the same clients (eg: HTTP/HTTPS), care should be taken to use different cookie names between all backends if persistence between them is not desired. +\end{verbatim} +\begin{verbatim} rewrite This keyword indicates that the cookie will be provided by the server and that haproxy will have to modify its value to set the server's identifier in it. This mode is handy when the management @@ -774,10 +992,14 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} very complex and/or broken, it is advised not to start with this mode for new deployments. This keyword is incompatible with "insert" and "prefix". +\end{verbatim} +\begin{verbatim} insert This keyword indicates that the persistence cookie will have to be inserted by haproxy in server responses if the client did not +\end{verbatim} +\begin{verbatim} already have a cookie that would have permitted it to access this server. When used without the "preserve" option, if the server emits a cookie with the same name, it will be remove before @@ -789,7 +1011,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} caching effects, it is generally wise to add the "nocache" or "postonly" keywords (see below). The "insert" keyword is not compatible with "rewrite" and "prefix". +\end{verbatim} +\begin{verbatim} prefix This keyword indicates that instead of relying on a dedicated cookie for the persistence, an existing one will be completed. This may be needed in some specific environments where the client @@ -803,7 +1027,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} not compatible with "rewrite" and "insert". Note: it is highly recommended not to use "indirect" with "prefix", otherwise server cookie updates would not be sent to clients. +\end{verbatim} +\begin{verbatim} indirect When this option is specified, no cookie will be emitted to a client which already has a valid one for the server which has processed the request. If the server sets such a cookie itself, @@ -814,7 +1040,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} Note: it is highly recommended not to use "indirect" with "prefix", otherwise server cookie updates would not be sent to clients. +\end{verbatim} +\begin{verbatim} nocache This option is recommended in conjunction with the insert mode when there is a cache between the client and HAProxy, as it ensures that a cacheable response will be tagged non-cacheable if @@ -824,7 +1052,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} outer cache and will all share the same persistence cookie, leading to one server receiving much more traffic than others. See also the "insert" and "postonly" options. +\end{verbatim} +\begin{verbatim} postonly This option ensures that cookie insertion will only be performed on responses to POST requests. It is an alternative to the "nocache" option, because POST responses are not cacheable, so @@ -834,7 +1064,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} efficient method to optimize caching without risking to find a persistence cookie in the cache. See also the "insert" and "nocache" options. +\end{verbatim} +\begin{verbatim} preserve This option may only be used with "insert" and/or "indirect". It allows the server to emit the persistence cookie itself. In this case, if a cookie is found in the response, haproxy will leave it @@ -845,7 +1077,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} check option, it is possible to perform a completely graceful shutdown because users will definitely leave the server after they logout. +\end{verbatim} +\begin{verbatim} domain This option allows to specify the domain at which a cookie is inserted. It requires exactly one parameter: a valid domain name. If the domain begins with a dot, the browser is allowed to @@ -854,7 +1088,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} times. Some browsers might have small limits on the number of domains, so be careful when doing that. For the record, sending 10 domains to MSIE 6 or Firefox 2 works as expected. +\end{verbatim} +\begin{verbatim} maxidle This option allows inserted cookies to be ignored after some idle time. It only works with insert-mode cookies. When a cookie is sent to the client, the date this cookie was emitted is sent too. @@ -870,7 +1106,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} date in the future further than 24 hours are ignored. Doing so lets admins fix timezone issues without risking kicking users off the site. +\end{verbatim} +\begin{verbatim} maxlife This option allows inserted cookies to be ignored after some life time, whether they're in use or not. It only works with insert mode cookies. When a cookie is first sent to the client, the date @@ -887,22 +1125,29 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} too long on the same server (eg: after a farm size change). This is stronger than the maxidle method in that it forces a redispatch after some absolute delay. +\end{verbatim} +\begin{verbatim} There can be only one persistence cookie per HTTP backend, and it can be declared in a defaults section. The value of the cookie will be the value indicated after the "cookie" keyword in a "server" statement. If no cookie is declared for a given server, the cookie is not set. +\end{verbatim} +\begin{verbatim} Examples : cookie JSESSIONID prefix cookie SRV insert indirect nocache cookie SRV insert postonly indirect cookie SRV insert indirect nocache maxidle 30m maxlife 8h +\end{verbatim} +\begin{verbatim} See also : "appsession", "balance source", "capture cookie", "server" and "ignore-persist". +\end{verbatim} - +\begin{verbatim} default-server [param*] Change default options for a server in a backend May be used in sections : defaults | frontend | listen | backend @@ -912,40 +1157,55 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} keyword accepts an important number of options and has a complete section dedicated to it. Please refer to section 5 for more details. +\end{verbatim} +\begin{verbatim} Example : default-server inter 1000 weight 13 +\end{verbatim} +\begin{verbatim} See also: "server" and section 5 about server options +\end{verbatim} - +\begin{verbatim} default_backend Specify the backend to use when no "use_backend" rule has been matched. May be used in sections : defaults | frontend | listen | backend yes | yes | yes | no Arguments : is the name of the backend to use. +\end{verbatim} +\begin{verbatim} When doing content-switching between frontend and backends using the "use_backend" keyword, it is often useful to indicate which backend will be used when no rule has matched. It generally is the dynamic backend which will catch all undetermined requests. +\end{verbatim} +\begin{verbatim} Example : +\end{verbatim} +\begin{verbatim} use_backend dynamic if url_dyn use_backend static if url_css url_img extension_img default_backend dynamic +\end{verbatim} +\begin{verbatim} See also : "use_backend", "reqsetbe", "reqisetbe" +\end{verbatim} - -disabled +\begin{verbatim} Disable a proxy, frontend or backend. May be used in sections : defaults | frontend | listen | backend yes | yes | yes | yes Arguments : none +\end{verbatim} +\begin{verbatim} The "disabled" keyword is used to disable an instance, mainly in order to liberate a listening port or to temporarily disable a service. The instance will still be created and its configuration will be checked, but it will be @@ -953,45 +1213,61 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} will not receive any traffic nor will it send any health-checks or logs. It is possible to disable many instances at once by adding the "disabled" keyword in a "defaults" section. +\end{verbatim} +\begin{verbatim} See also : "enabled" +\end{verbatim} - +\begin{verbatim} dispatch
: Set a default server address May be used in sections : defaults | frontend | listen | backend no | no | yes | yes Arguments : none +\end{verbatim} +\begin{verbatim}
is the IPv4 address of the default server. Alternatively, a resolvable hostname is supported, but this name will be resolved during start-up. +\end{verbatim} +\begin{verbatim} is a mandatory port specification. All connections will be sent to this port, and it is not permitted to use port offsets as is possible with normal servers. +\end{verbatim} +\begin{verbatim} The "dispatch" keyword designates a default server for use when no other server can take the connection. In the past it was used to forward non persistent connections to an auxiliary load balancer. Due to its simple syntax, it has also been used for simple TCP relays. It is recommended not to use it for more clarity, and to use the "server" directive instead. +\end{verbatim} +\begin{verbatim} See also : "server" +\end{verbatim} - -enabled +\begin{verbatim} Enable a proxy, frontend or backend. May be used in sections : defaults | frontend | listen | backend yes | yes | yes | yes Arguments : none +\end{verbatim} +\begin{verbatim} The "enabled" keyword is used to explicitly enable an instance, when the defaults has been set to "disabled". This is very rarely used. +\end{verbatim} +\begin{verbatim} See also : "disabled" +\end{verbatim} - +\begin{verbatim} errorfile Return a file contents instead of errors generated by HAProxy May be used in sections : defaults | frontend | listen | backend @@ -999,45 +1275,62 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} Arguments : is the HTTP status code. Currently, HAProxy is capable of generating codes 200, 400, 403, 408, 500, 502, 503, and 504. +\end{verbatim} +\begin{verbatim} designates a file containing the full HTTP response. It is recommended to follow the common practice of appending ".http" to the filename so that people do not confuse the response with HTML error pages, and to use absolute paths, since files are read before any chroot is performed. +\end{verbatim} +\begin{verbatim} It is important to understand that this keyword is not meant to rewrite errors returned by the server, but errors detected and returned by HAProxy. This is why the list of supported errors is limited to a small set. +\end{verbatim} +\begin{verbatim} Code 200 is emitted in response to requests matching a "monitor-uri" rule. +\end{verbatim} +\begin{verbatim} The files are returned verbatim on the TCP socket. This allows any trick such as redirections to another URL or site, as well as tricks to clean cookies, force enable or disable caching, etc... The package provides default error files returning the same contents as default errors. +\end{verbatim} +\begin{verbatim} The files should not exceed the configured buffer size (BUFSIZE), which generally is 8 or 16 kB, otherwise they will be truncated. It is also wise not to put any reference to local contents (eg: images) in order to avoid loops between the client and HAProxy when all servers are down, causing an error to be returned instead of an image. For better HTTP compliance, it is recommended that all header lines end with CR-LF and not LF alone. +\end{verbatim} +\begin{verbatim} The files are read at the same time as the configuration and kept in memory. For this reason, the errors continue to be returned even when the process is chrooted, and no file change is considered while the process is running. A simple method for developing those files consists in associating them to the 403 status code and interrogating a blocked URL. +\end{verbatim} +\begin{verbatim} See also : "errorloc", "errorloc302", "errorloc303" +\end{verbatim} +\begin{verbatim} Example : errorfile 400 /etc/haproxy/errorfiles/400badreq.http errorfile 403 /etc/haproxy/errorfiles/403forbid.http errorfile 503 /etc/haproxy/errorfiles/503sorry.http +\end{verbatim} - +\begin{verbatim} errorloc errorloc302 Return an HTTP redirection to a URL instead of errors generated by HAProxy @@ -1046,19 +1339,27 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} Arguments : is the HTTP status code. Currently, HAProxy is capable of generating codes 200, 400, 403, 408, 500, 502, 503, and 504. +\end{verbatim} +\begin{verbatim} it is the exact contents of the "Location" header. It may contain either a relative URI to an error page hosted on the same site, or an absolute URI designating an error page on another site. Special care should be given to relative URIs to avoid redirect loops if the URI itself may generate the same error (eg: 500). +\end{verbatim} +\begin{verbatim} It is important to understand that this keyword is not meant to rewrite errors returned by the server, but errors detected and returned by HAProxy. This is why the list of supported errors is limited to a small set. +\end{verbatim} +\begin{verbatim} Code 200 is emitted in response to requests matching a "monitor-uri" rule. +\end{verbatim} +\begin{verbatim} Note that both keyword return the HTTP 302 status code, which tells the client to fetch the designated URL using the same HTTP method. This can be quite problematic in case of non-GET methods such as POST, because the URL @@ -1066,10 +1367,13 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} workaround this problem, please use "errorloc303" which send the HTTP 303 status code, indicating to the client that the URL must be fetched with a GET request. +\end{verbatim} +\begin{verbatim} See also : "errorfile", "errorloc303" +\end{verbatim} - +\begin{verbatim} errorloc303 Return an HTTP redirection to a URL instead of errors generated by HAProxy May be used in sections : defaults | frontend | listen | backend @@ -1077,39 +1381,54 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} Arguments : is the HTTP status code. Currently, HAProxy is capable of generating codes 400, 403, 408, 500, 502, 503, and 504. +\end{verbatim} +\begin{verbatim} it is the exact contents of the "Location" header. It may contain either a relative URI to an error page hosted on the same site, or an absolute URI designating an error page on another site. Special care should be given to relative URIs to avoid redirect loops if the URI itself may generate the same error (eg: 500). +\end{verbatim} +\begin{verbatim} It is important to understand that this keyword is not meant to rewrite errors returned by the server, but errors detected and returned by HAProxy. This is why the list of supported errors is limited to a small set. +\end{verbatim} +\begin{verbatim} Code 200 is emitted in response to requests matching a "monitor-uri" rule. +\end{verbatim} +\begin{verbatim} Note that both keyword return the HTTP 303 status code, which tells the client to fetch the designated URL using the same HTTP GET method. This solves the usual problems associated with "errorloc" and the 302 code. It is possible that some very old browsers designed before HTTP/1.1 do not support it, but no such problem has been reported till now. +\end{verbatim} +\begin{verbatim} See also : "errorfile", "errorloc", "errorloc302" +\end{verbatim} - +\begin{verbatim} force-persist { if | unless } Declare a condition to force persistence on down servers May be used in sections: defaults | frontend | listen | backend no | yes | yes | yes +\end{verbatim} +\begin{verbatim} By default, requests are not dispatched to down servers. It is possible to force this using "option persist", but it is unconditional and redispatches to a valid server if "option redispatch" is set. That leaves with very little possibilities to force some requests to reach a server which is artificially marked down for maintenance operations. +\end{verbatim} +\begin{verbatim} The "force-persist" statement allows one to declare various ACL-based conditions which, when met, will cause a request to ignore the down status of a server and still try to connect to it. That makes it possible to start a @@ -1119,15 +1438,20 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} the advantage that it can easily be added/removed on the browser from a test page. Once the service is validated, it is then possible to open the service to the world by returning a valid response to health checks. +\end{verbatim} +\begin{verbatim} The forced persistence is enabled when an "if" condition is met, or unless an "unless" condition is met. The final redispatch is always disabled when this is used. +\end{verbatim} +\begin{verbatim} See also : "option redispatch", "ignore-persist", "persist", and section 7 about ACL usage. +\end{verbatim} - +\begin{verbatim} fullconn Specify at what backend load the servers will reach their maxconn May be used in sections : defaults | frontend | listen | backend @@ -1135,7 +1459,9 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} Arguments : is the number of connections on the backend which will make the servers use the maximal number of connections. +\end{verbatim} +\begin{verbatim} When a server has a "maxconn" parameter specified, it means that its number of concurrent connections will never go higher. Additionally, if it has a "minconn" parameter, it indicates a dynamic limit following the backend's @@ -1145,11 +1471,15 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} makes it possible to limit the load on the servers during normal loads, but push it further for important loads without overloading the servers during exceptional loads. +\end{verbatim} +\begin{verbatim} Since it's hard to get this value right, haproxy automatically sets it to 10% of the sum of the maxconns of all frontends that may branch to this backend. That way it's safe to leave it unset. +\end{verbatim} +\begin{verbatim} Example : # The servers will accept between 100 and 1000 concurrent connections each # and the maximum of 1000 will be reached when the backend reaches 10000 @@ -1158,10 +1488,13 @@ \section{Alphabetically sorted keywords reference}\label{keywords reference} fullconn 10000 server srv1 dyn1:80 minconn 100 maxconn 1000 server srv2 dyn2:80 minconn 100 maxconn 1000 +\end{verbatim} +\begin{verbatim} See also : "maxconn", "server" +\end{verbatim} - +\begin{verbatim} grace