userguide/lua: add explanation about `need` diffs

The differences on how the `need` key works, depending on script
usage (output or detection) confuses users, sometimes (cf doc#4725).
While we don't fix that, just explain this behavior.

doc/userguide/lua/lua-functions.rst

@@ -3,6 +3,35 @@
 Lua functions
 =============
 
+Differences between `output` and `detect`:
+------------------------------------------
+
+Currently, the ``needs`` key initialization varies, depending on what is the goal of the script: output or detection.
+
+If the script is for detection, the ``needs`` initialization should be as seen in the example below (see :ref:`lua-scripting` for a complete example for a detect script):
+
+::
+
+  function init (args)
+      local needs = {}
+      needs["packet"] = tostring(true)
+      return needs
+  end
+
+For output logs, follow the pattern below. (The complete script structure can be seen at :ref:`lua-output`:)
+
+::
+
+  function init (args)
+      local needs = {}
+      needs["protocol"] = "http"
+      return needs
+  end
+
+
+Do notice that the functions and protocols available for ``log`` and ``match`` may also vary. DNP3, for instance, is not
+available for logging.
+
 packet
 ------
 
@@ -159,7 +188,7 @@ notation. To avoid that, simply do:
 http
 ----
 
-Init with:
+For output, init with:
 
 ::
 
@@ -169,6 +198,16 @@ Init with:
       return needs
   end
 
+For detection, use the specific buffer (cf :ref:`lua-detection` for a complete list), as with:
+
+::
+
+  function init (args)
+      local needs = {}
+      needs["http.uri"] = tostring(true)
+      return needs
+  end
+
 HttpGetRequestBody and HttpGetResponseBody.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -297,6 +336,27 @@ HttpGetResponseHeaders
 DNS
 ---
 
+If your purpose is to create a logging script, initialize the buffer as:
+
+::
+
+  function init (args)
+     local needs = {}
+     needs["protocol"] = "dns"
+     return needs
+  end
+
+If you are going to use the script for rule matching, choose one of the available DNS buffers listed in
+:ref:`lua-detection` and follow the pattern:
+
+::
+
+  function init (args)
+     local needs = {}
+     needs["dns.rrname"] = tostring(true)
+     return needs
+  end
+
 DnsGetQueries
 ~~~~~~~~~~~~~
 
@@ -383,7 +443,7 @@ returns a bool
 TLS
 ---
 
-Initialize with:
+For log output, initialize with:
 
 ::
 
@@ -393,6 +453,16 @@ Initialize with:
       return needs
   end
 
+For detection, initialization is as follows:
+
+::
+
+  function init (args)
+      local needs = {}
+      needs["tls"] = tostring(true)
+      return needs
+  end
+
 TlsGetVersion
 ~~~~~~~~~~~~~
 
@@ -519,7 +589,7 @@ JA3
 
 JA3 must be enabled in the Suricata config file (set 'app-layer.protocols.tls.ja3-fingerprints' to 'yes').
 
-Initialize with:
+For log output, initialize with:
 
 ::
 
@@ -529,6 +599,16 @@ Initialize with:
       return needs
   end
 
+For detection, initialization is as follows:
+
+::
+
+  function init (args)
+      local needs = {}
+      needs["tls"] = tostring(true)
+      return needs
+  end
+
 Ja3GetHash
 ~~~~~~~~~~
 
@@ -566,7 +646,7 @@ Ja3SGetHash
 
 Get the JA3S hash (md5sum of JA3S string) through JA3SGetHash.
 
-Example:
+Examples:
 
 ::
 
@@ -577,12 +657,27 @@ Example:
       end
   end
 
+Or, for detection:
+
+::
+
+  function match (args)
+      hash = Ja3SGetHash()
+      if hash == nil then
+        return 0
+      end
+
+      // matching code
+
+      return 0
+  end
+
 JA3SGetString
 ~~~~~~~~~~~~~
 
 Get the JA3S string through Ja3SGetString.
 
-Example:
+Examples:
 
 ::
 
@@ -593,6 +688,21 @@ Example:
       end
   end
 
+Or, for detection:
+
+::
+
+  function match (args)
+    str = Ja3SGetString()
+    if str == nil then
+      return 0
+    end
+
+    // matching code
+
+    return 0
+  end
+
 SSH
 ---
 
@@ -600,7 +710,6 @@ Initialize with:
 
 ::
 
-
   function init (args)
       local needs = {}
       needs["protocol"] = "ssh"
@@ -632,7 +741,6 @@ Example:
 
 ::
 
-
   function log (args)
       software = SshGetServerSoftwareVersion()
       if software == nil then

doc/userguide/lua/lua-usage.rst

@@ -4,9 +4,11 @@ Lua usage in Suricata
 Lua scripting can be used in two components of Suricata. The first is in
 output and the second one in rules in the detection engine.
 
-Both features are using a list of functions to access to data extracted by
+Both features are using a list of functions to access the data extracted by
 Suricata. You can get the list of functions in the :ref:`lua-functions` page.
 
+.. note:: Currently, there is a difference in the ``needs`` key in the ``init`` function, depending on what is the usage: ``output`` or ``detection``. The list of available functions may also differ.
+
 Lua output
 ----------
 

doc/userguide/rules/rule-lua-scripting.rst

@@ -16,7 +16,6 @@ The script has 2 parts, an init function and a match function. First, the init.
 Init function
 -------------
 
-
 .. code-block:: lua
 
   function init (args)
@@ -88,3 +87,6 @@ Entire script:
   end
 
   return 0
+
+A comprehensive list of existing lua functions -  with examples - can be found at :ref:`lua-functions` (some of them, however,
+work only for the lua-output functionality).