[DOC] stats: document "show table" and "clear table"

doc/configuration.txt

@@ -8456,6 +8456,28 @@ clear counters all
   server. This has the same effect as restarting. This command is restricted
   and can only be issued on sockets configured for level "admin".
 
+clear table <table> key <key>
+  Remove entry <key> from the stick-table <table>. The key must be of the same
+  type as the table, which currently is limited to IPv4. This is typically used
+  un unblock some users complaining they have been abusively denied access to a
+  service, but this can also be used to clear some stickiness entries matching
+  a server that is going to be replaced (see "show table" below for details).
+  Note that sometimes, removal of a key will be refused because it is currently
+  tracked by a session. Retrying a few seconds later after the session ends is
+  usuall enough.
+
+  Example :
+    >>> $ echo "show table http_proxy" | socat stdio /tmp/sock1
+        # table: http_proxy, type: 0, size:204800, used:2
+        0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 bytes_out_rate(60000)=187
+        0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 bytes_out_rate(60000)=191
+
+        $ echo "clear table http_proxy key 127.0.0.1" | socat stdio /tmp/sock1
+
+        $ echo "show table http_proxy" | socat stdio /tmp/sock1
+        # table: http_proxy, type: 0, size:204800, used:1
+        0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 bytes_out_rate(60000)=191
+
 disable server <backend>/<server>
   Mark the server DOWN for maintenance. In this mode, no more checks will be
   performed on the server until it leaves maintenance.
@@ -8630,6 +8652,59 @@ show stat [<iid> <type> <sid>]
     A similar empty line appears at the end of the second block (stats) so that
     the reader knows the output has not been truncated.
 
+show table
+  Dump general information on all known stick-tables. Their name is returned
+  (the name of the proxy which holds them), their type (currently zero, always
+  IP), their size in maximum possible number of entries, and the number of
+  entries currently in use.
+
+  Example :
+    >>> $ echo "show table" | socat stdio /tmp/sock1
+        # table: front_pub, type: 0, size:204800, used:171454
+        # table: back_rdp, type: 0, size:204800, used:0
+
+show table <name> [ data.<type> <operator> <value> ]
+  Dump contents of stick-table <name>. In this mode, a first line of generic
+  information about the table is reported as with "show table", then all
+  entries are dumped. Since this can be quite heavy, it is possible to specify
+  a filter in order to specify what entries to display. The filter then applies
+  to the stored data (see "stick-table" in section 4.2). One stored data type
+  has to be specified in <type>, and this data type must be stored in the table
+  otherwise an error is reported. The data is compared according to <operator>
+  with the 64-bit integer <value>. Operators are the same as with the ACLs :
+    - eq : match entries whose data is equal to this value
+    - ne : match entries whose data is not equal to this value
+    - le : match entries whose data is less than or equal to this value
+    - ge : match entries whose data is greater than or equal to this value
+    - lt : match entries whose data is less than this value
+    - gt : match entries whose data is greater than this value
+
+  Example :
+    >>> $ echo "show table http_proxy" | socat stdio /tmp/sock1
+        # table: http_proxy, type: 0, size:204800, used:2
+        0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 bytes_out_rate(60000)=187
+        0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 bytes_out_rate(60000)=191
+
+    >>> $ echo "show table http_proxy data.gpc0 gt 0" | socat stdio /tmp/sock1
+        # table: http_proxy, type: 0, size:204800, used:2
+        0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 bytes_out_rate(60000)=191
+
+    >>> $ echo "show table http_proxy data.conn_rate gt 5" | socat stdio /tmp/sock1
+        # table: http_proxy, type: 0, size:204800, used:2
+        0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 bytes_out_rate(60000)=191
+
+  When the data criterion applies to a dynamic value dependent on time such as
+  a bytes rate, the value is dynamically computed during the evaluation of the
+  entry in order to decide whether it has to be dumped or not. This means that
+  such a filter could match for some time then not match anymore because as
+  time goes, the average event rate drops.
+
+  It is possible to use this to extract lists of IP addresses abusing the
+  service, in order to monitor them or even blacklist them in a firewall.
+  Example :
+        $ echo "show table http_proxy data.gpc0 gt 0" | socat stdio /tmp/sock1 \
+          | fgrep 'key=' | cut -d' ' -f2 | cut -d= -f2 > abusers-ip.txt
+          ( or | awk '/key/{ print a[split($2,a,"=")]; }' )
 
 /*
  * Local variables: