Note: I have not updated the French documentation
---
doc/configuration.txt | 48 ++++++++++++++++++++++++++++++++++++++++++------
doc/haproxy-en.txt | 47 ++++++++++++++++++++++++++++++++++-------------
doc/haproxy.1 | 20 ++++++++++++++++++--
3 files changed, 94 insertions(+), 21 deletions(-)
diff --git a/doc/configuration.txt b/doc/configuration.txt
index 7a5ace2..f9c9bd8 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -432,6 +432,7 @@ The following keywords are supported in the "global"
section :
* Process management and security
- chroot
- daemon
+ - master_worker
- gid
- group
- log
@@ -486,10 +487,25 @@ daemon
operation. It is equivalent to the command line "-D" argument. It can be
disabled by the command line "-db" argument.
+master_worker
+ Split haproxy into two types of processes. A master process which
+ binds to sockets and worker sockets which run proxies. When running
+ in this mode haproxy will restart rather than exiting when
+ haproxy -st is used. On restart configuration files will be reread.
+
+ On linux the master process will run with CAP_NET_BIND_SERVCE and
+ CAP_SYS_RESOURCE so that even if is running as non-root it will be able
+ to bind to privilaged ports and update ulimits.
+
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.
+
+ If running in master_worker mode changes to the gid are ignored if
+ haproxy is already runing as non-root, either because it was started as
+ non-root or it switched to another user when originally started.
+
See also "group" and "uid".
group <group name>
@@ -542,17 +558,21 @@ log-tag <string>
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".
+ Creates <number> processes when going daemon. This requires "daemon" or
+ "master_worker" 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".
+ If both "daemon" and "master_worker" mode is set then the pid
+ of the master process will be the first entry in <pid file>.
+
stats socket <path> [{uid | user} <uid>] [{gid | group} <gid>] [mode <mode>]
[level <level>]
@@ -595,7 +615,13 @@ 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".
+ one.
+
+ If running in master_worker mode changes to the uid are ignored if
+ haproxy is already runing as non-root, either because it was started as
+ non-root or it switched to another user when originally started.
+
+ See also "gid" and "user".
ulimit-n <number>
Sets the maximum number of per-process file-descriptors to <number>. By
@@ -616,10 +642,17 @@ unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user
<user> ] [ uid <uid> ]
both are specified, the "bind" statement has priority, meaning that the
"unix-bind" settings may be seen as process-wide default settings.
+ If running in master_worker mode and in a chroot any failure to resolve
+ the user or group on restart will be ignored and the previous settings
+ will prevail.
+
user <user name>
Similar to "uid" but uses the UID of user name <user name> from /etc/passwd.
See also "uid" and "group".
+ If running in master_worker mode and in a chroot any failure to resolve
+ the user will be ignored and the previous settings will prevail.
+
node <name>
Only letters, digits, hyphen and underscore are allowed, like in DNS names.
@@ -791,6 +824,9 @@ group <groupname> [users <user>,<user>,(...)]
attach users to this group by using a comma separated list of names
proceeded by "users" keyword.
+ If running in master_worker mode and in a chroot any failure to resolve
+ the group will be ignored and the previous settings will prevail.
+
user <username> [password|insecure-password <password>]
[groups <group>,<group>,(...)]
Adds user <username> to the current userlist. Both secure (encrypted) and
diff --git a/doc/haproxy-en.txt b/doc/haproxy-en.txt
index 32f52be..e0be221 100644
--- a/doc/haproxy-en.txt
+++ b/doc/haproxy-en.txt
@@ -67,6 +67,7 @@ There are only a few command line options :
-dp disables use of poll()
-db disables background mode (stays in foreground, useful for debugging)
-m <megs> enforces a memory usage limit to a maximum of <megs> megabytes.
+ -M master/worker mode
The maximal number of connections per proxy instance is used as the default
parameter for each instance for which the 'maxconn' paramter is not set in the
@@ -128,6 +129,7 @@ the following ones :
- chroot <directory>
- nbproc <number>
- daemon
+ - master_worker
- debug
- nokqueue
- nosepoll
@@ -266,13 +268,22 @@ Example :
The service can start in several different modes :
- foreground / background
- quiet / normal / debug
+ - master_worker / non-master_worker
-The default mode is normal, foreground, which means that the program doesn't
-return once started. NEVER EVER use this mode in a system startup script, or
-the system won't boot. It needs to be started in background, so that it
-returns immediately after forking. That's accomplished by the 'daemon' option
-in the 'global' section, which is the equivalent of the '-D' command line
-argument.
+The default mode is normal, foreground, non-master_worker, which means that
+the program doesn't return once started. NEVER EVER use this mode in a
+system startup script, or the system won't boot. It needs to be started in
+background, so that it returns immediately after forking. That's
+accomplished by the 'daemon' option in the 'global' section, which is the
+equivalent of the '-D' command line argument.
+
+master_worker mode splits haproxy into two types of processes. A master
+process which binds to sockets and worker sockets which run proxies. When
+running in this mode haproxy a master process will restart on receipt of a
+SIGUSR2. On restart configuration files will be reread, existing workers
+killed and new workers started.
+
+master_worker may be compined with daemon.
The '-db' command line argument overrides the 'daemon' and 'nbproc' global
options to make the process run in normal, foreground mode.
@@ -295,9 +306,10 @@ eventhough the load needed to saturate a recent processor
is far above common
usage. Anyway, for very specific needs, the proxy can start several processes
between which the operating system will spread the incoming connections. The
number of processes is controlled by the 'nbproc' parameter in the 'global'
-section. It defaults to 1, and obviously works only in 'daemon' mode. One
-typical usage of this parameter has been to workaround the default per-process
-file-descriptor limit that Solaris imposes to user processes.
+section. It defaults to 1, and works only if 'daemon' or 'master_worker' mode
+is selected. One typical usage of this parameter has been to workaround
+the default per-process file-descriptor limit that Solaris imposes to user
+processes.
Example :
---------
@@ -312,10 +324,11 @@ Example :
-------------------------------
Haproxy now supports the notion of pidfile. If the '-p' command line argument,
or the 'pidfile' global option is followed with a file name, this file will be
-removed, then filled with all children's pids, one per line (only in daemon
-mode). This file is NOT within the chroot, which allows to work with a readonly
- chroot. It will be owned by the user starting the process, and will have
-permissions 0644.
+removed, then filled with all children's pids, one per line (only if daemon
+or master_worker mode is selected). This file is NOT within the chroot,
+which allows to work with a readonly chroot. It will be owned by the user
+starting the process, and will have permissions 0644. In master_worker mode
+the first pid in the pidfile will be that of the master.
Example :
---------
@@ -613,6 +626,14 @@ be useful to save the pidfile before starting a new
instance.
This mechanism fully exploited since 1.2.11 with the '-st' and '-sf' options
(see below).
+As of version 1.XXX a restart mechanism has been introduced. When running
+in master/worker mode if the master recieves a SIGUSR2 then it re-reads the
+configuration file, sends a SIGUSR1 to workers to gracefully shut them down
+and starts new workers. Soft-stopping workers is currently not supported on
+restart.
+
+If a worker recieves a SIGUSR2 it is ignored.
+
2.4.1) Hot reconfiguration
--------------------------
The '-st' and '-sf' command line options are used to inform previously running
diff --git a/doc/haproxy.1 b/doc/haproxy.1
index 001de15..e21b75f 100644
--- a/doc/haproxy.1
+++ b/doc/haproxy.1
@@ -6,7 +6,7 @@ HAProxy \- fast and reliable http reverse proxy and load
balancer
.SH SYNOPSIS
-haproxy \-f <configuration\ file> [\-n\ maxconn] [\-N\ maxconn] [\-d] [\-D]
[\-q] [\-V] [\-c] [\-p\ <pidfile>] [\-s] [\-l] [\-dk] [\-ds] [\-de] [\-dp]
[\-db] [\-m\ <megs>] [{\-sf|\-st}\ pidlist...]
+haproxy \-f <configuration\ file> [\-n\ maxconn] [\-N\ maxconn] [\-d] [\-D]
[\-q] [\-V] [\-c] [\-p\ <pidfile>] [\-s] [\-l] [\-dk] [\-ds] [\-de] [\-dp]
[\-db] [\-m\ <megs>] [{\-sf|\-sr|\-st}\ pidlist...]
.SH DESCRIPTION
@@ -116,6 +116,10 @@ run full debug.
Enforce a memory usage limit to a maximum of <megs> megabytes.
.TP
+\fB\-M\fP
+Use master/worker mode. This may be compined with daemon mode.
+
+.TP
\fB\-sf <pidlist>\fP
Send FINISH signal to the pids in pidlist after startup. The processes
which receive this signal will wait for all sessions to finish before
@@ -123,6 +127,13 @@ exiting. This option must be specified last, followed by
any number of
PIDs. Technically speaking, \fBSIGTTOU\fP and \fBSIGUSR1\fP are sent.
.TP
+\fB\-sr <pidlist>\fP
+Send RELOAD signal. If received by a master process it will re-read the
+configuration, signal its workers using the procedure described for
+\fB\-sf\fP and if that is successful start new workers. If received by a
+worker it is ignored.
+
+.TP
\fB\-st <pidlist>\fP
Send TERMINATE signal to the pids in pidlist after startup. The processes
which receive this signal will wait immediately terminate, closing all
@@ -143,9 +154,14 @@ Some signals have a special meaning for the haproxy
daemon. Generally, they are
.TP
\- \fBSIGUSR1\fP
Tells the daemon to stop all proxies and exit once all sessions are closed. It
is often referred to as the "soft-stop" signal.
+Used internally by \sB-sr\fP.
+
+\- \fBSIGUSR2\fP
+In master/worker mode the master will perform a restart. Ignored by workers.
.TP
\- \fBSIGTTOU\fP
-Tells the daemon to stop listening to all sockets. Used internally by
\fB\-sf\fP and \fB\-st\fP.
+Tells the daemon to stop listening to all sockets.
+Used internally by \fB\-sf\fP, \fB\-st\fP.
.TP
\- \fBSIGTTIN\fP
Tells the daemon to restart listening to all sockets after a \fBSIGTTOU\fP.
Used internally when there was a problem during hot reconfiguration.
--
1.7.2.3
