Configuration Overview

How Snort 3 is configured: the four input sources, precedence rules, include file resolution, and global Lua variables.

Snort 3 is configured from four sources, applied in order of increasing precedence:

Environment

Shell environment variables accessible inside the Lua config file.

Lua config file

The main snort.lua file loaded with -c. Provides full control over all modules.

Rules

Detection rules loaded via ips.include, -R, or inline with --lua.

Command line

Flags and --lua overrides. Highest precedence — always wins over the Lua file.

Command line

A typical invocation looks like:

snort -c snort.lua -R cool.rules -r some.pcap -A cmg

Flag	Purpose
-c snort.lua	Load the main Lua configuration file
-R cool.rules	Load a rules file
-r some.pcap	Read traffic from a pcap file (use -i eth0 for live)
-A cmg	Alert format (fast + packet headers + hex payload)

Command line options take precedence over Lua config. For example:

--daq-batch-size=32

will override any daq.batch_size value set in snort.lua.

Overriding Lua config inline

Use --lua to add or replace any Lua table without touching the config file:

# Replace the entire ips table
snort -c snort.lua --lua 'ips = { enable_builtin_rules = true }'

# Set a single field within the existing ips table
snort -c snort.lua --lua 'ips.enable_builtin_rules = true'

This is useful for one-off runs that keep all config files unchanged.

Configuration file

The -c flag loads a Lua script that is executed when parsed. Start with the default snort.lua included in the distribution — it contains the essential structure.

Most module entries look like:

stream = { }

An empty table enables the module using its internal defaults. To inspect those defaults:

snort --help-config stream
snort --help-module active

Include file resolution

When Snort resolves relative paths in include statements or module parameters, it searches in this order:

1. --include-path

   If you specified --include-path, that directory is tried first.

2. Directory of the including file

   The directory that contains the file that issued the include.

3. Directory of the -c config file

   The directory that contains the top-level snort.lua passed to -c.

4. Current working directory

   The directory from which Snort was launched.

Use include instead of Lua’s built-in dofile. The include function follows Snort’s search order; dofile executes before Snort sees the file, so you must provide absolute paths or cwd-relative paths with dofile.

As of this release, appid and reputation paths must be absolute or relative to the working directory. This will be updated in a future release.

Global Lua variables

When running with -c, Snort injects the following read-only globals into the Lua environment before executing your config file:

-- Version string
SNORT_VERSION = "3.0.2-x"

-- Individual version components
SNORT_MAJOR_VERSION = 3
SNORT_MINOR_VERSION = 0
SNORT_PATCH_VERSION = 2

-- Dependency versions (nil if not built with that library)
SNORT_DEP_VERSIONS.DAQ      = "3.0.7"
SNORT_DEP_VERSIONS.LUAJIT   = "2.1.0"
SNORT_DEP_VERSIONS.OPENSSL  = "3.0.5"
SNORT_DEP_VERSIONS.LIBPCAP  = "1.9.1"
SNORT_DEP_VERSIONS.PCRE     = "8.45"
SNORT_DEP_VERSIONS.ZLIB     = "1.2.11"
SNORT_DEP_VERSIONS.HYPERSCAN = "5.4.8"
SNORT_DEP_VERSIONS.LZMA     = "5.0.5"

Use these to write version-conditional config:

if SNORT_MAJOR_VERSION >= 3 then
    -- enable a Snort 3-only feature
end

Whitelist functions

When Snort is run with --warn-conf-strict, it warns on any Lua table in the config that does not map to a known module name. In --pedantic mode those warnings become errors.

To suppress warnings for custom Lua tables you intentionally define, call these functions anywhere in your config:

-- Whitelist specific table names exactly
snort_whitelist_append("table1 table2")

-- Whitelist all tables whose names start with a given prefix
snort_whitelist_add_prefix("local_ foobar_")

Both functions accept a whitespace-delimited list. The accumulated whitelist is printed when Snort runs in verbose mode (-v).

Strict validation flags

Flag	Effect
--warn-conf-strict	Warn on unknown Lua tables in the config
--pedantic	Promote all warnings to errors

Running with both flags during development catches typos and stale config entries early:

snort -c snort.lua --warn-conf-strict --pedantic

Loading rules

Rules can be loaded in three ways, and they can be combined:

-- In snort.lua: load an external rules file
ips = { include = 'rules.txt' }

# On the command line
snort -c snort.lua -R rules.txt

# Inline via --lua
snort -c snort.lua --lua 'ips = { enable_builtin_rules = true }'

Rules files can themselves include other rules files, so a single entry point can pull in an entire rule tree.