doc/userguide: document TCP urgent policy

doc/userguide/configuration/suricata-yaml.rst

@@ -1305,6 +1305,58 @@ network inspection.
 .. image:: suricata-yaml/IDS_chunk_size.png
 
 
+TCP Urgent Handling
+^^^^^^^^^^^^^^^^^^^
+
+TCP Urgent pointer support is a complicated topic, where it is essentially impossible
+for a network device to know with certainty what the behavior of the receiving host is.
+
+For this reason, many middleboxes strip the URG flag and reset the urgent pointer (see
+for example RFC 6093, 3.4).
+
+Several options are provided to control how to deal with the urgent pointer.
+
+::
+
+    stream:
+      reassembly:
+      urgent:
+        policy: oob              # drop, inline, oob (1 byte, see RFC 6093, 3.1), gap
+        oob-limit-policy: drop
+
+`stream.reassembly.urgent.policy`:
+ - `drop`: drop URG packets before they affect the stream engine
+ - `inline`: ignore the urgent pointer and process all data inline
+ - `oob` (out of band): treat the last byte as out of band
+ - `gap`: skip the last byte, but do no adjust sequence offsets, leading to
+          gaps in the data
+
+If the urgent policy is set to `oob`, there is an additional setting. Since OOB data does
+advance the TCP sequence number, the stream engine tracks the number of bytes to make sure
+no GAPs in the non-OOB data are seen by the app-layer parsers and detection engine. This
+is currently limited to 64k per direction. If the number of OOB bytes exceeds that 64k, an
+additional policy is triggered: `stream.reassembly.urgent.oob-limit-policy`.
+
+`stream.reassembly.urgent.oob-limit-policy`:
+- `drop`: drop URG packets before they affect the stream engine
+- `inline`: ignore the urgent pointer and process all data inline
+- `gap`: skip the last byte, but do no adjust sequence offsets, leading to gaps in the data
+
+Observables
+"""""""""""
+
+Each packet with the URG flag set, will increment the `tcp.urg` counter.
+
+When dropping the URG packets, the packets will have the drop reason
+`ips.drop_reason.stream_urgent`, which is also a counter in the stats logging.
+
+The stream event `stream-event:reassembly_urgent_oob_limit_reached` allows matching on the
+packet that reaches the OOB limit. Stream rule `2210066` matches on this.
+
+If `stats.stream-events` are enabled the counter `stream.reassembly_urgent_oob_limit_reached`
+will be incremented if the OOB limit is reached.
+
+
 Host Tracking
 -------------