doc/entropy: Describe unique names conf var

Discuss the new configuration variable that provides unique
names for entropy values in logging output: logging.entropy.make-unique

Issue: 7814

doc/userguide/configuration/suricata-yaml.rst

@@ -540,13 +540,13 @@ In multi mode the filename takes a few special variables:
   - %n representing the thread number
   - %i representing the thread id
   - %t representing the timestamp (secs or secs.usecs based on 'ts-format')
-  
+
   Example: filename: pcap.%n.%t
 
 .. note:: It is possible to use directories but the directories are not
   created by Suricata. For example ``filename: pcaps/%n/log.%s`` will log into
   the pre-existing ``pcaps`` directory and per thread sub directories.
-  
+
 .. note:: that the limit and max-files settings are enforced per thread. So the
   size limit using 8 threads with 1000mb files and 2000 files is about 16TiB.
 
@@ -2151,8 +2151,8 @@ A logging line exists of two parts. First it displays meta information
 
   i: suricata: This is Suricata version 7.0.2 RELEASE running in USER mode
 
-(Here the part until the second `:` is the meta info, 
-"This is Suricata version 7.0.2 RELEASE running in USER mode" is the actual 
+(Here the part until the second `:` is the meta info,
+"This is Suricata version 7.0.2 RELEASE running in USER mode" is the actual
 message.)
 
 It is possible to determine which information will be displayed in
@@ -3063,6 +3063,25 @@ headers are encapsulated in the same number of headers.
 Advanced Options
 ----------------
 
+entropy
+~~~~~~~
+
+When a rule causes an entropy value to be calculated for a flow, output for the flow will include
+the calculated entropy value. The log output contains the sticky buffer name for which the
+entropy was calculated. Often, more context is needed and the configuration setting shown
+below will amend the sticky buffer name with the signature id and instance number from the rule
+that caused the entropy value calculation. The instance number changes for each ``entropy``
+keyword usage within a rule.  The default value is ``off``. We strongly recommend changing
+the value to ``on``.
+
+::
+
+    logging:
+        # Ensure that logged entropy values have unique names by appending the signature_id
+        # of the rule and other values where used
+        #entropy:
+            #make-unique: off
+
 stacktrace
 ~~~~~~~~~~
 Display diagnostic stacktraces when a signal unexpectedly terminates Suricata, e.g., such as
@@ -3121,7 +3140,7 @@ Suricata 7.0 default:
        #allow-rules: true
 
        # Upper bound of allocations by a Lua rule before it will fail
-       #max-bytes: 500000 
+       #max-bytes: 500000
 
        # Upper bound of lua instructions by a Lua rule before it will fail
        #max-instructions: 500000

doc/userguide/rules/payload-keywords.rst

@@ -731,7 +731,7 @@ The following operators are available::
 This example matches if the `file.data` content for an HTTP transaction has
 a Shannon entropy value of 4 or higher::
 
-	alert http any any -> any any (msg:"entropy simple test"; file.data; entropy: value >= 4; sid:1;)
+    alert http any any -> any any (msg:"entropy simple test"; file.data; entropy: value >= 4; sid:1;)
 
 Logging
 ~~~~~~~
@@ -744,9 +744,28 @@ the ``metadata`` section of an output log. The follow is an example that shows
 the calculated entropy value with the buffer on which the value was computed::
 
      "metadata": {
-        "entropy": {
-          "file_data": 4.265743301617466
-        }
+        "entropy":[
+           {
+             "buffer":"file_data",
+             "value":4.150007324019584
+           }
+        ]
+      }
+
+When ``logging.entropy.make-unique`` is enabled, the format is modified to
+include the signature id, instance number (tracks which entropy keyword
+was used in a rule in case there are multiple usages), buffer and
+value::
+
+     "metadata": {
+        entropy": [
+          {
+            "sid": 1,
+            "buffer": "file_data",
+            "instance": 1,
+            "value": 4.137370175000773
+          }
+        ]
       }
 
 The events where entropy is logged will depend largely on how it's used within a