Migrating from Snort 2

Understand what changed between Snort 2 and Snort 3, and how to migrate your configuration and rules.

Snort 3 is a ground-up redesign of the Snort IPS. It delivers better throughput, detection accuracy, scalability, and extensibility—but backwards compatibility with Snort 2 was intentionally sacrificed to achieve those gains.

Your existing snort.conf and Snort 2.X rules will not work as-is with Snort 3. The configuration format has changed to Lua, and rule syntax has been updated. Use snort2lua to automate the conversion, then review the output manually.

This page explains what changed and what you need to do. To run the converter, see snort2lua: Configuration Converter.

Why migration is required

Snort 3 introduces a new configuration language (Lua), a new rule parser, a rewritten HTTP inspector, multi-threaded packet processing, and over 200 plugins—features that required breaking changes to the configuration and rule formats.

From the Snort 3 user manual:

Backwards compatibility with Snort 2 was sacrificed to obtain new and improved functionality. The configuration of Snort 3 is done with Lua, so your old conf won’t work as is. Rules are still text based but with syntax tweaks, so your 2.X rules must be fixed up.

The snort2lua tool handles most of the conversion automatically, but some changes require manual review.

What changed

Configuration format: snort.conf → snort.lua

Snort 2 used a custom configuration syntax in snort.conf. Snort 3 uses a Lua script (snort.lua).

Key implications:

• All module parameters are now Lua tables. Field names are case-sensitive (Snort 2 was largely case-insensitive).
• No positional parameters—everything uses name = value syntax.
• Size limits like "1234K" become limit = 1234, units = 'K'.
• Address list syntax: [[ and ]] must be written as [ [ and ] ] to avoid Lua string parsing errors (unless inside a quoted string).
• Module output filenames are no longer configurable: always <log-dir>/<module-name><suffix>.
• Because the Lua config is live code, file/line locations are not available in application error messages (syntax errors from Lua itself still show file and line).

Example of a simple module configuration in Snort 3:

-- Enable stream module with defaults
stream = { }

-- Configure active module
active = { max_responses = 1, min_interval = 5 }

Snort 3 will supply default global configs automatically. In Snort 2, omitting a global (e.g. http_inspect_global before http_inspect_server) was a fatal error.

Rule syntax changes

Rules remain text-based but several syntax rules changed.

Content sub-options must be comma-separated:

# Snort 2
content:"foo"; nocase;

# Snort 3
content:"foo", nocase;

Offset, depth, distance, and within use a space separator, not a colon:

# Snort 2
content:"foo"; offset:5; depth:10;

# Snort 3
content:"foo", offset 5, depth 10;

Sticky (buffer selector) options:

Buffer selectors must appear before the content option and remain in effect until changed. This replaces per-option buffer qualifiers.

# Snort 2 (per-option qualifier)
content:"foo"; http_uri;

# Snort 3 (sticky buffer)
http_uri; content:"foo";

uricontent is deleted—use sticky buffers:

# Snort 2
uricontent:"foo";

# Snort 3
http_uri; content:"foo";

urilen is replaced by bufferlen, which applies to the current sticky buffer.

All rules must have a sid. sid == 0 is not allowed.

activate / dynamic rules are deleted.

PCRE buffer selectors deleted

The following PCRE modifier flags that selected buffers have been removed. Use sticky buffers instead.

Deleted PCRE flag	Snort 3 equivalent
B	Use the appropriate sticky buffer option
U	http_uri;
P	http_client_body;
H	http_header;
M	http_method;
C	http_cookie;
I	http_raw_uri;
D	http_raw_header;
K	http_raw_cookie;
S	http_stat_code;
Y	http_stat_msg;

Example:

# Snort 2
pcre:"/foo/U";

# Snort 3
http_uri; pcre:"/foo/";

Service-based rules replace port-based rules

Snort 3 supports alert http, alert file, and other service-based rule headers. These are preferred over port-based detection because Snort 3 autodetects services.

# Snort 2 (port-based)
alert tcp $HOME_NET any -> $EXTERNAL_NET 80 ( ... )

# Snort 3 (service-based)
alert http $HOME_NET any -> $EXTERNAL_NET any ( ... )

Service-based rules disable fast pattern searching of raw packets. Port configurations are now largely optional because service autodetection handles traffic identification.

The metadata:service syntax also changed:

# Snort 2
metadata:service http;

# Snort 3
service:http;

metadata is now truly metadata with no impact on detection.

Preprocessors renamed and reorganized

Several Snort 2 preprocessors have been renamed in Snort 3:

Snort 2 preprocessor	Snort 3 module
frag3	defrag
arpspoof	arp_spoof
sfportscan	port_scan
perfmonitor	perf_monitor
bo	back_orifice
http_inspect_server	http_inspect

Plugin paths are consolidated: --dynamic-*-lib[-dir] is replaced by --plugin-path (with : separators).

The frag3 default policy changed from bsd to Linux.

Deleted configuration options

A number of Snort 2 configuration options no longer exist in Snort 3.

Deleted config directives (use rules instead):

• decode_*_alerts, decode_*_drops — use rules only
• disable_decode_alerts, disable_decode_drops, disable_ipopt_alerts, and similar decode/drop disable flags
• config threshold — replaced by event_filter
• flowbits_size, so_rule_memcap, include_vlan_in_alerts — removed
• cs_dir, sidechannel — control socket removed

Deleted rule options:

• fast_pattern:only — use fast_pattern, nocase instead (option is automatically omitted from detection tree if not required)
• fast_pattern:<offset>,<length> — use fast_pattern, fast_pattern_offset <offset>, fast_pattern_length <length>
• http_* content sub-options — now full standalone options
• metadata:engine shared and metadata:rule-flushing — deleted

Deleted output modules:

• alert_unified2 and log_unified2 — removed entirely; use JSON output
• log_ascii — removed
• layer2resets, flexresp2_* — removed

Output changes

• alert_fast now includes packet data by default.
• All text mode outputs default to stdout.
• Default logging mode is -L none.
• alert_unified2 and log_unified2 are deleted. JSON output (integrates with ELK stack) is now recommended.
• Snort 3 queues decoder and inspector events to the main event queue before IPS policy selection. Size the queue larger than with Snort 2.
• The intermediate HTTP and FTP/Telnet event queues are deleted.

Sensitive data (SDF preprocessor removed)

The Snort 2 SDF Preprocessor is gone. It is replaced by the sd_pattern IPS rule option.

sd_pattern uses the Hyperscan pattern matching library with a regex language similar to PCRE. It also serves as a fast pattern in the Snort engine, which significantly improves performance compared to the separate detection step in earlier versions.

The preprocessor alert SDF_COMBO_ALERT (139:1) has been removed with no replacement.

Command line changes

Several command line options changed or were removed:

Snort 2 option	Snort 3 equivalent
--dynamic-*-lib[-dir]	--plugin-path (colon-separated)
--search-method	Removed (configure in detection module)
--pid-path, --no-interface-pidfile	Deleted
-b, -N, -Z, --perfmon-file	Removed
Unknown args treated as BPF	Use --bpf explicitly

New options in Snort 3:

• --pause — load config and wait for resume before processing packets
• --shell — enable interactive Lua shell
• --help-config <prefix> — dump all matching settings
• -z <#> / --max-packet-threads <#> — set packet thread count
• -T — assumed if no input is given

Snort 2 vs Snort 3: feature comparison

Feature	Snort 2	Snort 3
Packet threads	1 per process	N per process
Config memory	N processes × M GB	M GB total, more for packets
Config reload	N processes, slower	1 thread, can pin to separate core
Config syntax	Custom, static, limited variables	Lua, fully scriptable
Service detection	appid only, port configs required	Autodetection, most port configs optional
HTTP inspector	Partly stateful	Fully stateful
HTTP Evader misses	65	10
Rule sticky buffers	Some	All buffers are sticky
Fast pattern buffers	6 available	14 available
Sensitive data	Separate slow search	Normal fast pattern rule
alert file rules	No	Yes
alert service rules	No	Yes
Event logging	Unified2 recommended	JSON recommended
Hyperscan	External patch	Native support, regex fast patterns
Rule parsing	Buggy, limited warnings	Robust, many optional warnings
Command line help	No	Extensive
Default config	Complex, needs tuning	Simplified, effective defaults

For the full comparison, see differences.txt in the Snort 3 upgrade documentation.

New features exclusive to Snort 3

These capabilities do not exist in Snort 2 and require no migration—they are available after upgrading:

• Regex fast patterns (not just literals)
• JSON perf monitor logs
• LuaJIT scriptable rule options and loggers
• Pub/sub inspection events
• C-style comments and #begin ... #end comment blocks in rules
• Rule rem: option for embedded comments
• alert file and alert service rules
• Fast pattern offload to a separate thread (experimental)
• Override any config item from the command line
• Pause and resume commands

Testing the migrated configuration

After converting with snort2lua, validate the output before deploying:

# Test configuration loads without errors
snort -c snort.lua

# Test configuration with rules
snort -c snort.lua -R your.rules

# Run against a packet capture to verify detection
snort -c snort.lua -R your.rules -r test.pcap -A alert_fast

# Override a single setting from the command line to test
snort -c snort.lua --lua 'ips.enable_builtin_rules = true'

Use snort --help-config <module> to inspect available parameters for any module. For example, snort --help-config stream lists all stream options and their defaults.

snort2lua will produce a .rej file listing anything it could not convert. Review this file carefully—each entry requires manual attention before your configuration is complete.