From: Jason Ish <ish@unx.ca>
Date: Fri, 4 Dec 2015 15:11:52 +0000 (-0600)
Subject: doc: rule lua scripting
X-Git-Tag: suricata-3.2beta1~262
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1e6df87ecb92d068ae72d28950ac0f2191f159cc;p=thirdparty%2Fsuricata.git

doc: rule lua scripting
---

diff --git a/doc/sphinx/rule-lua-scripting.rst b/doc/sphinx/rule-lua-scripting.rst
new file mode 100644
index 0000000000..9e0f6feff8
--- /dev/null
+++ b/doc/sphinx/rule-lua-scripting.rst
@@ -0,0 +1,90 @@
+Lua scripting
+=============
+
+In order to enable Lua scripting, please reference this page before
+continuing [[Installation from GIT with luajit]].
+
+Syntax:
+
+::
+
+  luajit:[!]<scriptfilename>;
+
+The script filename will be appended to your default rules location.
+
+The script has 2 parts, an init function and a match function. First, the init.
+
+Init function
+-------------
+
+
+.. code-block:: lua
+
+  function init (args)
+      local needs = {}
+      needs["http.request_line"] = tostring(true)
+      return needs
+  end
+
+The init function registers the buffer(s) that need
+inspection. Currently the following are available:
+
+* packet -- entire packet, including headers
+* payload -- packet payload (not stream)
+* http.uri
+* http.uri.raw
+* http.request_line
+* http.request_headers
+* http.request_headers.raw
+* http.request_cookie
+* http.request_user_agent
+* http.request_body
+* http.response_headers
+* http.response_headers.raw
+* http.response_body
+* http.response_cookie
+
+All the HTTP buffers have a limitation: only one can be inspected by a
+script at a time.
+
+Match function
+--------------
+
+.. code-block:: lua
+
+  function match(args)
+      a = tostring(args["http.request_line"])
+      if #a > 0 then
+          if a:find("^POST%s+/.*%.php%s+HTTP/1.0$") then
+              return 1
+          end
+      end
+
+      return 0
+  end
+
+The script can return 1 or 0. It should return 1 if the condition(s)
+it checks for match, 0 if not.
+
+Entire script:
+
+.. code-block:: lua
+
+  function init (args)
+      local needs = {}
+      needs["http.request_line"] = tostring(true)
+      return needs
+  end
+
+  function match(args)
+      a = tostring(args["http.request_line"])
+      if #a > 0 then
+          if a:find("^POST%s+/.*%.php%s+HTTP/1.0$") then
+              return 1
+          end
+      end
+
+      return 0
+  end
+
+  return 0
diff --git a/doc/sphinx/rules.rst b/doc/sphinx/rules.rst
index 0e95d52f09..67dcabd6c1 100644
--- a/doc/sphinx/rules.rst
+++ b/doc/sphinx/rules.rst
@@ -13,3 +13,4 @@ Rules
    flowint
    file-keywords
    thresholding
+   rule-lua-scripting