You start HAProxy by invoking the "hapee-lb" program (located in /opt/hapee-1.7/sbin/) with a number of arguments passed on the command line. The syntax is:

$ hapee-lb [<options>]*

where [<options>]* are any number of options.

  • An option always starts with - followed by one of more letters, and possibly followed by one or multiple extra arguments.

  • Without any option, HAProxy displays the help page with a reminder about supported options.

  • Available options may vary slightly based on the operating system. See available options below.

Start HAProxy in safe mode

A safe way to start HAProxy from an init file consists in forcing the daemon mode, storing existing pids to a pid file and using this pid file to notify older processes to finish before leaving:

hapee-lb -f /etc/haproxy.cfg
    -D -p /var/run/haproxy.pid -sf $(cat /var/run/haproxy.pid)

Start HAProxy with split configuration files

If you configuration is split into several specific files (eg: tcp vs http), we recommend that you use the -f option:

hapee-lb -f /etc/haproxy/global.cfg -f /etc/haproxy/stats.cfg
    -f /etc/haproxy/default-tcp.cfg -f /etc/haproxy/tcp.cfg  -f
            /etc/haproxy/default-http.cfg
    -f /etc/haproxy/http.cfg
    -D -p /var/run/haproxy.pid -sf $(cat /var/run/haproxy.pid)

When the number of files is unknown, such as customer-specific files, we recommended that you assign them a name starting with a fixed-size sequence number and to use - to load them.

hapee-lb -f /etc/haproxy/global.cfg -f /etc/haproxy/stats.cfg
    -f /etc/haproxy/default-tcp.cfg -f /etc/haproxy/tcp.cfg
    -f /etc/haproxy/default-http.cfg -f /etc/haproxy/http.cfg
    -D -p /var/run/haproxy.pid -sf $(cat /var/run/haproxy.pid)
    -f /etc/haproxy/default-customers.cfg -- /etc/haproxy/customers/*

Enable master-worker model

In the master-worker model, HAProxy launches one master process and starts a number of additional worker processes under it.

The new master process monitors all worker processes and controls them from a single instance and relieves systemd or other software from these tasks.

To enable the master/worker model, you can use one of the following approaches:

  • Use the new directive in the global configuration section named master-worker

  • Start the haproxy process with the command line argument -W

Example configuration

In this example, HAProxy is running with an nbproc of 2, both running under the same master process:

/opt/hapee-1.7/sbin/hapee-lb -Ws -f /etc/hapee-1.7/hapee-lb.cfg -p /run/hapee-1.7-lb.pid -sf 4928 -x /var/run/hapee-1.7/hapee-lb.sock
_ /opt/hapee-1.7/sbin/hapee-lb -Ws -f /etc/hapee-1.7/hapee-lb.cfg -p /run/hapee-1.7-lb.pid -sf 4928 -x /var/run/hapee-1.7/hapee-lb.sock
_ /opt/hapee-1.7/sbin/hapee-lb -Ws -f /etc/hapee-1.7/hapee-lb.cfg -p /run/hapee-1.7-lb.pid -sf 4928 -x /var/run/hapee-1.7/hapee-lb.sock

For instance, if expose-fd listeners is present on a stats socket line in the configuration when the master gets a USR2 signal (i.e. when systemd is told to reload), HAProxy automatically adds a -x argument with the socket path which forces the file descriptors of the listing sockets to be handed off without losing a single connection.

Post bug reports

Sometimes a failure to start can happen for unknown reasons. Check that the version of HAProxy you are invoking is the expected version, and if it supports the features you are expecting (such as SSL, PCRE, compression, Lua, etc).

You can verify this by using haproxy -vv to retrieve important information such as build options, the target system, and the versions of the libraries used. HAProxy Support will systematically ask for this information when you post a bug report:

hapee-lb -vv HA-Proxy version 1.6-dev7-a088d3-4 2015/10/08
    Copyright 2000-2015 Willy Tarreau <willy@haproxy.org>

High level information

The relevant information that many non-developer users can verify here are:

Build options:
    TARGET  = linux2628
    CPU     = generic
    CC      = gcc
    CFLAGS  = -pg -O0 -g -fno-strict-aliasing -Wdeclaration-after-statement  -DBUFSIZE=8030 -DMAXREWRITE=1030 -DSO_MARK=36 -DTCP_REPAIR=19
    OPTIONS         = USE_ZLIB=1 USE_DLMALLOC=1 USE_OPENSSL=1 USE_LUA=1 USE_PCRE=1
Default settings :
    maxconn = 2000, bufsize = 8030, maxrewrite = 1030, maxpollevents = 200
Encrypted password support via crypt(3): yes
Built with zlib version : 1.2.6
Compression algorithms supported : identity("identity"), deflate("deflate"),
raw-deflate("deflate"), gzip("gzip")
Built with OpenSSL version : OpenSSL 1.0.1o 12 Jun 2015
Running on OpenSSL verson : OpenSSL 1.0.1o 12 Jun 2015
OpenSSL library supports TLS extensions : yes
OpenSSL library supports SNI : yes
OpenSSL library supports prefer-server-ciphers : yes
Built with PCRE version : 8.12 2011-01-15
PCRE library supports JIT : no (USE_PCRE_JIT not set)
Built with Lua version : Lua 5.3.1
Built with transparent proxy support using: IP_TRANSPARENT IP_FREEBIND
Available polling systems :
    epoll   : pref=300,  test result OK
    poll    : pref=200,  test result OK
    select  : pref=150,  test result OK
Total: 3 (3 usable), will use epoll.

version

1.6-dev7-a088d3-4 above means the code is currently at commit ID a088d3 which is the 4th one after after official version 1.6-dev7. This is a production-ready version.

release date

2015/10/08, represented in the universal year/month/day format (August 8th, 2015). If you see an old date here, it means there are a number of bugs or security issues that have since been fixed. Check the official site.

build options

For users who build their own packages to show unexplained behavior. In the example below, the development version above was built for Linux 2.6.28 or later, targeting a generic CPU (no CPU-specific optimizations), and lacks any code optimization (-O0) so it will perform poorly in terms of performance.

libraries versions

zlib version is reported as found in the library itself. This library must be kept up to date.

Available polling systems

can affect the process's scalability when dealing with more than about one thousand of concurrent connections.

Available options

A number of these options overlap with an equivalent one if the global section. In this case, the command line always has precedence over the configuration file, so you can use the command line to enforce quickly some settings without touching the configuration files.

The current list of options is:

Option

Description

-- <cfgfile>*

All the arguments following - are paths to configuration file/directory to be loaded and processed in the declaration order. It is mostly useful when relying on the shell to load many files that are numerically ordered.

See also -f.

The difference between - and -f is that one -f must be placed before each file name, while a single - is needed before all file names.

Both options can be used together, the command line ordering still applies. When more than one file is specified, each file must start on a section boundary, so the first keyword of each file must be one of global, defaults, peers, listen, frontend, backend, and so on.

A file cannot contain just a server list for example.

-f <cfgfile|cfgdir>

Adds <cfgfile> to the list of configuration files to be loaded. If <cfgdir> is a directory, all the files (and only files) it contains are added in lexical order (using LC_COLLATE=C) to the list of configuration files to be loaded ; only files with .cfg extension are added, only non hidden files (not prefixed with .) are added. Configuration files are loaded and processed in their declaration order. This option may be specified multiple times to load multiple files.

See also -.

The difference between - and -f is that one -f must be placed before each file name, while a single - is needed before all file names. Both options can be used together, the command line ordering still applies.

When more than one file is specified, each file must start on a section boundary, so the first keyword of each file must be one of global, defaults, peers, listen, frontend, backend, and so on.

A file cannot contain just a server list for example.

-C <dir>

Changes to directory <dir> before loading configuration files. This is useful when using relative paths.

Warning

Warning when using wildcards after - which are in fact replaced by the shell before starting haproxy.

-D

Start as a daemon. The process detaches from the current terminal after forking, and errors are not reported anymore in the terminal. It is equivalent to the daemon keyword in the global section of the configuration. It is recommended to always force it in any init script so that a faulty configuration doesn't prevent the system from booting.

-Ds

Work in systemd mode. Only used by the systemd wrapper.

-L <name>

Change the local peer name to <name>, which defaults to the local hostname. This is used only with peers replication.

-N <limit>

Sets the default per-proxy maxconn to <limit> instead of the builtin default value (usually 2000). Only useful for debugging.

-V

Enable verbose mode (disables quiet mode). Reverts the effect of -q or quiet.

-W

Master-worker mode. It is equivalent to the master-worker keyword in the global section of the configuration. 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.

-Ws

Master-worker mode with systemd to notify support.

-c

Only performs a check of the configuration files and exits before trying to bind. The exit status is zero if everything is OK, or non-zero if an error is encountered.

-d

Enable debug mode. This disables daemon mode, forces the process to stay in foreground and to show incoming and outgoing events. It is equivalent to the global section's debug keyword. It must never be used in an init script.

-dG

Disable use of getaddrinfo() to resolve host names into addresses. It can be used when suspecting that getaddrinfo() doesn't work as expected. This option was made available because many bogus implementations of getaddrinfo() exist on various systems and cause anomalies that are difficult to troubleshoot.

-dM[<byte>]

Forces memory poisoning, which means that each and every memory region allocated with malloc() or pool_alloc2() will be filled with <byte> before being passed to the caller. When <byte> is not specified, it defaults to 0x50 (P).

While this slightly slows down operations, it is useful to reliably trigger issues resulting from missing initializations in the code that cause random crashes. Note that -dM0 has the effect of turning any malloc() into a calloc(). In any case if a bug appears or disappears when using this option it means there is a bug in haproxy, so please report it.

-dS

Disable use of the splice() system call. It is equivalent to the global section's nosplice keyword. This may be used when splice() is suspected to behave improperly or to cause performance issues, or when using strace to see the forwarded data (which do not appear when using splice()).

-dV

Disable SSL verify on the server side. It is equivalent to having ssl-server-verify none in the global section. This is useful when trying to reproduce production issues out of the production environment. Never use this in an init script as it degrades SSL security to the servers.

-db

Disable background mode and multi-process mode. The process remains in foreground. It is mainly used during development or during small tests, as Ctrl-C is enough to stop the process. Never use it in an init script.

-de

Disable the use of the epoll poller. It is equivalent to the global section's keyword noepoll. It is mostly useful when suspecting a bug related to this poller. On systems supporting epoll, the fallback will generally be the poll poller.

-dk

Disable the use of the kqueue poller. It is equivalent to the global section's keyword nokqueue. It is mostly useful when suspecting a bug related to this poller. On systems supporting kqueue, the fallback will generally be the poll poller.

-dp

Disable the use of the poll poller. It is equivalent to the global section's keyword nopoll. It is mostly useful when suspecting a bug related to this poller. On systems supporting poll, the fallback will generally be the select poller, which cannot be disabled and is limited to 1024 file descriptors.

-dr

Ignore server address resolution failures. It is very common when validating a configuration out of production not to have access to the same resolvers and to fail on server address resolution, making it difficult to test a configuration. This option simply appends the none method to the list of address resolution methods for all servers, ensuring that even if the libc fails to resolve an address, the startup sequence is not interrupted.

-m <limit>

Limit the total allocatable memory to <limit> megabytes across all processes. This may cause some connection refusals or some slowdowns depending on the amount of memory needed for normal operations. This is mostly used to force the processes to work in a constrained resource usage scenario. It is important to note that the memory is not shared between processes, so in a multi-process scenario, this value is first divided by global.nbproc before forking.

-n <limit>

Limits the per-process connection limit to <limit>. This is equivalent to the global section's keyword maxconn. It has precedence over this keyword. This may be used to quickly force lower limits to avoid a service outage on systems where resource limits are too low.

-p <file>

Write all processe's pids into <file> during startup. This is equivalent to the global section's keyword pidfile. The file is opened before entering the chroot jail, and after doing the chdir() implied by -C. Each pid appears on its own line.

-q

Set quiet mode. This disables some messages during the configuration parsing and during startup. It can be used in combination with -c to just check if a configuration file is valid or not.

-sf <pid>*

Send the finish signal (SIGUSR1) to older processes after boot completion to ask them to finish what they are doing and to leave. <pid> is a list of pids to signal (one per argument). The list ends on any option starting with a -. It is not a problem if the list of pids is empty, so that it can be built on the fly based on the result of a command like pidof or pgrep.

-st <pid>*

Send the terminate signal (SIGTERM) to older processes after boot completion to terminate them immediately without finishing what they were doing. <pid> is a list of pids to signal (one per argument). The list is ends on any option starting with a -. It is not a problem if the list of pids is empty, so that it can be built on the fly based on the result of a command llike pidof or pgrep.

-v

Report the version and build date.

-vv

Display the version, build options, libraries versions and usable pollers. This output is systematically requested when filing a bug report.

-x

Get the listening sockets from a Unix socket