1HAPROXY(1) General Commands Manual HAPROXY(1)
2
6 HAProxy - fast and reliable http reverse proxy and load balancer
7
10 haproxy -f <configuration file|dir> [-L <name>] [-n maxconn] [-N max‐
11 conn] [-C <dir>] [-v|-vv] [-d] [-D] [-W] [-Ws] [-q] [-V] [-c] [-p <pid‐
12 file>] [-dk] [-ds] [-de] [-dp] [-db] [-dM[<byte>]] [-m <megs>] [-x
13 <unix_socket>] [{-sf|-st} pidlist...]
14
17 HAProxy is a TCP/HTTP reverse proxy which is particularly suited for
18 high availability environments. Indeed, it can:
19 - route HTTP requests depending on statically assigned cookies ;
20 - spread the load among several servers while assuring server
21 persistence through the use of HTTP cookies ;
22 - switch to backup servers in the event a main one fails ;
23 - accept connections to special ports dedicated to service
24 monitoring ;
25 - stop accepting connections without breaking existing ones ;
26 - add/modify/delete HTTP headers both ways ;
27 - block requests matching a particular pattern ;
28 - hold clients to the right application server depending on
29 application cookies
30 - report detailed status as HTML pages to authenticated users from an
31 URI intercepted from the application.
32 It needs very little resource. Its event-driven architecture allows it
34 to easily handle thousands of simultaneous connections on hundreds of
35 instances without risking the system's stability.
36
39 -f <configuration file|dir>
40 Specify configuration file or directory path. If the argument is
41 a directory the files (and only files) it contains are added in
42 lexical order (using LC_COLLATE=C) ; only non hidden files with
43 ".cfg" extension are added.
44 -L <name>
47 Set the local instance's peer name. Peers are defined in the
48 peers configuration section and used for syncing stick tables
49 between different instances. If this option is not specified,
50 the local hostname is used as peer name. This name is exported
51 in the $HAPROXY_LOCALPEER environment variable and can be used
52 in the configuration file.
53 -n <maxconn>
56 Set the high limit for the total number of simultaneous connec‐
57 tions.
58 -N <maxconn>
61 Set the high limit for the per-listener number of simultaneous
62 connections.
63 -C <dir>
66 Change directory to <dir> before loading any files.
67 -v Display HAProxy's version.
70 -vv Display HAProxy's version and all build options.
73 -d Start in foreground with debugging mode enabled. When the proxy
76 runs in this mode, it dumps every connections, disconnections,
77 timestamps, and HTTP headers to stdout. This should NEVER be
78 used in an init script since it will prevent the system from
79 starting up.
80 -D Start in daemon mode.
83 -W Start in master-worker mode. Could be used either with fore‐
86 ground or daemon mode.
87 -Ws Start in master-worker mode with systemd notify support. It
90 tells systemd when the process is ready. This mode forces fore‐
91 ground.
92 -q Disable messages on output.
95 -V Displays messages on output even when -q or 'quiet' are speci‐
98 fied. Some information about pollers and config file are dis‐
99 played during startup.
100 -c Only checks config file and exits with code 0 if no error was
103 found, or exits with code 1 if a syntax error was found.
104 -p <pidfile>
107 Ask the process to write down each of its children's pids to
108 this file in daemon mode or ask the process to write down its
109 master's pid to this file in master-worker mode.
110 -dk Disable use of kqueue(2). kqueue(2) is available only on BSD
113 systems.
114 -dv Disable use of event ports. Event ports are available only on
117 SunOS systems derived from Solaris 10 and later (including illu‐
118 mos systems).
119 -ds Disable use of speculative epoll(7). epoll(7) is available only
122 on Linux 2.6 and some custom Linux 2.4 systems.
123 -de Disable use of epoll(7). epoll(7) is available only on Linux 2.6
126 and some custom Linux 2.4 systems.
127 -dp Disables use of poll(2). select(2) might be used instead.
130 -dS Disables use of splice(2), which is broken on older kernels.
133 -db Disables background mode (stays in foreground, useful for debug‐
136 ging). For debugging, the '-db' option is very useful as it
137 temporarily disables daemon mode and multi-process mode. The
138 service can then be stopped by simply pressing Ctrl-C, without
139 having to edit the config nor run full debug.
140 -dM[<byte>]
143 Initializes all allocated memory areas with the given <byte>.
144 This makes it easier to detect bugs resulting from uninitialized
145 memory accesses, at the expense of touching all allocated memory
146 once. If <byte> is not specified, it defaults to 0x50 (ASCII
147 'P').
148 -m <megs>
151 Enforce a memory usage limit to a maximum of <megs> megabytes.
152 -sf <pidlist>
155 Send FINISH signal to the pids in pidlist after startup. The
156 processes which receive this signal will wait for all sessions
157 to finish before exiting. This option must be specified last,
158 followed by any number of PIDs. Technically speaking, SIGTTOU
159 and SIGUSR1 are sent.
160 -st <pidlist>
163 Send TERMINATE signal to the pids in pidlist after startup. The
164 processes which receive this signal will terminate immediately,
165 closing all active sessions. This option must be specified last,
166 followed by any number of PIDs. Technically speaking, SIGTTOU
167 and SIGTERM are sent.
168 -x <unix_socket>
171 Attempt to connect to the unix socket, and retrieve all the lis‐
172 tening sockets from the old process. Those sockets will then be
173 used if possible instead of binding new ones.
174 -S <bind>[,<bind options>...]
177 In master-worker mode, create a master CLI. This CLI will enable
178 access to the CLI of every worker. Useful for debugging, it's a
179 convenient way of accessing a leaving process.
180
183 Since HAProxy can run inside a chroot, it cannot reliably access
184 /dev/log. For this reason, it uses the UDP protocol to send its logs
185 to the server, even if it is the local server. People who experience
186 trouble receiving logs should ensure that their syslog daemon listens
187 to the UDP socket. Several Linux distributions which ship with syslogd
188 from the sysklogd package have UDP disabled by default. The -r option
189 must be passed to the daemon in order to enable UDP.
190
193 Some signals have a special meaning for the haproxy daemon. Generally,
194 they are used between daemons and need not be used by the administra‐
195 tor.
196 - SIGUSR1
198 Tells the daemon to stop all proxies and exit once all sessions
199 are closed. It is often referred to as the "soft-stop" signal.
200 - SIGUSR2
202 In master-worker mode, reloads the configuration and sends a
203 soft-stop signal to old processes.
204 - SIGTTOU
206 Tells the daemon to stop listening to all sockets. Used inter‐
207 nally by -sf and -st.
208 - SIGTTIN
210 Tells the daemon to restart listening to all sockets after a
211 SIGTTOU. Used internally when there was a problem during hot re‐
212 configuration.
213 - SIGINT and SIGTERM
215 Both signals can be used to quickly stop the daemon.
216 - SIGHUP
218 Dumps the status of all proxies and servers into the logs.
219 Mostly used for trouble-shooting purposes.
220 - SIGQUIT
222 Dumps information about memory pools on stderr. Mostly used for
223 debugging purposes.
224 - SIGPIPE
226 This signal is intercepted and ignored on systems without
227 MSG_NOSIGNAL.
228
231 A much better documentation can be found in configuration.txt. On De‐
232 bian systems, you can find this file in /usr/share/doc/haproxy/configu‐
233 ration.txt.gz.
234
237 HAProxy was written by Willy Tarreau. This man page was written by Ar‐
238 naud Cornet and Willy Tarreau.
239 17 August 2007 HAPROXY(1)