3. Global parameters - 3.1. Process management and security - 《HAProxy 2.0 Configuration Manual》

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 non-writable to anyone.

cpu-map [auto:][/] …

On Linux 2.6 and above, it is possible to bind a process or a thread to a
specific CPU set. This means that the process or the thread will never run on
other CPUs. The "" directive specifies CPU sets for process or thread
sets. The first argument is a process set, eventually followed by a thread
set. These sets have the format
 
    all | odd | even | number[-[number]]
 
<number>> must be a number between 1 and 32 or 64, depending on the machine's
word size. Any process IDs above nbproc and any thread IDs above nbthread are
ignored. It is possible to specify a range with two such number delimited by
a dash ('-'). It also is possible to specify all processes at once using
"all", only odd numbers using "odd" or even numbers using "", just like
with the "bind-process" directive. The second and forthcoming arguments are
CPU sets. Each CPU set is either a unique number between 0 and 31 or 63 or a
range with two such numbers delimited by a dash ('-'). Multiple CPU numbers
or ranges may be specified, and the processes or threads will be allowed to
bind to all of them. Obviously, multiple "" directives may be
specified. Each "cpu-map" directive will replace the previous ones when they
overlap. A thread will be bound on the intersection of its mapping and the
one of the process on which it is attached. If the intersection is null, no
specific binding will be set for the thread.
 
Ranges can be partially defined. The higher bound can be omitted. In such
case, it is replaced by the corresponding maximum value, 32 or 64 depending
on the machine's word size.
 
The prefix "auto:" can be added before the process set to let HAProxy
automatically bind a process or a thread to a CPU by incrementing
process/thread and CPU sets. To be valid, both sets must have the same
size. No matter the declaration order of the CPU sets, it will be bound from
the lowest to the highest bound. Having a process and a thread range with the
"auto:" prefix is not supported. Only one range is supported, the other one
must be a fixed number.

Examples:


cpu-map 1/all 0-3 # bind all threads of the first process on the
                  # first 4 CPUs
cpu-map 1- 0-     # will be replaced by "cpu-map 1-64 0-63"
                  # or "cpu-map 1-32 0-31" depending on the machine's
                  # word size.
# all these lines bind the process 1 to the cpu 0, the process 2 to cpu 1
# and so on.
cpu-map auto:1-4   0-3
cpu-map auto:1-4   0-1 2-3
# all these lines bind the thread 1 to the cpu 0, the thread 2 to cpu 1
# and so on.
cpu-map auto:1/1-4   0-3
cpu-map auto:1/1-4   0-1 2-3
cpu-map auto:1/1-4   3 2 1 0
# bind each process to exactly one CPU using all/odd/even keyword
cpu-map auto:all   0-63
cpu-map auto:even  0-31
cpu-map auto:odd   32-63
cpu-map auto:1-4   0    # invalid
cpu-map auto:1     0-3  # invalid
# invalid cpu-map because automatic binding is used with a process range
# and a thread range.
cpu-map auto:all/all   0 # invalid
cpu-map auto:all/1-4   0 # invalid
cpu-map auto:1-4/all   0 # invalid

Assigns a default directory to fetch SSL certificates from when a relative
path is used with "crtfile" directives. Absolute locations specified after
"crtfile" prevail and ignore "crt-base".

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. This option is ignored in
systemd mode.

deviceatlas-json-file

Sets the path of the DeviceAtlas JSON data file to be loaded by the API.
The path must be a valid JSON data file and accessible by HAProxy process.

Sets the level of information returned by the API. This directive is
optional and set to 0 by default if not set.

deviceatlas-separator

Sets the character separator for the API properties results. This directive
is optional and set to | by default if not set.

Sets the client cookie's name used for the detection if the DeviceAtlas
Client-side component was used during the request. This directive is optional
and set to DAPROPS by default if not set.

external-check

Allows the use of an external agent to perform health checks.
This is disabled by default as a security precaution.
See "".

gid

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.
Note that if haproxy is started from a user having supplementary groups, it
will only be able to drop these groups if started with superuser privileges.
See also "This keyword is available in sections :
Process management and security
Bind options
" and "This keyword is available in sections :
Process management and security
".

group

Similar to "This keyword is available in sections :
Process management and security
" but uses the GID of group name <group name> from /etc/group.
See also "gidThis keyword is available in sections :
Bind options
" and "This keyword is available in sections :
Process management and security
Bind options
".

Defines the maximum time allowed to perform a clean soft-stop.

Arguments :

<time>  is the maximum time (by default in milliseconds) for which the
        instance will remain alive when a soft-stop is received via the
        SIGUSR1 signal.

This may be used to ensure that the instance will quit even if connections
remain opened during a soft-stop (for example with long timeouts for a proxy
in tcp mode). It applies both in TCP and HTTP mode.

Example:

global
  hard-stop-after 30s

h1-case-adjust

Defines the case adjustment to apply, when enabled, to the header name
<from>, to change it to <to> before sending it to HTTP/1 clients or
servers. <from> must be in lower case, and <from> and <to> must not differ
except for their case. It may be repeated if several header names need to be
adjusted. Duplicate entries are not allowed. If a lot of header names have to
be adjusted, it might be more convenient to use "".
Please note that no transformation will be applied unless "option
h1-case-adjust-bogus-client" or "option h1-case-adjust-bogus-server" is
specified in a proxy.
 
There is no standard case for header names because, as stated in RFC7230,
they are case-insensitive. So applications must handle them in a case-
insensitive manner. But some bogus applications violate the standards and
erroneously rely on the cases most commonly used by browsers. This problem
becomes critical with HTTP/2 because all header names must be exchanged in
lower case, and HAProxy follows the same convention. All header names are
sent in lower case to clients and servers, regardless of the HTTP version.
 
Applications which fail to properly process requests or responses may require
to temporarily use such workarounds to adjust header names sent to them for
the time it takes the application to be fixed. Please note that an
application which requires such workarounds might be vulnerable to content
smuggling attacks and must absolutely be fixed.

Example:

global
  h1-case-adjust content-length Content-Length

See "", "option h1-case-adjust-bogus-client" and
"".

h1-case-adjust-file

Defines a file containing a list of key/value pairs used to adjust the case
of some header names before sending them to HTTP/1 clients or servers. The
file <hdrs-file> must contain 2 header names per line. The first one must be
in lower case and both must not differ except for their case. Lines which
start with '#' are ignored, just like empty lines. Leading and trailing tabs
and spaces are stripped. Duplicate entries are not allowed. Please note that
no transformation will be applied unless ""
or "option h1-case-adjust-bogus-server" is specified in a proxy.
 
If this directive is repeated, only the last one will be processed.  It is an
alternative to the directive "" if a lot of header names need
to be adjusted. Please read the risks associated with using this.
 
See "h1-case-adjust", "" and
"option h1-case-adjust-bogus-server".

[len ] [format ] [sample :] [max level [min level]]

log-send-hostname []

Sets the hostname field in the syslog header. If optional "string" parameter
is set the header is set to the string contents, otherwise uses the hostname
of the system. Generally used if one is not relaying logs through an
intermediate syslog server or for simply customizing the hostname printed in
the logs.

Sets the tag field in the syslog header to this string. It defaults to the
program name as launched from the command line, which usually is "haproxy".
running on the same host. See also the per-proxy "log-tagThis keyword is available in sections :
Alphabetically sorted keywords reference
" directive.

This global directive loads and executes a Lua file. This directive can be
used multiple times.

master-worker [no-exit-on-failure]

Master-worker mode. It is equivalent to the command line "-W" argument.
This mode will launch a "master" which will monitor the "workers". Using
this mode, you can reload HAProxy directly by sending a SIGUSR2 signal to
the master. The master-worker mode is compatible either with the foreground
or daemon mode. It is recommended to use this mode with multiprocess and
systemd.
By default, if a worker exits with a bad return code, in the case of a
segfault for example, all workers will be killed, and the master will leave.
It is convenient to combine this behavior with Restart=on-failure in a
systemd unit file in order to relaunch the whole process. If you don't want
this behavior, you must use the keyword "no-exit-on-failure".
 
See also "-W" in the management guide.

In master-worker mode, this option limits the number of time a worker can
survive to a reload. If the worker did not leave after a reload, once its
number of reloads is greater than this number, the worker will receive a
SIGTERM. This option helps to keep under control the number of workers.
See also "show proc" in the Management Guide.

nbproc

Creates <number> processes when going daemon. This requires the ""
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. When set to a value
larger than 1, threads are automatically disabled. USING MULTIPLE PROCESSES
IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. See also "daemon" and
"".

nbthread

This setting is only available when support for threads was built in. It
makes haproxy run on <number> threads. This is exclusive with "This keyword is available in sections :
Process management and security
". While
"nbprocThis keyword is available in sections :
Fetching samples from internal states
" historically used to be the only way to use multiple processors, it
also involved a number of shortcomings related to the lack of synchronization
between processes (health-checks, peers, stick-tables, stats, ...) which do
not affect threads. As such, any modern configuration is strongly encouraged
to migrate away from "This keyword is available in sections :
Process management and security
" to "nbthread". "" also works when
HAProxy is started in foreground. On some platforms supporting CPU affinity,
when nbproc is not used, the default "nbthread" value is automatically set to
the number of CPUs the process is bound to upon startup. This means that the
thread count can easily be adjusted from the calling process using commands
like "taskset" or "cpuset". Otherwise, this value defaults to 1. The default
value is reported in the output of "haproxy -vv". See also "This keyword is available in sections :
Process management and security
".

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 "".

presetenv

Sets environment variable <name> to value <value>. If the variable exists, it
is NOT overwritten. The changes immediately take effect so that the next line
in the configuration file sees the new value. See also "", "resetenv",
and "".

resetenv [ …]

Removes all environment variables except the ones specified in argument. It
allows to use a clean controlled environment before setting new values with
setenv or unsetenv. Please note that some internal functions may make use of
some environment variables, such as time manipulation functions, but also
OpenSSL or even external checks. This must be used with extreme care and only
after complete validation. The changes immediately take effect so that the
next line in the configuration file sees the new environment. See also
"", "presetenv", and "".

stats bind-process [ all | odd | even | [-[process_num>]] ] …

Limits the stats socket to a certain set of processes numbers. By default the
stats socket is bound to all processes, causing a warning to be emitted when
nbproc is greater than 1 because there is no way to select the target process
when connecting. However, by using this setting, it becomes possible to pin
the stats socket to a specific set of processes, typically the first one. The
warning will automatically be disabled when this setting is used, whatever
the number of processes used. The maximum process ID depends on the machine's
word size (32 or 64). Ranges can be partially defined. The higher bound can
be omitted. In such case, it is replaced by the corresponding maximum
value. A better option consists in using the "" setting of the "stats
socket" line to force the process on each line.

server-state-base

Specifies the directory prefix to be prepended in front of all servers state
file names which do not start with a '/'. See also "",
"load-server-state-from-file" and "".

server-state-file

Specifies the path to the file containing state of servers. If the path starts
with a slash ('/'), it is considered absolute, otherwise it is considered
relative to the directory specified using "" (if set) or to
the current directory. Before reloading HAProxy, it is possible to save the
servers' current state using the stats command "show servers state". The
output of this command must be written in the file pointed by <file>. When
starting up, before handling traffic, HAProxy will read, load and apply state
for each server found in the file and available in its current running
configuration. See also "server-state-base" and "show servers state",
"" and "server-state-file-name"

Sets environment variable <name> to value <value>. If the variable exists, it
is overwritten. The changes immediately take effect so that the next line in
the configuration file sees the new value. See also "presetenv", "",
and "unsetenv".

This option is better left disabled by default and enabled only upon a
developer's request. It has no impact on performance nor stability but will
try hard to re-enable core dumps that were possibly disabled by file size
limitations (ulimit -f), core size limitations (ulimit -c), or "dumpability"
of a process after changing its UID/GID (such as /proc/sys/fs/suid_dumpable
on Linux). Core dumps might still be limited by the current directory's
permissions (check what directory the file is started from), the chroot
directory's permission (it may be needed to temporarily disable the chroot
directive or to move it to a dedicated writable location), or any other
system-specific constraint. For example, some Linux flavours are notorious
for replacing the default core file with a path to an executable not even
installed on the system (check /proc/sys/kernel/core_pattern). Often, simply
writing "core", "core.%p" or "/var/log/core/core.%p" addresses the issue.
When trying to enable this option waiting for a rare issue to re-appear, it's
often a good idea to first try to obtain such a dump by issuing, for example,
"kill -11" to the haproxy process and verify that it leaves a core where
expected when dying.

ssl-default-bind-ciphers

This setting is only available when support for OpenSSL was built in. It sets
the default string describing the list of cipher algorithms ("cipher suite")
that are negotiated during the SSL/TLS handshake up to TLSv1.2 for all
"This keyword is available in sections :
Peers
" lines which do not explicitly define theirs. The format of the string
is defined in "man 1 ciphers" from OpenSSL man pages. For background
information and recommendations see e.g.
(https://wiki.mozilla.org/Security/Server_Side_TLS) and
(https://mozilla.github.io/server-side-tls/ssl-config-generator/). For TLSv1.3
cipher configuration, please check the "ssl-default-bind-ciphersuites" keyword.
Please check the "This keyword is available in sections :
Peers
" keyword for more information.

ssl-default-bind-ciphersuites

This setting is only available when support for OpenSSL was built in and
OpenSSL 1.1.1 or later was used to build HAProxy. It sets the default string
describing the list of cipher algorithms ("cipher suite") that are negotiated
during the TLSv1.3 handshake for all "This keyword is available in sections :
Peers
" lines which do not explicitly define
theirs. The format of the string is defined in
"man 1 ciphers" from OpenSSL man pages under the section "ciphersuitesThis keyword is available in sections :
Server and default-server options
". For
cipher configuration for TLSv1.2 and earlier, please check the
"" keyword. Please check the "bindThis keyword is available in sections :
Alphabetically sorted keywords reference
" keyword for more
information.

[]…

This setting is only available when support for OpenSSL was built in. It sets
default ssl-options to force on all "bindThis keyword is available in sections :
Alphabetically sorted keywords reference
" lines. Please check the "This keyword is available in sections :
Peers
"
keyword to see available options.

Example:


   ssl-default-bind-options ssl-min-ver TLSv1.0 no-tls-tickets

ssl-default-server-ciphers

This setting is only available when support for OpenSSL was built in. It
sets the default string describing the list of cipher algorithms that are
negotiated during the SSL/TLS handshake up to TLSv1.2 with the server,
for all "This keyword is available in sections :
Peers
" lines which do not explicitly define theirs. The format of
the string is defined in "man 1 ciphers" from OpenSSL man pages. For background
information and recommendations see e.g.
(https://wiki.mozilla.org/Security/Server_Side_TLS) and
(https://mozilla.github.io/server-side-tls/ssl-config-generator/).
For TLSv1.3 cipher configuration, please check the
"ssl-default-server-ciphersuites" keyword. Please check the "This keyword is available in sections :
Peers
" keyword

ssl-default-server-ciphersuites

This setting is only available when support for OpenSSL was built in. It sets
default ssl-options to force on all "This keyword is available in sections :
Peers
" lines. Please check the "serverThis keyword is available in sections :
Alphabetically sorted keywords reference
"
keyword to see available options.

This setting is only available when support for OpenSSL was built in. It sets
the default DH parameters that are used during the SSL/TLS handshake when
ephemeral Diffie-Hellman (DHE) key exchange is used, for all "bindThis keyword is available in sections :
Alphabetically sorted keywords reference
" lines
which do not explicitly define theirs. It will be overridden by custom DH
parameters found in a bind certificate file if any. If custom DH parameters
are not specified either by using ssl-dh-param-file or by setting them
directly in the certificate file, pre-generated DH parameters of the size
specified by tune.ssl.default-dh-param will be used. Custom parameters are
known to be more secure and therefore their use is recommended.
Custom DH parameters may be generated by using the OpenSSL command
"openssl dhparam <size>", where size should be at least 2048, as 1024-bit DH
parameters should not be considered secure anymore.

[none|required]

The default behavior for SSL verify on servers side. If specified to 'none',
servers certificates are not verified. The default is 'required' except if
forced using cmdline option '-dV'.

stats socket [|] [param*]

Binds a UNIX socket to <path> or a TCPv4/v6 address to <address:port>.
Connections to this socket will return various statistics outputs and even
allow some commands to be issued to change some runtime settings. Please
consult  "Unix Socket commands" of Management Guide for more
details.
 
All parameters supported by "bindThis keyword is available in sections :
Alphabetically sorted keywords reference
" lines are supported, for instance to
restrict access to some users or their access rights. Please consult
 for more information.

stats timeout

The default timeout on the stats socket is set to 10 seconds. It is possible
to change this value with "". The value must be passed in
milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }.

stats maxconn

By default, the stats socket is limited to 10 concurrent connections. It is
possible to change this value with "".

uid

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 "This keyword is available in sections :
Process management and security
" and "userThis keyword is available in sections :
Userlists
".

ulimit-n

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.

[ prefix ] [ mode ] [ user ] [ uid ] [ group ] [ gid ]

Fixes common settings to UNIX listening sockets declared in "bindThis keyword is available in sections :
Alphabetically sorted keywords reference
" statements.
This is mainly used to simplify declaration of those UNIX sockets and reduce
the risk of errors, since those settings are most commonly required but are
also process-specific. The <prefix> setting can be used to force all socket
path to be relative to that directory. This might be needed to access another
component's chroot. Note that those paths are resolved before haproxy chroots
itself, so they are absolute. The <mode>, <user>, <uid>, <group> and <gid>
all have the same meaning as their homonyms used by the "This keyword is available in sections :
Peers
" statement. If
both are specified, the "bindThis keyword is available in sections :
Alphabetically sorted keywords reference
" statement has priority, meaning that the
"" settings may be seen as process-wide default settings.

unsetenv [ …]

Removes environment variables specified in arguments. This can be useful to
hide some sensitive information that are occasionally inherited from the
user's environment during some operations. Variables which did not exist are
silently ignored so that after the operation, it is certain that none of
these variables remain. The changes immediately take effect so that the next
line in the configuration file will not see these variables. See also
"", "presetenv", and "".

user

Similar to "This keyword is available in sections :
Process management and security
" but uses the UID of user name <user name> from /etc/passwd.
See also "uidThis keyword is available in sections :
Bind options
" and "This keyword is available in sections :
Process management and security
Bind options
".

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

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.

The path of the 51Degrees data file to provide device detection services. The
file should be unzipped and accessible by HAProxy with relevant permissions.
 
Please note that this option is only available when haproxy has been
compiled with USE_51DEGREES.

51degrees-property-name-list [ …]

A list of 51Degrees property names to be load from the dataset. A full list
of names is available on the 51Degrees website:
https://51degrees.com/resources/property-dictionary
 
Please note that this option is only available when haproxy has been
compiled with USE_51DEGREES.

A char that will be appended to every property value in a response header
containing 51Degrees results. If not set that will be set as ','.
 
Please note that this option is only available when haproxy has been
compiled with USE_51DEGREES.

51degrees-cache-size

Sets the size of the 51Degrees converter cache to <number> entries. This
is an LRU cache which reminds previous device detections and their results.
By default, this cache is disabled.
 
Please note that this option is only available when haproxy has been
compiled with USE_51DEGREES.

The path of the WURFL data file to provide device detection services. The
file should be accessible by HAProxy with relevant permissions.
 
Please note that this option is only available when haproxy has been compiled
with USE_WURFL=1.

wurfl-information-list []*

A space-delimited list of WURFL capabilities, virtual capabilities, property
names we plan to use in injected headers. A full list of capability and
virtual capability names is available on the Scientiamobile website :
 
    https://www.scientiamobile.com/wurflCapability
 
Valid WURFL properties are:
- wurfl_id                    Contains the device ID of the matched device.
 
- wurfl_root_id               Contains the device root ID of the matched
                              device.
 
- wurfl_isdevroot             Tells if the matched device is a root device.
                              Possible values are "TRUE" or "FALSE".
 
- wurfl_useragent             The original useragent coming with this
                              particular web request.
 
- wurfl_api_version           Contains a string representing the currently
                              used Libwurfl API version.
 
- wurfl_info                  A string containing information on the parsed
                              wurfl.xml and its full path.
 
- wurfl_last_load_time        Contains the UNIX timestamp of the last time
                              WURFL has been loaded successfully.
 
- wurfl_normalized_useragent  The normalized useragent.
 
Please note that this option is only available when haproxy has been compiled
with USE_WURFL=1.

A char that will be used to separate values in a response header containing
WURFL results. If not set that a comma (',') will be used by default.
 
Please note that this option is only available when haproxy has been compiled
with USE_WURFL=1.

wurfl-patch-file []

Sets the WURFL Useragent cache size. For faster lookups, already processed user
agents are kept in a LRU cache :
- "0"     : no cache is used.
- <size>  : size of lru cache in elements.
 
Please note that this option is only available when haproxy has been compiled
with USE_WURFL=1.