snort2lua: Configuration Converter

Use snort2lua to automatically convert Snort 2.x configuration files and rules to Snort 3 Lua format.

snort2lua is a tool included with Snort 3 that converts Snort 2.x configuration files and rules into the Lua-based format that Snort 3 requires. It reads your existing snort.conf and any included files, then generates a snort.lua configuration and converted rule files.

snort2lua is built and installed automatically as part of the Snort 3 build. Its source is located in tools/snort2lua/ within the Snort 3 source tree.

Basic usage

The only required argument is a Snort 2 configuration file:

snort2lua -c snort.conf

This generates snort.lua in the current directory. If the input is a valid Snort 2 configuration, the output will always be a valid Snort 3 configuration—any conversion errors reflect Snort 3 features that are not yet supported or options that were deleted.

Output files

Running snort2lua produces up to four types of output:

Output	Default name	Description
Lua config file	snort.lua	Main Snort 3 configuration in Lua syntax
Rule file	snort.lua (inline)	Converted rules; use -r to write to a separate file
Error file	snort.rej	Lines that could not be converted; only created if errors exist
Console	stdout	Count of errors and the name of the error file

Every keyword from the Snort 2 configuration appears in the output. When an option has been renamed, a comment in the output file shows both the old and new names.

Any line that was a comment in the Snort 2 config is placed in a comments section at the bottom of the output Lua file.

Command-line options

snort2lua [options]

Flag	Description
-c <file>	Required. Snort 2 configuration file to convert.
-r <file>	Write all converted rules to this file instead of the Lua output file. Useful when converting only rules.
-R	Collect all rules from every included file into a single rule file.
-L	Pull all Lua syntax from every include file into the main output file.
-q	Quiet mode: produce a clean Snort 3 configuration. Omits errors, differences, and comments from the output.
-d	Differences mode: output only the options that changed between Snort 2 and Snort 3. Does not produce a valid Snort 3 configuration.

Output modes

Default mode

Prints everything: new syntax, original comments, a record of what changed, and all conversion errors.

snort2lua -c snort.conf

Use this when doing an initial conversion and audit of your configuration.

Quiet mode

Produces a clean Snort 3 configuration file. Errors, differences, and comments are omitted from the output file.

snort2lua -c snort.conf -q

Use this when you want a minimal, production-ready output without conversion annotations.

Differences mode

Shows only the options that differ between Snort 2 and Snort 3. The output is not a valid Snort 3 configuration.

snort2lua -c snort.conf -d

Use this to audit what changed without generating a full configuration.

Converting a configuration file

1. Run snort2lua on your Snort 2 config

   snort2lua -c snort.conf
   

   This generates snort.lua and, if there are conversion errors, snort.rej.

2. Review the error file

   cat snort.rej
   

   Each entry in snort.rej is a line that could not be converted automatically. There are two categories:

   • Syntax errors: The Snort 2 config has invalid syntax that Snort 2 itself could not parse.
   • Unsupported options: The option exists in Snort 2 but is not supported in Snort 3. As Snort 3 adds support for more options, snort2lua will handle more of these automatically.
3. Validate the converted configuration

   snort -c snort.lua
   

   Snort 3 will load the configuration, report all errors (not just the first), and exit. Fix any reported issues in snort.lua before proceeding.

4. Test with rules

   snort -c snort.lua -R your.rules
   

   If you converted rules separately, load them explicitly. Snort will validate that the rule syntax is correct.

5. Run against a packet capture

   snort -c snort.lua -R your.rules -r test.pcap -A alert_fast
   

   Verify that detection works as expected before deploying.

Converting a rule file

To convert a standalone rules file without a full configuration:

snort2lua -c snort.rules -r updated.rules

The output updated.rules will always be a valid Snort 3 rule file. Any rule that contains unsupported options will be converted as best as possible and then printed as a comment in the output file—it will not be active.

Rules with unsupported options are silently commented out in the output. Always review the converted rule file and search for commented-out rules that need manual correction.

Rules file handling

Files with a .rules suffix are treated as Talos 2.X rule files and converted line by line:

• Lines starting with alert are converted as usual.
• Lines starting with # alert are assumed to be commented-out rules. They are converted to Snort 3 format and remain as comments in the output.
• All other comments are passed through without modification.

Multi-file configurations

By default, snort2lua follows every include and binding keyword and processes the referenced files automatically.

In Snort 3, every included file must be either a Lua file or a rules file—a single file cannot contain both Lua syntax and rules. When snort2lua encounters an include file that has both, it creates two separate output files: one .lua and one .rules.

When processing binding files:

• Rules and configuration are automatically combined into the same output file.
• The new filename is the original filename with a .lua extension appended.
• There is no way to specify a different output filename for binding files.

To pull all Lua content from included files into the main output file:

snort2lua -c snort.conf -L

To write all rules from all included files into a single rule file:

snort2lua -c snort.conf -R

If an included file cannot be found on disk, snort2lua still references it in the output. You will need to manually adjust or comment out the filename in snort.lua.

What snort2lua converts automatically

• Preprocessor names (e.g., frag3 → defrag, sfportscan → port_scan)
• Module parameter names (e.g., client_flow_depth → request_depth)
• Rule metadata syntax (metadata:service http; → service:http;)
• Content sub-option formatting (semicolon → comma separators)
• Sticky buffer syntax (converts http_* content sub-options to standalone buffer selectors)
• Detection method names (e.g., ac-bnfa → ac_bnfa)
• Unified2 output references to unified2
• CSV field names (e.g., src → src_addr, dst → dst_addr)
• event_filter and rate_filter field names (gen_id → gid, sig_id → sid)
• threshold IPS option → event_filter

What requires manual review

Some conversions cannot be done automatically:

Variables may not be resolved correctly

snort2lua does not always handle Snort 2 variables correctly. In some cases it substitutes the variable’s value directly rather than preserving the variable reference.

For example, include $RULE_PATH/example.rule may become include /etc/rules/example.rule in the output instead of keeping the variable.

Review all include statements and variable references in the output file.

Custom rule actions (ruletypes)

If a rule’s action is a custom ruletype, the rule action is silently converted to the rule’s base type. No warning or error is emitted. The custom ruletype’s associated outputs are also silently discarded.

Search the output for rules that used custom actions in Snort 2 and configure the appropriate output plugins manually.

Replace rules

If the original configuration contains a replace rule with an alert action, snort2lua keeps the action as alert rather than converting it to rewrite. In Snort 3, content replacement requires the rewrite action.

After conversion, search for rules that were replace rules in Snort 2 and update their action to rewrite manually.

Binding file names

When snort2lua processes a binding configuration file, the output filename is always the original filename with .lua appended. There is no option to specify a different output filename.

Unsupported Snort 3 options

Options that exist in Snort 2 but are not supported in Snort 3 produce entries in the .rej file. One example is dcerpc2. Review each rejection and determine whether it requires a workaround or can be removed.

Binding file error counts

If the original configuration contains a binding that points to another file and that binding file has errors, snort2lua reports the rejection count for the binding file separately from the main file count. The two counts are not yet combined into one total.

Understanding the output file

In default mode, snort.lua contains:

• Converted configuration — Lua tables for each Snort module.
• Change annotations — Comments showing old option names next to new names where options were renamed.
• Original comments — All comment lines from the Snort 2 config, collected at the bottom.
• Conversion errors — Any lines that could not be converted, noted inline.

In quiet mode (-q), only the converted configuration is written—no annotations, comments, or error notes.

Tips for cleaning up converted configuration

Review variable substitutions

Search snort.lua for hardcoded paths and IP addresses that should be variables. Restore variable references where snort2lua inlined the value.

Check commented-out rules

Search converted rule files for # alert lines. Each one is a rule that could not be fully converted and needs manual correction.

Verify includes

Confirm all include paths in snort.lua are correct. If snort2lua could not find a file, the path is preserved but may be wrong.

Remove deleted options

Options in snort.rej that map to deleted Snort 3 features can often simply be removed. Check config_changes.txt for the authoritative list.

Run Snort in test mode after every change

# Validate config only (no packet processing)
snort -c snort.lua

# Validate config and rules together
snort -c snort.lua -R your.rules

# Suppress a specific rule from the command line while testing
snort -c snort.lua -R your.rules -r test.pcap \
  --lua "suppress = { { gid = 1, sid = 2123 } }"

Snort 3 reports all configuration and rule errors before quitting, not just the first one. Run snort -c snort.lua after each round of edits to see the full error list at once.