DOC: document tcp-request session

This is mostly a copy-paste-edit of the section about "tcp-request connection".
Maybe all these sections should be merged.

doc/configuration.txt

@@ -1867,6 +1867,7 @@ tcp-check send-binary                     -          -         X         X
 tcp-request connection                    -          X         X         -
 tcp-request content                       -          X         X         X
 tcp-request inspect-delay                 -          X         X         X
+tcp-request session                       -          X         X         -
 tcp-response content                      -          -         X         X
 tcp-response inspect-delay                -          -         X         X
 timeout check                             X          -         X         X
@@ -8665,7 +8666,7 @@ tcp-request connection <action> [{if | unless} <condition>]
         conditions, the simple action of logging each event would make the
         system collapse and would considerably lower the filtering capacity. If
         logging is absolutely desired, then "tcp-request content" rules should
-        be used instead.
+        be used instead, as "tcp-request session" rules will not log either.
 
     - expect-proxy layer4 :
         configures the client-facing connection to receive a PROXY protocol
@@ -8860,7 +8861,7 @@ tcp-request connection <action> [{if | unless} <condition>]
 
   See section 7 about ACL usage.
 
-  See also : "tcp-request content", "stick-table"
+  See also : "tcp-request session", "tcp-request content", "stick-table"
 
 
 tcp-request content <action> [{if | unless} <condition>]
@@ -8936,7 +8937,8 @@ tcp-request content <action> [{if | unless} <condition>]
   available.
 
   The "set-var" is used to set the content of a variable. The variable is
-  declared inline.
+  declared inline. For "tcp-request session" rules, only session-level
+  variables can be used, without any layer7 contents.
 
     <var-name> The name of the variable starts with an indication about
                its scope. The scopes allowed are:
@@ -9011,7 +9013,8 @@ tcp-request content <action> [{if | unless} <condition>]
 
   See section 7 about ACL usage.
 
-  See also : "tcp-request connection", "tcp-request inspect-delay"
+  See also : "tcp-request connection", "tcp-request session", and
+             "tcp-request inspect-delay"
 
 
 tcp-request inspect-delay <timeout>
@@ -9175,6 +9178,89 @@ tcp-response content <action> [{if | unless} <condition>]
   See also : "tcp-request content", "tcp-response inspect-delay"
 
 
+tcp-request session <action> [{if | unless} <condition>]
+  Perform an action on a validated session depending on a layer 5 condition
+  May be used in sections :   defaults | frontend | listen | backend
+                                 no    |    yes   |   yes  |   no
+  Arguments :
+    <action>    defines the action to perform if the condition applies. See
+                below.
+
+    <condition> is a standard layer5-only ACL-based condition (see section 7).
+
+  Once a session is validated, (ie. after all handshakes have been completed),
+  it is possible to evaluate some conditions to decide whether this session
+  must be accepted or dropped or have its counters tracked. Those conditions
+  cannot make use of any data contents because no buffers are allocated yet and
+  the processing cannot wait at this stage. The main use case it to copy some
+  early information into variables (since variables are accessible in the
+  session), or to keep track of some information collected after the handshake,
+  such as SSL-level elements (SNI, ciphers, client cert's CN) or information
+  from the PROXY protocol header (eg: track a source forwarded this way). The
+  extracted information can thus be copied to a variable or tracked using
+  "track-sc" rules. Of course it is also possible to decide to accept/reject as
+  with other rulesets. Most operations performed here could also be performed
+  in "tcp-request content" rules, except that in HTTP these rules are evaluated
+  for each new request, and that might not always be acceptable. For example a
+  rule might increment a counter on each evaluation. It would also be possible
+  that a country is resolved by geolocation from the source IP address,
+  assigned to a session-wide variable, then the source address rewritten from
+  an HTTP header for all requests. If some contents need to be inspected in
+  order to take the decision, the "tcp-request content" statements must be used
+  instead.
+
+  The "tcp-request session" rules are evaluated in their exact declaration
+  order. If no rule matches or if there is no rule, the default action is to
+  accept the incoming session. There is no specific limit to the number of
+  rules which may be inserted.
+
+  Several types of actions are supported :
+    - accept : the request is accepted
+    - reject : the request is rejected and the connection is closed
+    - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>]
+    - sc-inc-gpc0(<sc-id>)
+    - sc-set-gpt0(<sc-id>) <int>
+    - set-var(<var-name>) <expr>
+    - silent-drop
+
+  These actions have the same meaning as their respective counter-parts in
+  "tcp-request connection" and "tcp-request content", so please refer to these
+  sections for a complete description.
+
+  Note that the "if/unless" condition is optional. If no condition is set on
+  the action, it is simply performed unconditionally. That can be useful for
+  "track-sc*" actions as well as for changing the default action to a reject.
+
+  Example: track the original source address by default, or the one advertised
+           in the PROXY protocol header for connection coming from the local
+           proxies. The first connection-level rule enables receipt of the
+           PROXY protocol for these ones, the second rule tracks whatever
+           address we decide to keep after optional decoding.
+
+        tcp-request connection expect-proxy layer4 if { src -f proxies.lst }
+        tcp-request session track-sc0 src
+
+  Example: accept all sessions from white-listed hosts, reject too fast
+           sessions without counting them, and track accepted sessions.
+           This results in session rate being capped from abusive sources.
+
+        tcp-request session accept if { src -f /etc/haproxy/whitelist.lst }
+        tcp-request session reject if { src_sess_rate gt 10 }
+        tcp-request session track-sc0 src
+
+  Example: accept all sessions from white-listed hosts, count all other
+           sessions and reject too fast ones. This results in abusive ones
+           being blocked as long as they don't slow down.
+
+        tcp-request session accept if { src -f /etc/haproxy/whitelist.lst }
+        tcp-request session track-sc0 src
+        tcp-request session reject if { sc0_sess_rate gt 10 }
+
+  See section 7 about ACL usage.
+
+  See also : "tcp-request connection", "tcp-request content", "stick-table"
+
+
 tcp-response inspect-delay <timeout>
   Set the maximum allowed time to wait for a response during content inspection
   May be used in sections :   defaults | frontend | listen | backend