DOC: master CLI documentation in management.txt
Documentation which explains the basic usage of the master CLI.
diff --git a/doc/management.txt b/doc/management.txt
index c8f8c65..dee7b20 100644
--- a/doc/management.txt
+++ b/doc/management.txt
@@ -30,6 +30,7 @@
9.1. CSV format
9.2. Typed output format
9.3. Unix Socket commands
+9.4. Master CLI
10. Tricks for easier configuration management
11. Well-known traps to avoid
12. Debugging and performance issues
@@ -269,6 +270,15 @@
parsing and during startup. It can be used in combination with "-c" to
just check if a configuration file is valid or not.
+ -S <bind>[,bind_options...]: in master-worker mode, bind a master CLI, which
+ allows the access to every processes, running or leaving ones.
+ For security reasons, it is recommended to bind the master CLI to a local
+ UNIX socket. The bind options are the same as the keyword "bind" in
+ the configuration file with words separated by commas instead of spaces.
+
+ Note that this socket can't be used to retrieve the listening sockets from
+ an old process during a seamless reload.
+
-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
@@ -2468,6 +2478,84 @@
'K' flag in the logs.
+9.4. Master CLI
+---------------
+
+The master CLI is a socket bound to the master process in master-worker mode.
+This CLI gives access to the unix socket commands in every running or leaving
+processes and allows a basic supervision of those processes.
+
+The master CLI is configurable only from the haproxy program arguments with
+the -S option. This option also takes bind options separated by commas.
+
+Example:
+
+ # haproxy -W -S 127.0.0.1:1234 -f test1.cfg
+ # haproxy -Ws -S /tmp/master-socket,uid,1000,gid,1000,mode,600 -f test1.cfg
+
+The master CLI introduces a new 'show proc' command to surpervise the
+processes:
+
+Example:
+
+ $ echo 'show proc' | socat /var/run/haproxy-master.sock -
+ #<PID> <type> <relative PID> <reloads> <uptime>
+ 1162 master 0 5 0d 00h02m07s
+ # workers
+ 1271 worker 1 0 0d 00h00m00s
+ 1272 worker 2 0 0d 00h00m00s
+ # old workers
+ 1233 worker 1 3 0d 00h00m43s
+
+
+In this example, the master has been reloaded 5 times but one of the old
+worker is still running and survived 3 reloads. You could access the CLI of
+this worker to understand what's going on.
+
+The master CLI uses a special prefix notation to access the multiple
+processes. This notation is easily identifiable as it begins by a @.
+
+A @ prefix can be followed by a relative process number or by an exclamation
+point and a PID. (e.g. @1 or @!1271). A @ alone could be use to specify the
+master. Leaving processes are only accessible with the PID as relative process
+number are only usable with the current processes.
+
+Examples:
+
+ $ socat /var/run/haproxy-master.sock readline
+ prompt
+ master> @1 show info; @2 show info
+ [...]
+ Process_num: 1
+ Pid: 1271
+ [...]
+ Process_num: 2
+ Pid: 1272
+ [...]
+ master>
+
+ $ echo '@!1271 show info; @!1272 show info' | socat /var/run/haproxy-master.sock -
+ [...]
+
+A prefix could be use as a command, which will send every next commands to
+the specified process.
+
+Examples:
+
+ $ socat /var/run/haproxy-master.sock readline
+ prompt
+ master> @1
+ 1271> show info
+ [...]
+ 1271> show stat
+ [...]
+ 1271> @
+ master>
+
+ $ echo '@1; show info; show stat; @2; show info; show stat' | socat /var/run/haproxy-master.sock -
+ [...]
+
+
10. Tricks for easier configuration management
----------------------------------------------