Snort 3 has extensive command-line help built in. Running snort --help provides a quick summary, and every option and module can be queried directly:
snort --help
snort -V
snort -?
Command-line options have the highest precedence. They override equivalent settings in your Lua configuration file.
| Option | Argument | Description |
|---|
-r | <file> | Read packets from a pcap file. |
-i | <interface> | Capture live traffic from a network interface. Separate multiple interfaces with spaces inside quotes. |
--pcap-dir | <dir> | Read all pcap files found in the given directory. |
--pcap-filter | <pattern> | Shell glob pattern to select files when using --pcap-dir (e.g., '*.pcap'). |
-n | <count> | Stop after processing this many packets. |
-s | <snaplen> | Set the snapshot length (bytes captured per packet). |
--stdin-rules | — | Read rules from stdin instead of a file. Combine with shell redirection. |
# Read a single pcap
snort -r /path/to/my.pcap
# Capture live traffic, limit to 100 packets
snort -i eth0 -n 100
# Process an entire directory of pcaps, only .pcap files
snort --pcap-dir /path/to/pcap/dir --pcap-filter '*.pcap' -L dump -d -e
# Read rules from stdin
snort -c snort.lua --stdin-rules < sample.rules
DAQ Options
Snort uses the DAQ (Data Acquisition) library for packet I/O. The default DAQ is pcap.
| Option | Argument | Description |
|---|
--daq | <type> | Select the DAQ module to use (e.g., pcap, afpacket, hext, file, socket). |
--daq-dir | <path> | Load external DAQ modules from this directory path. Must appear before --daq-list. |
--daq-list | — | List all available DAQ modules and exit. |
--daq-var | <name>=<value> | Set a DAQ-specific variable. Can be repeated. |
--daq-batch-size | <n> | Override daq.batch_size; sets the number of packets acquired per batch. |
# List available DAQs (load external ones first)
snort --daq-dir $my_path/lib/snort/daqs --daq-list
# Run inline with the afpacket DAQ on a bridged pair
snort -c snort.lua --daq afpacket -i "eth0:eth1" -A cmg
# Process hext packets from a file
snort -c snort.lua --daq-dir $my_path/lib/snort/daqs --daq hext \
--daq-var dlt=1 -r capture.hext
# Process raw files with 8K buffers using the file DAQ
snort -c snort.lua --daq-dir $my_path/lib/snort/daqs --daq file \
--pcap-dir path/to/files -z 4 -s 8192
Put --daq-dir before --daq-list or external DAQs will not appear in the listing.
Configuration
| Option | Argument | Description |
|---|
-c | <file> | Load the main Lua configuration file. |
-R | <file> | Load an additional rules file. |
--lua | '<snippet>' | Evaluate a Lua snippet to add or override configuration. Can be specified multiple times. |
--plugin-path | <path> | Load external plugin libraries from this path. |
--script-path | <path> | Search path for Lua scripts (e.g., LuaJIT rule options). |
--include-path | <path> | First search path for Snort include files. |
--warn-all | — | Enable all configuration warnings. |
--warn-conf-strict | — | Warn on Lua tables that do not map to any known Snort module. |
--warn-unknown | — | Warn on symbols unknown to Snort (silently ignored by default). |
--pedantic | — | Treat warnings as fatal errors. |
# Validate a configuration file (no packet source needed)
snort -c $my_path/etc/snort/snort.lua
# Validate config with a rules file
snort -c $my_path/etc/snort/snort.lua -R $my_path/etc/snort/sample.rules
# Override a setting inline without editing the config file
snort -c snort.lua --lua 'ips = { enable_builtin_rules = true }'
# Or change a single field within an existing table
snort -c snort.lua --lua 'ips.enable_builtin_rules = true'
# Suppress a specific alert inline
snort -c snort.lua -r pcap -A alert_test \
--lua "suppress = { { gid = 1, sid = 2123 } }"
# Enable strict warnings and make them fatal
snort -c snort.lua --warn-all --pedantic
# Load external plugins
snort -c snort.lua --plugin-path $my_path/lib/snort_extra -r pcap
The --lua option is processed after the configuration file, so it can override any setting. Use module.param = value syntax to change a single field rather than replacing the entire table.
Alert / Output
| Option | Argument | Description |
|---|
-A | <mode> | Enable an alert output plugin by name. See table below for available modes. |
-l | <dir> | Write output files to this log directory. Defaults to ./. |
--run-prefix | <prefix> | Prepend this string to all output file names. |
--id-subdir | — | Place per-thread output in numbered subdirectories (0/, 1/, …) instead of file name prefixes. |
--id-zero | — | Include the thread ID 0 in output file names even when there is only one packet thread. |
Alert Modes (-A)
| Mode | Description |
|---|
cmg | Same as -A fast -d -e: compact header info plus hex/text payload dump. |
fast | One-line alert summary per event. |
full | Full alert with all header fields. |
unified2 / u2 | Binary format compatible with external post-processors (e.g., Barnyard2). |
csv | Comma-separated values; fields and separator are configurable via alert_csv. |
json | JSON-formatted alerts. |
alert_test | Simple test format useful for scripted verification. |
# List all available logger plugins
snort --list-plugins | grep logger
<logdir>/[<run_prefix>][<id#>][<X>]<name>
X is / with --id-subdir or _ when a thread ID is included.
Examples:
# Alert to console in cmg format
snort -c snort.lua -r my.pcap -A cmg
# Write unified2 output to /tmp
snort -c snort.lua -r my.pcap -A unified2 -l /tmp
# Four packet threads, output in per-thread subdirectories
snort -c snort.lua --pcap-dir /pcaps --pcap-filter '*.pcap' \
-z 4 -A unified2 --id-subdir
# Capture stdout/stderr/log streams separately
snort -c snort.lua -r my.pcap -A csv 1>out 2>err 3>log
# Customise CSV fields
snort -c snort.lua --lua "alert_csv = { fields = 'pkt_num gid sid rev', separator = '\t' }"
Processing
| Option | Argument | Description |
|---|
-z / --max-packet-threads | <n> | Number of packet processing threads. Each input source (pcap / interface) runs on its own thread. |
--max-threads | <n> | Alias for --max-packet-threads. |
-L | <mode> | Packet logging mode: dump (stdout), pcap (write pcap), or hext (hex/text stream). |
-d | — | Dump application-layer (TCP/UDP) payload. |
-e | — | Show link-layer (layer 2) packet headers. |
-q | — | Quiet mode: suppress the startup banner and shutdown statistics. |
# Dump packets with payload and layer-2 headers
snort -r my.pcap -L dump -d -e
# Capture 10 live packets to a pcap file
snort -i eth0 -L pcap -n 10
# Dump TCP stream payload in hext format
snort -c snort.lua -L hext
# Process a pcap directory using 8 threads
snort -c snort.lua --pcap-dir /path/to/pcaps \
--pcap-filter '*.pcap' --max-packet-threads 8
# Run on two interfaces with two threads
snort -c snort.lua -i "eth0 eth1" -z 2 -A cmg
Command-line flags must be specified separately. snort -de will not work; use snort -d -e. You can still concatenate a flag and its argument: snort -Ldump is valid.
Help and Info
| Option | Argument | Description |
|---|
--help / -? | — | Print a summary of available options. |
-V | — | Print the Snort version and exit. |
--help-module | <name> | Show the parameters, peg counts, and commands for a specific module. |
--help-config | [<module>] | List all configuration parameters, optionally filtered to one module. |
--help-options | [<option>] | Show help for command-line options, optionally filtered by prefix string. |
--help-counts | — | List all available peg count names. |
--help-signals | — | List available process signals on this platform. |
--help-limits | — | Show the numeric values of max31, max32, etc. |
--list-plugins | — | List all loaded plugins (codecs, inspectors, loggers, etc.). |
--list-gids | — | List all generator IDs (GIDs) for internal Snort components. |
--list-builtin | — | List all built-in rule GIDs and SIDs. |
--markup | — | Format help output in AsciiDoc markup. |
# Show help for the stream_tcp module
snort --help-module stream_tcp
# Show the active module's configuration parameters
snort --help-module active
# Grep all configuration params for anything related to threads
snort --help-config | grep thread
# Get help for the -A option
snort --help-options A
# Output help for rule options in AsciiDoc format
snort --markup --help-options rule
# List internal GIDs and built-in rules
snort --list-gids
snort --list-builtin
Snort stops reading command-line options after a --help-* or --list-* option. Place any other options before these flags.
Shell
The interactive command shell must be enabled at build time with --enable-shell.
| Option | Argument | Description |
|---|
--shell | — | Enable the interactive command shell. The prompt is o")~. |
--pause | — | Pause after loading configuration (and again before exit). Resume with resume(). |
-j | <port> | Enable a telnet-accessible shell on the specified TCP port. |
# Enable shell mode
snort --shell -c snort.lua -r my.pcap
# Pause immediately after config load; use resume() to continue
snort --shell --pause -c snort.lua -r my.pcap
# Enable telnet access on port 12345
snort --shell -j 12345 -c snort.lua -i eth0
| Command | Description |
|---|
help() | List available shell commands. |
resume() | Continue processing after a --pause. |
quit() | Terminate Snort. |
detach() | Exit the shell without stopping Snort. |
The shell prompt can be changed by setting the SNORT_PROMPT environment variable.
Signals
When Snort is running as a daemon or long-lived process, you can control it with POSIX signals.
| Signal | Description |
|---|
SIGHUP | Reload the configuration file without restarting. |
SIGUSR1 | Dump current statistics to stdout immediately. |
SIGTERM | Shut down normally, flushing all in-flight packets. |
SIGQUIT | Exit immediately without flushing packets. |
# Append a suppress rule and reload
echo 'suppress = { { gid = 1, sid = 2215 } }' >> snort.lua
kill -hup <pid>
# Dump stats to stdout
kill -usr1 <pid>
# Graceful shutdown
kill -term <pid>
# Immediate exit (no flush)
kill -quit <pid>
# List signals available on this platform
snort --help-signals
Available signals may vary by platform. Use snort --help-signals to see what is supported on your system.
