From 97e01a8cc83889209d1ef23202283ea7971ae1e5 Mon Sep 17 00:00:00 2001
From: Jason Ish <jason.ish@oisf.net>
Date: Tue, 11 Feb 2025 16:37:54 -0600
Subject: [PATCH] doc/userguide: upgrade notes for Lua

- Sandboxed Lua for rules
- Search path changes for Lua output scripts
---
 doc/userguide/output/lua-output.rst | 11 +++++++++++
 doc/userguide/upgrade.rst           |  6 ++++++
 2 files changed, 17 insertions(+)

diff --git a/doc/userguide/output/lua-output.rst b/doc/userguide/output/lua-output.rst
index ab520e1aaa..9401d94e5e 100644
--- a/doc/userguide/output/lua-output.rst
+++ b/doc/userguide/output/lua-output.rst
@@ -75,6 +75,8 @@ Example:
       file:close(file)
   end
 
+.. _lua-output-yaml:
+
 YAML
 ----
 
@@ -87,6 +89,15 @@ scripts like so:
     - lua:
         enabled: yes
         scripts-dir: /etc/suricata/lua-output/
+
+        # By default the Lua module search paths are empty. If you plan
+        # to use external modules these paths will need to be set. The
+        # examples below are likely suitable for finding modules
+        # installed with a package manager on a 64 bit Linux system, but
+        # may need tweaking.
+        #path: "/usr/share/lua/5.4/?.lua;/usr/share/lua/5.4/?/init.lua;/usr/lib64/lua/5.4/?.lua;/usr/lib64/lua/5.4/?/init.lua;./?.lua;./?/init.lua"
+        #cpath: "/usr/lib64/lua/5.4/?.so;/usr/lib64/lua/5.4/loadall.so;./?.so"
+
         scripts:
           - tcp-data.lua
           - flow.lua
diff --git a/doc/userguide/upgrade.rst b/doc/userguide/upgrade.rst
index f5df98100f..282c5a0cf1 100644
--- a/doc/userguide/upgrade.rst
+++ b/doc/userguide/upgrade.rst
@@ -89,6 +89,12 @@ Major changes
   Suricata 8.0, ``stream.checksum-validation`` no longer affects the checksum rule keywords.
   E.g., ``ipv4-csum: valid`` will only match if the check sum is valid, even when engine
   checksum validations are disabled.
+- Lua detection scripts (rules) now run in a sandboxed
+  environment. See :ref:`lua-detection`.
+- Lua output scripts have no default module search path, a search path
+  will need to be set before external modules can be loaded. See the
+  new default configuration file or :ref:`lua-output-yaml` for more
+  details.
 
 Removals
 ~~~~~~~~
-- 
2.47.2