[airween]

Proposed changes

Document where the messages of the Lua m.log() function go, as agreed in owasp-modsecurity/ModSecurity#3035.

• Configuration directives, SecRuleScript: a new note after the first Lua example:
  • m.log(level, text) writes to the debug log, and only if SecDebugLogLevel is set to level or higher, with links to SecDebugLog and SecDebugLogLevel;
  • ModSecurity v2 also copies levels 1-3 to the Apache error log;
  • libModSecurity v3 writes them only to the debug log, never to the web server's error log or the console, and not at all in a build configured with --disable-debug-logs.

Closes owasp-modsecurity/ModSecurity#3035

Further comments

• v3: Lua::log() (src/engine/lua.cc) calls ms_dbg_a(), which writes only to the debug log, and only if the debug log level is at least the given level (headers/modsecurity/transaction.h). With --disable-debug-logs, configure defines NO_LOGS, and ms_dbg_a() does nothing.
• v2: l_log() (apache2/msc_lua.c) calls msr_log(), which also sends levels 1-3 to the Apache error log (apache2/apache2_util.c). The existing SecDebugLogLevel text describes this for v2, so users coming from v2 expect the same in v3.

AI disclosure

Made with help of Claude Code, Opus 5.5

[fzipi]

Thanks @airween. The v3 half is right, but the v2 half needs a small fix, see inline.

What I checked:

• v3. Lua::log() only calls ms_dbg_a(), which writes to the debug log when m_debugLevel >= level, and is an empty macro under NO_LOGS, which --disable-debug-logs defines (configure.ac). So "only to the debug log" and the --disable-debug-logs sentence are correct.
• v2. l_log() calls msr_log(), and internal_log_ex() (apache2/apache2_util.c) only returns early for level > 3. Messages at levels 1–3 are always sent to the Apache error log and added to msr->alerts, even with no SecDebugLog and SecDebugLogLevel 0. That list becomes the Message: lines in the audit log, and is_relevant++ makes the transaction relevant for SecAuditEngine RelevantOnly. So "only if SecDebugLogLevel is set to level or higher" applies to the debug log only, and in v2 levels 1–3 also reach the audit log. The SecDebugLogLevel section already says they are "always copied" to the error log, so the note should match it.