blob: 0a1b2f5ef533798993eed11ed1311a6ccdb21708 [file] [log] [blame]
Willy Tarreau031a26b2007-09-09 22:40:07 +02001.TH HAPROXY 1 "17 August 2007"
2
3.SH NAME
4
5HAProxy \- fast and reliable http reverse proxy and load balancer
6
7.SH SYNOPSIS
8
Maxime de Roucy379d9c72016-05-13 23:52:56 +02009haproxy \-f <configuration\ file|dir> [\-L\ <name>] [\-n\ maxconn] [\-N\ maxconn] [\-C\ <dir>] [\-v|\-vv] [\-d] [\-D] [\-q] [\-V] [\-c] [\-p\ <pidfile>] [\-dk] [\-ds] [\-de] [\-dp] [\-db] [\-dM[<byte>]] [\-m\ <megs>] [{\-sf|\-st}\ pidlist...]
Willy Tarreau031a26b2007-09-09 22:40:07 +020010
11.SH DESCRIPTION
12
13HAProxy is a TCP/HTTP reverse proxy which is particularly suited for
14high availability environments. Indeed, it can:
15 \- route HTTP requests depending on statically assigned cookies ;
16 \- spread the load among several servers while assuring server
17 persistence through the use of HTTP cookies ;
18 \- switch to backup servers in the event a main one fails ;
19 \- accept connections to special ports dedicated to service
20 monitoring ;
21 \- stop accepting connections without breaking existing ones ;
22 \- add/modify/delete HTTP headers both ways ;
23 \- block requests matching a particular pattern ;
24 \- hold clients to the right application server depending on
25 application cookies
26 \- report detailed status as HTML pages to authenticated users from an
27 URI intercepted from the application.
28
29It needs very little resource. Its event-driven architecture allows it
30to easily handle thousands of simultaneous connections on hundreds of
31instances without risking the system's stability.
32
33.SH OPTIONS
34
35.TP
Maxime de Roucy379d9c72016-05-13 23:52:56 +020036\fB\-f <configuration file|dir>\fP
37Specify configuration file or directory path. If the argument is a directory
Tim Düsterhus4896c442016-11-29 02:15:19 +010038the files (and only files) it contains are added in lexical order (using
Maxime de Roucye3841392016-05-18 23:13:38 +020039LC_COLLATE=C) ; only non hidden files with ".cfg" extension are added.
Willy Tarreau031a26b2007-09-09 22:40:07 +020040
41.TP
Apollon Oikonomopoulos6712bb72013-09-29 23:03:37 +030042\fB\-L <name>\fP
43Set the local instance's peer name. Peers are defined in the \fBpeers\fP
44configuration section and used for syncing stick tables between different
45instances. If this option is not specified, the local hostname is used as peer
46name.
47
48.TP
Michael Shuler35928e82009-10-14 10:23:03 -050049\fB\-n <maxconn>\fP
Willy Tarreau031a26b2007-09-09 22:40:07 +020050Set the high limit for the total number of simultaneous connections.
51
52.TP
Michael Shuler35928e82009-10-14 10:23:03 -050053\fB\-N <maxconn>\fP
Willy Tarreau031a26b2007-09-09 22:40:07 +020054Set the high limit for the per-listener number of simultaneous connections.
55
56.TP
Apollon Oikonomopoulos6712bb72013-09-29 23:03:37 +030057\fB\-C <dir>\fP
58Change directory to <\fIdir\fP> before loading any files.
59
60.TP
61\fB\-v\fP
62Display HAProxy's version.
63
64.TP
65\fB\-vv\fP
66Display HAProxy's version and all build options.
67
68.TP
Michael Shuler35928e82009-10-14 10:23:03 -050069\fB\-d\fP
Jarno Huuskonen0e82b922014-04-12 18:22:19 +030070Start in foreground with debugging mode enabled.
Willy Tarreau031a26b2007-09-09 22:40:07 +020071When the proxy runs in this mode, it dumps every connections,
72disconnections, timestamps, and HTTP headers to stdout. This should
73NEVER be used in an init script since it will prevent the system from
74starting up.
75
76.TP
Michael Shuler35928e82009-10-14 10:23:03 -050077\fB\-D\fP
Willy Tarreau031a26b2007-09-09 22:40:07 +020078Start in daemon mode.
79
80.TP
Marc-Antoine Perennou992709b2013-02-12 10:53:52 +010081\fB\-Ds\fP
82Start in systemd daemon mode, keeping a process in foreground.
83
84.TP
Michael Shuler35928e82009-10-14 10:23:03 -050085\fB\-q\fP
Willy Tarreau031a26b2007-09-09 22:40:07 +020086Disable messages on output.
87
88.TP
Michael Shuler35928e82009-10-14 10:23:03 -050089\fB\-V\fP
90Displays messages on output even when \-q or 'quiet' are specified. Some
Willy Tarreau031a26b2007-09-09 22:40:07 +020091information about pollers and config file are displayed during startup.
92
93.TP
Michael Shuler35928e82009-10-14 10:23:03 -050094\fB\-c\fP
Willy Tarreau031a26b2007-09-09 22:40:07 +020095Only checks config file and exits with code 0 if no error was found, or
96exits with code 1 if a syntax error was found.
97
98.TP
Michael Shuler35928e82009-10-14 10:23:03 -050099\fB\-p <pidfile>\fP
Willy Tarreau031a26b2007-09-09 22:40:07 +0200100Ask the process to write down each of its children's pids to this file
101in daemon mode.
102
103.TP
Michael Shuler35928e82009-10-14 10:23:03 -0500104\fB\-dk\fP
Apollon Oikonomopoulos7ef0edf2013-09-29 23:03:51 +0300105Disable use of \fBkqueue\fP(2). \fBkqueue\fP(2) is available only on BSD systems.
Willy Tarreau031a26b2007-09-09 22:40:07 +0200106
107.TP
Michael Shuler35928e82009-10-14 10:23:03 -0500108\fB\-ds\fP
Apollon Oikonomopoulos7ef0edf2013-09-29 23:03:51 +0300109Disable use of speculative \fBepoll\fP(7). \fBepoll\fP(7) is available only on
110Linux 2.6 and some custom Linux 2.4 systems.
Willy Tarreau031a26b2007-09-09 22:40:07 +0200111
112.TP
Michael Shuler35928e82009-10-14 10:23:03 -0500113\fB\-de\fP
Apollon Oikonomopoulos7ef0edf2013-09-29 23:03:51 +0300114Disable use of \fBepoll\fP(7). \fBepoll\fP(7) is available only on Linux 2.6
Willy Tarreau031a26b2007-09-09 22:40:07 +0200115and some custom Linux 2.4 systems.
116
117.TP
Michael Shuler35928e82009-10-14 10:23:03 -0500118\fB\-dp\fP
Apollon Oikonomopoulos7ef0edf2013-09-29 23:03:51 +0300119Disables use of \fBpoll\fP(2). \fBselect\fP(2) might be used instead.
Willy Tarreau031a26b2007-09-09 22:40:07 +0200120
121.TP
Apollon Oikonomopoulos6712bb72013-09-29 23:03:37 +0300122\fB\-dS\fP
Apollon Oikonomopoulos7ef0edf2013-09-29 23:03:51 +0300123Disables use of \fBsplice\fP(2), which is broken on older kernels.
Apollon Oikonomopoulos6712bb72013-09-29 23:03:37 +0300124
125.TP
Michael Shuler35928e82009-10-14 10:23:03 -0500126\fB\-db\fP
Willy Tarreau031a26b2007-09-09 22:40:07 +0200127Disables background mode (stays in foreground, useful for debugging).
Michael Shuler35928e82009-10-14 10:23:03 -0500128For debugging, the '\-db' option is very useful as it temporarily
Willy Tarreau031a26b2007-09-09 22:40:07 +0200129disables daemon mode and multi-process mode. The service can then be
130stopped by simply pressing Ctrl-C, without having to edit the config nor
131run full debug.
132
133.TP
Apollon Oikonomopoulos6712bb72013-09-29 23:03:37 +0300134\fB\-dM[<byte>]\fP
135Initializes all allocated memory areas with the given <\fIbyte\fP>. This makes
136it easier to detect bugs resulting from uninitialized memory accesses, at the
137expense of touching all allocated memory once. If <\fIbyte\fP> is not
138specified, it defaults to 0x50 (ASCII 'P').
139
140.TP
Michael Shuler35928e82009-10-14 10:23:03 -0500141\fB\-m <megs>\fP
Willy Tarreau031a26b2007-09-09 22:40:07 +0200142Enforce a memory usage limit to a maximum of <megs> megabytes.
143
144.TP
Michael Shuler35928e82009-10-14 10:23:03 -0500145\fB\-sf <pidlist>\fP
Willy Tarreau031a26b2007-09-09 22:40:07 +0200146Send FINISH signal to the pids in pidlist after startup. The processes
147which receive this signal will wait for all sessions to finish before
148exiting. This option must be specified last, followed by any number of
149PIDs. Technically speaking, \fBSIGTTOU\fP and \fBSIGUSR1\fP are sent.
150
151.TP
Michael Shuler35928e82009-10-14 10:23:03 -0500152\fB\-st <pidlist>\fP
Willy Tarreau031a26b2007-09-09 22:40:07 +0200153Send TERMINATE signal to the pids in pidlist after startup. The processes
Jorrit Schippers1458fdb2016-04-09 20:30:38 +0200154which receive this signal will terminate immediately, closing all active
155sessions. This option must be specified last, followed by any number of
156PIDs. Technically speaking, \fBSIGTTOU\fP and \fBSIGTERM\fP are sent.
Willy Tarreau031a26b2007-09-09 22:40:07 +0200157
158.SH LOGGING
159Since HAProxy can run inside a chroot, it cannot reliably access /dev/log.
160For this reason, it uses the UDP protocol to send its logs to the server,
161even if it is the local server. People who experience trouble receiving
162logs should ensure that their syslog daemon listens to the UDP socket.
163Several Linux distributions which ship with syslogd from the sysklogd
Michael Shuler35928e82009-10-14 10:23:03 -0500164package have UDP disabled by default. The \fB\-r\fP option must be passed
Willy Tarreau031a26b2007-09-09 22:40:07 +0200165to the daemon in order to enable UDP.
166
167.SH SIGNALS
168Some signals have a special meaning for the haproxy daemon. Generally, they are used between daemons and need not be used by the administrator.
169.TP
Michael Shuler35928e82009-10-14 10:23:03 -0500170\- \fBSIGUSR1\fP
Willy Tarreau031a26b2007-09-09 22:40:07 +0200171Tells the daemon to stop all proxies and exit once all sessions are closed. It is often referred to as the "soft-stop" signal.
172.TP
Michael Shuler35928e82009-10-14 10:23:03 -0500173\- \fBSIGTTOU\fP
174Tells the daemon to stop listening to all sockets. Used internally by \fB\-sf\fP and \fB\-st\fP.
Willy Tarreau031a26b2007-09-09 22:40:07 +0200175.TP
Michael Shuler35928e82009-10-14 10:23:03 -0500176\- \fBSIGTTIN\fP
Willy Tarreau031a26b2007-09-09 22:40:07 +0200177Tells the daemon to restart listening to all sockets after a \fBSIGTTOU\fP. Used internally when there was a problem during hot reconfiguration.
178.TP
Michael Shuler35928e82009-10-14 10:23:03 -0500179\- \fBSIGINT\fP and \fBSIGTERM\fP
Willy Tarreau031a26b2007-09-09 22:40:07 +0200180Both signals can be used to quickly stop the daemon.
181.TP
Michael Shuler35928e82009-10-14 10:23:03 -0500182\- \fBSIGHUP\fP
Willy Tarreau031a26b2007-09-09 22:40:07 +0200183Dumps the status of all proxies and servers into the logs. Mostly used for trouble-shooting purposes.
184.TP
Michael Shuler35928e82009-10-14 10:23:03 -0500185\- \fBSIGQUIT\fP
Willy Tarreaud153b3b2014-01-25 18:19:32 +0100186Dumps information about memory pools on stderr. Mostly used for debugging purposes.
Willy Tarreau031a26b2007-09-09 22:40:07 +0200187.TP
Michael Shuler35928e82009-10-14 10:23:03 -0500188\- \fBSIGPIPE\fP
Willy Tarreau031a26b2007-09-09 22:40:07 +0200189This signal is intercepted and ignored on systems without \fBMSG_NOSIGNAL\fP.
190
191.SH SEE ALSO
192
Apollon Oikonomopoulos2e979572013-09-29 23:04:13 +0300193A much better documentation can be found in configuration.txt. On Debian
194systems, you can find this file in /usr/share/doc/haproxy/configuration.txt.gz.
Willy Tarreau031a26b2007-09-09 22:40:07 +0200195
196.SH AUTHOR
197
198HAProxy was written by Willy Tarreau. This man page was written by Arnaud Cornet and Willy Tarreau.
199