[DOC] add docs and examples of tarpit configuration

doc/haproxy-en.txt

@@ -2,9 +2,9 @@
                                  HAProxy
                             Reference  Manual
                            -------------------
-                              version 1.3.1
+                              version 1.3.2
                               willy tarreau
-                                2006/07/09
+                                2006/09/03
 
 ============
 | Abstract |
@@ -1741,6 +1741,9 @@ HTTP, each of which has a special meaning :
         L : the proxy was still transmitting LAST data to the client while the
             server had already finished.
 
+        T : the request was tarpitted. It has been held open on with the client
+            during the whole contimeout duration.
+
         - : normal session completion after end of data transfer.
 
   - the third character tells whether the persistence cookie was provided by
@@ -1842,6 +1845,10 @@ The most common termination flags combinations are indicated here.
           incomplete, dangerous (cache control), or matched a security filter.
           In any case, an HTTP 502 error is sent to the client.
 
+      PT  The proxy blocked the client's request and has tarpitted its
+          connection before returning it a 500 server error. Nothing was sent
+          to the server.
+
       cD  The client did not read any data for as long as the clitimeout delay.
           This is often caused by network failures on the client side.
 
@@ -2014,6 +2021,8 @@ The syntax is :
    reqideny  <search>             same, but ignoring the case
    reqpass   <search>             ignore a header matching <search>
    reqipass  <search>             same, but ignoring the case
+   reqtarpit <search>             tarpit a request matching <search>
+   reqitarpit <search>            same, but ignoring the case
 
    rspadd   <string>              to add a header to the response
    rsprep   <search> <replace>    to modify the response
@@ -2039,11 +2048,12 @@ Other characters may be prefixed with a backslash to change their meaning :
   \xXX to write the ASCII hex code XX as in the C language
 
 
-<replace> containst the string to be used to replace the largest portion of text
+<replace> contains the string to be used to replace the largest portion of text
 matching the regex. It can make use of the special characters above, and can
 reference a substring delimited by parenthesis in the regex, by the group
-numerical order from 1 to 9. In this case, you would write a backslah ('\')
+numerical order from 0 to 9 (0 being the entire line). In this case, you would
-immediately followed by one digit indicating the group position.
+write a backslash ('\') immediately followed by one digit indicating the group
+position.
 
 <string> represents the string which will systematically be added after the last
 header line. It can also use special characters above.
@@ -2062,6 +2072,11 @@ Notes :
     useless headers before adding new ones.
   - a denied request will generate an "HTTP 403 forbidden" response, while a
     denied response will generate an "HTTP 502 Bad gateway" response.
+  - a tarpitted request will be held open on the client side for a duration
+    defined in the contimeout parameter. Nothing will be sent to any server.
+    When the timeout is reached, the proxy will reply with a 500 server error
+    response so that the attacker does not suspect it has been tarpitted. The
+    logs will report the 500, but the termination flags will indicate 'PT'.
 
 
 Examples :
@@ -2092,6 +2107,9 @@ Examples :
         reqideny      ^[^:\ ]*\ .*<script
         reqideny      ^[^:\ ]*\ .*/(root\.exe\?|cmd\.exe\?|default\.ida\?)
 
+	# tarpit attacks on the login page.
+        reqtarpit     ^[^:\ ]*\ .*\.php?login=[^0-9]
+
         # allow other syntactically valid requests, and block any other method
         reqipass      ^(GET|POST|HEAD|OPTIONS)\ /.*\ HTTP/1\.[01]$
         reqipass      ^OPTIONS\ \\*\ HTTP/1\.[01]$

doc/haproxy-fr.txt

@@ -2,9 +2,9 @@
                                  HAProxy
                            Manuel de référence
                            -------------------
-                              version 1.3.1
+                              version 1.3.2
                               willy tarreau
-                                2006/07/09
+                                2006/09/03
 
 ================
 | Introduction |
@@ -1797,6 +1797,9 @@ une signification pr
         L : transfert des dernières ("LAST") données du proxy vers le client,
             alors que le serveur a déjà fini.
 
+        T : requête bloquée en mode "tarpit" par le proxy. Elle a été maintenue
+            ouverte vers le client pendant toute la durée du contimeout.
+
         - : terminaison normale, après fin de transfert des données.
 
   - le troisième caractère indique l'éventuelle identification d'un cookie de
@@ -1914,6 +1917,10 @@ Les combinaisons d'indicateurs les plus fr
           un filtre de sécurité. Dans tous les cas, une erreur HTTP 502 est
           renvoyée au client.
 
+      PT  Le proxy a bloqué une requête du client et a maintenu sa connection
+          ouverte avant de lui retourner une erreur "500 server error". Rien
+          n'a été envoyé au serveur.
+
       cD  Le client n'a pas lu de données pendant le temps qui lui était
           imparti. Ceci est souvent causé par des problèmes réseau côté client.
 
@@ -2091,6 +2098,8 @@ La syntaxe est :
    reqideny  <search>             idem sans distinction majuscules/minuscules
    reqpass   <search>             inhibe ces actions sur les en-têtes validant <search>
    reqipass  <search>             idem sans distinction majuscules/minuscules
+   reqtarpit <search>             bloquer et maintenir une request validant <search>
+   reqitarpit <search>            idem sans distinction majuscules/minuscules
 
    rspadd   <string>              pour ajouter un en-tête dans la réponse
    rsprep   <search> <replace>    pour modifier la réponse
@@ -2121,10 +2130,10 @@ backslach ('\') :
 <replace> contient la chaîne remplaçant la portion vérifiée par l'expression.
 Elle peut inclure les caractères spéciaux ci-dessus, faire référence à un
 groupe délimité par des parenthèses dans l'expression régulière, par sa
-position numérale. Les positions vont de 1 à 9, et sont codées par un '\'
+position numérale. Les positions vont de 0 à 9, et sont codées par un '\'
-suivi du chiffre désiré. Il est également possible d'insérer un caractère non
+suivi du chiffre désiré (0 désignant la ligne complète). Il est également
-imprimable (utile pour le saut de ligne) inscrivant '\x' suivi du code
+possible d'insérer un caractère non imprimable (utile pour le saut de ligne)
-hexadécimal de ce caractère (comme en C).
+inscrivant '\x' suivi du code hexadécimal de ce caractère (comme en C).
 
 <string> représente une chaîne qui sera ajoutée systématiquement après la
 dernière ligne d'en-tête.
@@ -2142,6 +2151,12 @@ Remarques :
     en-têtes inutiles avant les ajouts.
   - une requête bloquée produira une réponse "HTTP 403 forbidden" tandis qu'une
     réponse bloquée produira une réponse "HTTP 502 Bad gateway".
+  - une requête bloquée par 'reqtarpit' sera maintenue pendant une durée égale
+    au paramètre 'contimeout'. Rien ne sera envoyé au serveur. Lorsque le temps
+    alloué expire, le proxy répondra avec une réponse "500 server error" de
+    sorte que l'attaquant ne suspecte pas qu'il ait été bloqué. Les logs
+    rapporteront aussi ce code 500, mais les flags de terminaison indiqueront
+    "PT".
 
 Exemples :
 ----------
@@ -2171,6 +2186,9 @@ Exemples :
         reqideny        ^[^:\ ]*\ .*<script
         reqideny        ^[^:\ ]*\ .*/(root\.exe\?|cmd\.exe\?|default\.ida\?)
 
+	# tarpit attacks on the login page.
+        reqtarpit     ^[^:\ ]*\ .*\.php?login=[^0-9]
+
         # allow other syntactically valid requests, and block any other method
         reqipass        ^(GET|POST|HEAD|OPTIONS)\ /.*\ HTTP/1\.[01]$
         reqipass        ^OPTIONS\ \\*\ HTTP/1\.[01]$

examples/tarpit.cfg

@@ -0,0 +1,72 @@
+# This configuration is an example of how to use connection tarpitting based
+# on invalid requests.
+
+global
+        daemon
+        log 127.0.0.1 local0
+
+listen  frontend 0.0.0.0:80
+        mode    http
+        option  httplog
+        log     global
+        maxconn 10000
+
+	# do not log requests with no data
+        option  dontlognull
+
+	# log as soon as the server starts to respond, an do not wait for the
+	# end of the data transfer.
+        option  logasap
+
+	# disable keep-alive
+        option  httpclose
+
+	# load balancing mode set to round-robin
+        balance roundrobin
+
+        # the maxconn 150 below means 150 connections maximum will be used
+        # on apache, the remaining ones will be queued.
+	server  apache1 127.0.0.1:80 maxconn 150
+
+        # use short timeouts for client and server
+        clitimeout      20000
+        srvtimeout      20000
+
+	# the connect timeout should be large because it will also be used
+	# to define the queue timeout and the tarpit timeout. It generally
+	# is a good idea to set it to the same value as both above, and it
+	# will improve performance when dealing with thousands of connections.
+        contimeout      20000
+
+	# retry only once when a valid connection fails because the server
+	# is overloaded.
+        retries 1
+
+        # You might want to enable this option if the attacks start
+        # targetting valid URLs.
+        # option abortonclose
+
+	# not needed anymore.
+	#capture request header X-Forwarded-For len 15
+
+	# and add a new 'X-Forwarded-For: IP'	
+        option  forwardfor
+
+	# how to access the status reporting web interface
+        stats uri /stat
+        stats auth stat:stat
+
+	# Request header and URI processing begins here.
+
+	# rename the 'X-Forwarded-For:' header as 'X-Forwarded-For2:'
+        reqirep ^(X-Forwarded-For:)(.*) X-Forwarded-For2:\2
+
+	#### Now check the URI for requests we want to tarpit ###
+	# We do not analyze headers, we just focus on the request
+	reqpass ^[^:\ ]*:
+
+	# Tarpit those URIs for any method
+        reqtarpit  ^[^:\ ]*\ /invalid_req1
+        reqtarpit  ^[^:\ ]*\ /cgi-bin/.*\.pl\?
+        reqitarpit ^[^:\ ]*\ /.*\.(dll|exe|asp)
+