DOC: master CLI documentation in management.txt

Documentation which explains the basic usage of the master CLI.

doc/management.txt

@@ -30,6 +30,7 @@ Summary
 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 @@ list of options is :
     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 @@ shutdown sessions server <backend>/<server>
   '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
 ----------------------------------------------