Lua Configuration

Snort 3’s configuration is a live Lua script. Every module that accepts parameters is configured by defining a Lua table with the same name as the module. Because it is real Lua, you can use functions, environment variables, conditionals, and computed values anywhere in the file.

Modules and Lua tables

Each Snort module maps directly to a Lua table. An empty table enables the module with internal defaults:

stream = { }

To change a parameter, add it to the table:

stream_tcp = { session_timeout = 60 }

You can also set fields after the initial declaration:

stream_tcp = { }
stream_tcp.session_timeout = 60

Multiple parameters at once:

active = { max_responses = 1, min_interval = 5 }

Getting module help

# List all parameters for a module
snort --help-module stream_tcp

# Show config for a specific module group
snort --help-config stream

The output format for each parameter is:

type module.name = default: help { range }

For example:

int active.max_responses = 0: maximum number of responses { 0: }

This means max_responses is an integer, defaults to 0, and accepts any non-negative value.

Parameter types

Type	Description
`addr`	Any valid IPv4 or IPv6 address or CIDR
`bool`	`true` or `false`
`enum`	A string selected from a fixed list
`int`	Whole number within the given range
`real`	Floating-point number within the given range
`string`	Any string up to the given length
`multi`	One or more space-separated strings from a range
`port`	Integer from `0` to `65535`
`mac`	Ethernet address in `01:23:45:67:89:ab` format

Numeric ranges use low:high notation. Omitting a bound means no hard limit — 0: means any non-negative integer.

The snort.lua structure

The default snort.lua organises configuration into eight sections:

---------------------------------------------------------------------------
-- 1. configure defaults
---------------------------------------------------------------------------

-- Set the networks you are protecting (required)
HOME_NET = 'any'
EXTERNAL_NET = 'any'

include 'snort_defaults.lua'

---------------------------------------------------------------------------
-- 2. configure inspection
---------------------------------------------------------------------------

-- An empty table enables the module with internal defaults.
-- Use snort --help-module <name> to see those defaults.

stream = { }        -- enable stream reassembly
stream_tcp = { }    -- TCP stream tracking
stream_ip = { }     -- IP fragment reassembly
stream_icmp = { }
stream_udp = { }
stream_user = { }
stream_file = { }

normalizer = { }    -- normalize traffic for detection
dns = { }
imap = { }
http_inspect = { }
http2_inspect = { }
ssl = { }
ssh = { }
telnet = { }

-- Some inspectors use defaults defined in snort_defaults.lua
gtp_inspect = default_gtp
port_scan   = default_med_port_scan
smtp        = default_smtp
ftp_server  = default_ftp_server

---------------------------------------------------------------------------
-- 3. configure bindings
---------------------------------------------------------------------------

wizard = default_wizard

binder =
{
    { when = { proto = 'tcp', ports = '53', role='server' }, use = { type = 'dns' } },
    { when = { service = 'http' },  use = { type = 'http_inspect' } },
    { when = { service = 'smtp' },  use = { type = 'smtp' } },
    -- ... (see Binder page for the full list)
    { use = { type = 'wizard' } }   -- fallback: autodetect everything else
}

---------------------------------------------------------------------------
-- 4. configure performance
---------------------------------------------------------------------------

-- Uncomment to enable latency enforcement, profiling, or runtime metrics
-- latency = { }
-- profiler = { }
-- perf_monitor = { }

---------------------------------------------------------------------------
-- 5. configure detection
---------------------------------------------------------------------------

references      = default_references
classifications = default_classifications

ips =
{
    -- enable_builtin_rules = true,    -- decoder/inspector alerts
    variables = default_variables       -- HOME_NET, HTTP_PORTS, etc.
}

---------------------------------------------------------------------------
-- 6. configure filters
---------------------------------------------------------------------------

-- suppress = { { gid = 1, sid = 1 } }
-- event_filter = { ... }
-- rate_filter = { ... }

---------------------------------------------------------------------------
-- 7. configure outputs
---------------------------------------------------------------------------

-- alert_fast = { }
-- unified2 = { }

---------------------------------------------------------------------------
-- 8. configure tweaks
---------------------------------------------------------------------------

-- Load an optional tweaks file passed via --tweaks on the command line.
if ( tweaks ~= nil ) then
    include(tweaks .. '.lua')
end

The tweaks pattern lets you keep a clean base config and layer environment-specific overrides. For example:

snort -c snort.lua --lua 'tweaks = "balanced"'

This loads balanced.lua, which tunes http_inspect request/response depths and disables arp_spoof and port_scan.

snort_defaults.lua variables

snort_defaults.lua defines the variables that Talos rules and the default config expect. Include it after setting HOME_NET and EXTERNAL_NET:

HOME_NET = '192.168.0.0/16'
EXTERNAL_NET = '!192.168.0.0/16'

include 'snort_defaults.lua'

Network variables

-- Derived from HOME_NET — override individually if needed
DNS_SERVERS    = HOME_NET
FTP_SERVERS    = HOME_NET
HTTP_SERVERS   = HOME_NET
SIP_SERVERS    = HOME_NET
SMTP_SERVERS   = HOME_NET
SQL_SERVERS    = HOME_NET
SSH_SERVERS    = HOME_NET
TELNET_SERVERS = HOME_NET

Port variables

FTP_PORTS  = ' 21 2100 3535'

HTTP_PORTS = [[
    80 81 311 383 591 593 901 1220 1414 1741 1830 2301 2381 2809 3037 3128
    3702 4343 4848 5250 6988 7000 7001 7144 7145 7510 7777 7779 8000 8008
    8014 8028 8080 8085 8088 8090 8118 8123 8180 8181 8243 8280 8300 8800
    8888 8899 9000 9060 9080 9090 9091 9443 9999 11371 34443 34444 41080
    50002 55555
]]

MAIL_PORTS    = ' 110 143'
ORACLE_PORTS  = ' 1024:'
SIP_PORTS     = ' 5060 5061 5600'
SSH_PORTS     = ' 22'

-- Combined variable used internally by some inspectors
FILE_DATA_PORTS = HTTP_PORTS .. MAIL_PORTS

Path variables

RULE_PATH         = '../rules'
BUILTIN_RULE_PATH = '../builtin_rules'
PLUGIN_RULE_PATH  = '../so_rules'
WHITE_LIST_PATH   = '../lists'
BLACK_LIST_PATH   = '../lists'

These are assembled into default_variables and passed to the ips module so they are available inside rules as $HOME_NET, $HTTP_PORTS, etc.

Practical examples

stream_tcp
active
ips
http_inspect

-- Change TCP session tracking timeout to 60 seconds
stream_tcp = { session_timeout = 60 }

To inspect all available options:

snort --help-module stream_tcp

-- Send up to 1 TCP RST response, waiting at least 5 seconds between retries
active = { max_responses = 1, min_interval = 5 }

ips =
{
    enable_builtin_rules = true,    -- enable decoder and inspector alerts
    include = 'local.rules',        -- load a rules file
    variables = default_variables   -- make $HOME_NET etc. available in rules
}

-- Set inspection depth limits (from the balanced.lua tweak)
http_inspect = { }
http_inspect.request_depth  = 300
http_inspect.response_depth = 500

Lua as a live script

Because the config is executed as a Lua program, you can use the full language:

-- Read a value from the shell environment
local log_dir = os.getenv('SNORT_LOG_DIR') or '/var/log/snort'

-- Use Lua tables to build repeated config
local my_nets = { '10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16' }
HOME_NET = table.concat(my_nets, ' ')

-- Conditionally enable a module based on version
if SNORT_MINOR_VERSION >= 1 then
    detection = { pcre_override = false }
end

Disabling a module

To disable a module that was enabled in a parent or tweak file, set it to nil:

-- Disable arp_spoof
arp_spoof = nil

-- Disable port_scan
port_scan = nil

You can also rename a symbol to effectively disable it without removing the line — a convention used for commenting out optional configs:

-- Prefix with X to keep the line but disable the module
Xnormalizer = { }

To suppress the --warn-conf-strict warning for the Xnormalizer symbol:

snort_whitelist_add_prefix("X")

Get Started

Configuration

Inspectors & Detection

Running Snort

Migration from Snort 2

Lua Configuration

Modules and Lua tables

Getting module help

Parameter types

The snort.lua structure

snort_defaults.lua variables

Network variables

Port variables

Path variables

Practical examples

Lua as a live script

Disabling a module

Build docs developers (and LLMs) love

Get Started

Configuration

Inspectors & Detection

Running Snort

Migration from Snort 2

​Modules and Lua tables

​Getting module help

​Parameter types

​The snort.lua structure

​snort_defaults.lua variables

​Network variables

​Port variables

​Path variables

​Practical examples

​Lua as a live script

​Disabling a module

Build docs developers (and LLMs) love

Modules and Lua tables

Getting module help

Parameter types

The snort.lua structure

snort_defaults.lua variables

Network variables

Port variables

Path variables

Practical examples

Lua as a live script

Disabling a module