From 481132e07c832033a8cc7ee5da7c49bf48c8a8d5 Mon Sep 17 00:00:00 2001 From: willy tarreau Date: Sun, 21 May 2006 21:43:10 +0200 Subject: [PATCH] [DOC] documented the 'stats' parameter. --- ROADMAP | 2 +- doc/haproxy-en.txt | 111 +++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 109 insertions(+), 4 deletions(-) diff --git a/ROADMAP b/ROADMAP index 8dae1ab49..9c0c95f01 100644 --- a/ROADMAP +++ b/ROADMAP @@ -8,7 +8,7 @@ + queueing 1.2.14 : - * HTML status page + + HTML status page stats enable stats uri /?stats diff --git a/doc/haproxy-en.txt b/doc/haproxy-en.txt index 2f9660e59..27ac4f067 100644 --- a/doc/haproxy-en.txt +++ b/doc/haproxy-en.txt @@ -22,6 +22,8 @@ availability environments. Indeed, it can : - block requests matching a particular pattern ; - hold clients to the right application server depending on application cookies + - report detailed status as HTML pages to authenticated users from an URI + intercepted from the application. It needs very little resource. Its event-driven architecture allows it to easily handle thousands of simultaneous connections on hundreds of instances without @@ -72,7 +74,7 @@ daemon mode and multi-process mode. The service can then be stopped by simply pressing Ctrl-C, without having to edit the config nor run full debug. Statistics are only available if compiled in with the 'STATTIME' option. It's -only used during code optimization phases. +only used during code optimization phases, and will soon disappear. The '-st' and '-sf' options are used for hot reconfiguration (see below). @@ -1230,8 +1232,8 @@ Notes : 4) Additionnal features ======================= -Other features are available. They are transparent mode, event logging and -header rewriting/filtering. +Other features are available. They are transparent mode, event logging, header +rewriting/filtering, and the status as an HTML page. 4.1) Network features @@ -2205,6 +2207,109 @@ Examples : defaults # this empty section voids all default parameters + +4.8) Status report in HTML page +------------------------------- +Starting with 1.2.14, it is possible for HAProxy to intercept requests for a +particular URI and return a full report of the proxy's activity and servers +statistics. This is available through the 'stats' keyword, associated to any +such options : + + - stats enable + - stats uri + - stats realm + - stats auth + - stats scope | '.' + +By default, the status report is disabled. Specifying any combination above +enables it for the proxy instance referencing it. The easiest solution is to +use "stats enable" which will enable the report with default parameters : + + - default URI : "/haproxy?stats" (CONFIG_STATS_DEFAULT_URI) + - default auth : unspecified (no authentication) + - default realm : "HAProxy Statistics" (CONFIG_STATS_DEFAULT_REALM) + - default scope : unspecified (access to all instances) + +The "stats uri " option allows one to intercept another URI prefix. +Note that any URI that BEGINS with this string will match. For instance, one +proxy instance might be dedicated to status page only and would reply to any +URI. + +Example : +--------- + # catches any URI and returns the status page. + listen stats :8080 + mode http + stats uri / + +The "stats auth " option enables Basic authentication and adds a +valid user:password combination to the list of authorized accounts. The user +and password are passed in the configuration file as clear text, and since this +is HTTP Basic authentication, you should be aware that it transits as clear +text on the network, so you must not use any sensible account. The list is +unlimited in order to provide easy accesses to developpers or customers. + +The "stats realm " option defines the "realm" name which is displayed +in the popup box when the browser asks for a password. It's important to ensure +that this one is not used by the application, otherwise the browser will try to +use a cached one from the application. Note that any space in the realm name +should be escaped with a backslash ('\'). + +The "stats scope " option limits the scope of the status report. By +default, all proxy instances are listed. But under some circumstances, it would +be better to limit the listing to some proxies or only to the current one. This +is what this option does. The special proxy name "." (a single dot) references +the current proxy. The proxy name can be repeated multiple times, even for +proxies defined later in the configuration or some which do not exist. The name +is the one which appears after the 'listen' keyword. + +Example : +--------- + # simple application with authenticated embedded status report + listen app1 192.168.1.100:80 + mode http + balance roundrobin + cookie SERVERID postonly insert indirect + server srv1 192.168.1.1:8080 cookie srv1 check inter 1000 + server srv1 192.168.1.2:8080 cookie srv2 check inter 1000 + stats uri /my_stats + stats realm Statistics\ for\ MyApp1-2 + stats auth guest:guest + stats auth admin:AdMiN123 + stats scope . + stats scope app2 + + # simple application with anonymous embedded status report + listen app2 192.168.2.100:80 + mode http + balance roundrobin + cookie SERVERID postonly insert indirect + server srv1 192.168.2.1:8080 cookie srv1 check inter 1000 + server srv1 192.168.2.2:8080 cookie srv2 check inter 1000 + stats uri /my_stats + stats realm Statistics\ for\ MyApp2 + stats scope . + + listen admin_page :8080 + mode http + stats uri /my_stats + stats realm Global\ statistics + stats auth admin:AdMiN123 + +Notes : +------- + - The 'stats' options can also be specified in the 'defaults' section, in + which case it will provide the exact same configuration to all further + instances (hence the usefulness of the scope "."). However, if an instance + redefines any 'stats' parameter, defaults will not be used for this + instance. + + - HTTP Basic authentication is very basic and unsecure from snooping. No + sensible password should be used, and be aware that there is no way to + remove it from the browser so it will be sent to the whole application + upon further accesses. + + ========================= | System-specific setup | =========================