3. 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 - node - description * Performance tuning - maxconn - maxpipes - noepoll - nokqueue - nopoll - nosepoll - nosplice - spread-checks - tune.bufsize - tune.chksize - tune.maxaccept - tune.maxpollevents - tune.maxrewrite - tune.rcvbuf.client - tune.rcvbuf.server - tune.sndbuf.client - tune.sndbuf.server * Debugging - debug - quiet 3.1. Process management and security ------------------------------------ chroot <jail dir> Changes current directory to <jail dir> 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 <jail_dir> 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 <number> Changes the process' group ID to <number>. 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 <group name> Similar to "gid" but uses the GID of group name <group name> from /etc/group. See also "gid" and "user". log <address> <facility> [max level [min 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". <address> can be one of: - An IPv4 address optionally followed by a colon and a UDP port. If no port is specified, 514 is used by default (the standard syslog port). - A filesystem path to a UNIX domain socket, keeping in mind considerations for chroot (be sure the path is accessible inside the chroot) and uid/gid (be sure the path is appropriately writeable). <facility> 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 maximum level is specified, only messages with a severity at least as important as this level will be sent. An optional minimum level can be specified. If it is set, logs emitted with a more severe level than this one will be capped to this level. This is used to avoid sending "emerg" messages on all terminals on some default syslog configurations. Eight levels are known : emerg alert crit err warning notice info debug nbproc <number> Creates <number> 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 <pidfile> Writes pids of all daemons into file <pidfile>. 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 <path> [{uid | user} <uid>] [{gid | group} <gid>] [mode <mode>] [level <level>] Creates a UNIX socket in stream mode at location <path>. Any previously existing socket will be backed up then replaced. Connections to this socket will return various statistics outputs and even allow some commands to be issued. Please consult section 9.2 "Unix Socket commands" for more details. An optional "level" parameter can be specified to restrict the nature of the commands that can be issued on the socket : - "user" is the least privileged level ; only non-sensitive stats can be read, and no change is allowed. It would make sense on systems where it is not easy to restrict access to the socket. - "operator" is the default level and fits most common uses. All data can be read, and only non-sensible changes are permitted (eg: clear max counters). - "admin" should be used with care, as everything is permitted (eg: clear all counters). 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 <timeout, in milliseconds> 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, or be suffixed by a time unit among { us, ms, s, m, h, d }. stats maxconn <connections> By default, the stats socket is limited to 10 concurrent connections. It is possible to change this value with "stats maxconn". uid <number> Changes the process' user ID to <number>. 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 <number> Sets the maximum number of per-process file-descriptors to <number>. By default, it is automatically computed, so it is recommended not to use this option. user <user name> Similar to "uid" but uses the UID of user name <user name> from /etc/passwd. See also "uid" and "group". node <name> Only letters, digits, hyphen and underscore are allowed, like in DNS names. This statement is useful in HA configurations where two or more processes or servers share the same IP address. By setting a different node-name on all nodes, it becomes easy to immediately spot what server is handling the traffic. description <text> Add a text that describes the instance. Please note that it is required to escape certain characters (# for example) and this text is inserted into a html page so you should avoid using "<" and ">" characters. 3.2. Performance tuning ----------------------- maxconn <number> Sets the maximum per-process number of concurrent connections to <number>. 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". maxpipes <number> Sets the maximum per-process number of pipes to <number>. Currently, pipes are only used by kernel-based tcp splicing. Since a pipe contains two file descriptors, the "ulimit-n" value will be increased accordingly. The default value is maxconn/4, which seems to be more than enough for most heavy usages. The splice code dynamically allocates and releases pipes, and can fall back to standard copy, so setting this value too low may only impact performance. 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 disable "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". nosplice Disables the use of kernel tcp splicing between sockets on Linux. It is equivalent to the command line argument "-dS". Data will then be copied using conventional and more portable recv/send calls. Kernel tcp splicing is limited to some very recent instances of kernel 2.6. Most versions between 2.6.25 and 2.6.28 are buggy and will forward corrupted data, so they must not be used. This option makes it easier to globally disable kernel splicing in case of doubt. See also "option splice-auto", "option splice-request" and "option splice-response". 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. tune.bufsize <number> Sets the buffer size to this size (in bytes). Lower values allow more sessions to coexist in the same amount of RAM, and higher values allow some applications with very large cookies to work. The default value is 16384 and can be changed at build time. It is strongly recommended not to change this from the default value, as very low values will break some services such as statistics, and values larger than default size will increase memory usage, possibly causing the system to run out of memory. At least the global maxconn parameter should be decreased by the same factor as this one is increased. tune.chksize <number> Sets the check buffer size to this size (in bytes). Higher values may help find string or regex patterns in very large pages, though doing so may imply more memory and CPU usage. The default value is 16384 and can be changed at build time. It is not recommended to change this value, but to use better checks whenever possible. tune.maxaccept <number> Sets the maximum number of consecutive accepts that a process may perform on a single wake up. High values give higher priority to high connection rates, while lower values give higher priority to already established connections. This value is limited to 100 by default in single process mode. However, in multi-process mode (nbproc > 1), it defaults to 8 so that when one process wakes up, it does not take all incoming connections for itself and leaves a part of them to other processes. Setting this value to -1 completely disables the limitation. It should normally not be needed to tweak this value. tune.maxpollevents <number> 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. tune.maxrewrite <number> Sets the reserved buffer space to this size in bytes. The reserved space is used for header rewriting or appending. The first reads on sockets will never fill more than bufsize-maxrewrite. Historically it has defaulted to half of bufsize, though that does not make much sense since there are rarely large numbers of headers to add. Setting it too high prevents processing of large requests or responses. Setting it too low prevents addition of new headers to already large requests or to POST requests. It is generally wise to set it to about 1024. It is automatically readjusted to half of bufsize if it is larger than that. This means you don't have to worry about it when changing bufsize. tune.rcvbuf.client <number> tune.rcvbuf.server <number> Forces the kernel socket receive buffer size on the client or the server side to the specified value in bytes. This value applies to all TCP/HTTP frontends and backends. It should normally never be set, and the default size (0) lets the kernel autotune this value depending on the amount of available memory. However it can sometimes help to set it to very low values (eg: 4096) in order to save kernel memory by preventing it from buffering too large amounts of received data. Lower values will significantly increase CPU usage though. tune.sndbuf.client <number> tune.sndbuf.server <number> Forces the kernel socket send buffer size on the client or the server side to the specified value in bytes. This value applies to all TCP/HTTP frontends and backends. It should normally never be set, and the default size (0) lets the kernel autotune this value depending on the amount of available memory. However it can sometimes help to set it to very low values (eg: 4096) in order to save kernel memory by preventing it from buffering too large amounts of received data. Lower values will significantly increase CPU usage though. Another use case is to prevent write timeouts with extremely slow clients due to the kernel waiting for a large part of the buffer to be read before notifying haproxy again. 3.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". 3.4. Userlists -------------- It is possible to control access to frontend/backend/listen sections or to http stats by allowing only authenticated and authorized users. To do this, it is required to create at least one userlist and to define users. userlist <listname> Creates new userlist with name <listname>. Many independent userlists can be used to store authentication &authorization data for independent customers. group <groupname> [users <user>,<user>,(...)] Adds group <groupname> to the current userlist. It is also possible to attach users to this group by using a comma separated list of names proceeded by "users" keyword. user <username> [password|insecure-password <password>] [groups <group>,<group>,(...)] Adds user <username> to the current userlist. Both secure (encrypted) and insecure (unencrypted) passwords can be used. Encrypted passwords are evaluated using the crypt(3) function so depending of the system's capabilities, different algorithms are supported. For example modern Glibc based Linux system supports MD5, SHA-256, SHA-512 and of course classic, DES-based method of crypting passwords. Example: userlist L1 group G1 users tiger,scott group G2 users xdb,scott user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91 user scott insecure-password elgato user xdb insecure-password hello userlist L2 group G1 group G2 user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1 user scott insecure-password elgato groups G1,G2 user xdb insecure-password hello groups G2 Please note that both lists are functionally identical.