3.1. Process management and security



The following keywords can be used to improve the security. Also they can be used for the process management

ca-base <dir>
Assigns a default directory to fetch SSL CA certificates and CRLs from when a relative path is used with “ca-file” or “crl-file” directives. Absolute locations specified in “ca-file” and “crl-file” prevail and ignore “ca-base”.

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.

cpu-map <“all”|”odd”|”even”|process_num> <cpu-set>…
On Linux 2.6 and above, it is possible to bind a process to a specific CPU set. This means that the process will never run on other CPUs. The “cpu-map” directive specifies CPU sets for process sets. The first argument is the process number to bind. This process must have a number between 1 and 32 or 64, depending on the machine’s word size, and any process IDs above nbproc are ignored. It is possible to specify all processes at once using “all”, only odd numbers using “odd” or even numbers using “even”, 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 will be allowed to bind to all of them. Obviously, multiple “cpu-map” directives may be specified. Each “cpu-map” directive will replace the previous ones when they overlap.

crt-base <dir>
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”.

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. 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 “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> [len <length>] <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).
  • An IPv6 address followed by a colon and optionally 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).

Any part of the address string may reference any number of environment variables by preceding their name with a dollar sign (‘$’) and optionally enclosing them with braces (‘{}’), similarly to what is done in Bourne shell.

<length> is an optional maximum line length. Log lines larger than this value will be truncated before being sent. The reason is that syslog servers act differently on log line length. All servers support the default value of 1024, but some servers simply drop larger lines while others do log them. If a server supports long lines, it may make sense to set this value here in order to avoid truncating long lines. Similarly, if a server drops long lines, it is preferable to truncate them before sending them. Accepted values are 80 to 65535 inclusive. The default value of 1024 is generally fine for all standard usages. Some specific cases of long captures or JSON-formated logs may require larger values.

<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

log-send-hostname [<string>]
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.

log-tag <string>
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”. Sometimes it can be useful to differentiate between multiple processes running on the same host.

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 bind-process [ all | odd | even | <number 1-64>[-<number 1-64>] ] …
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). A better option consists in using the “process” setting of the “stats socket” line to force the process on each line.

ssl-default-bind-ciphers <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 for all “bind” lines which do not explicitly define theirs.
The format of the string is defined in “man 1 ciphers” from OpenSSL man pages, and can be for instance a string such as “AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH” (without quotes). Please check the “bind” keyword for more information.

ssl-default-server-ciphers <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 with the server, for all “server” lines which do not explicitly define theirs. The format of the string is
defined in “man 1 ciphers”. Please check the “server” keyword for more information.

ssl-server-verify [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 [<address:port>|<path>] [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 section 9.2 “Unix Socket commands” for more details.

All parameters supported by “bind” lines are supported, for instance to restrict access to some users or their access rights. Please consult section 5.1 for more information.

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.

unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ] [ group <group> ] [ gid <gid> ]

Fixes common settings to UNIX listening sockets declared in “bind” 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 “bind” statement.
If both are specified, the “bind” statement has priority, meaning that the “unix-bind” settings may be seen as process-wide default settings.

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.

Share Button

One thought on “3.1. Process management and security

Leave a Reply