diff --git a/doc/management.txt b/doc/management.txt index c8f8c65a9..dee7b20f5 100644 --- a/doc/management.txt +++ b/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_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 * : send the "finish" signal (SIGUSR1) to older processes after boot completion to ask them to finish what they are doing and to leave. is a list of pids to signal (one per argument). The list ends on any @@ -2468,6 +2478,84 @@ shutdown sessions 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 - + # + 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 ----------------------------------------------