For the following examples "$my_path" is assumed to be the path to
the Snort++ install directory. Additionally, it is assumed that
"$my_path/bin" is in your PATH.
Environment
LUA_PATH is used directly by Lua to load and run required libraries.
SNORT_LUA_PATH is used by Snort to load supplemental configuration files.
export LUA_PATH=$my_path/include/snort/lua/\?.lua\;\;
export SNORT_LUA_PATH=$my_path/etc/snort
Help
Print the help summary:
snort --help
Get help on a specific module ("stream", for example):
snort --help-module stream
Get help on the "-A" command line option:
snort --help-options A
Grep for help on threads:
snort --help-config | grep thread
Output help on "rule" options in AsciiDoc format:
snort --markup --help-options rule
Note: Snort++ stops reading command-line options after the "--help-*" and "--list-*" options,
so any other options should be placed before them.
Sniffing and Logging
Read a pcap:
snort -r /path/to/my.pcap
Dump the packets to STDOUT:
snort -r /path/to/my.pcap -K text
Dump packets with application data and layer 2 headers
snort -r /path/to/my.pcap -K text -d -e
Note: Command line options must be specified separately. "snort -de" won't work.
You can still concatenate options and their arguments, however, so "snort -Ktext" will work.
Dump packets from all pcaps in a directory:
snort --pcap-dir /path/to/pcap/dir --pcap-filter '*.pcap' -K text -d -e
Log packets to a directory:
snort --pcap-dir /path/to/pcap/dir --pcap-filter '*.pcap' -K pcap \
-l /path/to/log/dir
Configuration
Validate a configuration file:
snort -c $my_path/etc/snort/snort.lua
Validate a rules file and a configuration file:
snort -c $my_path/etc/snort/snort.lua -R $my_path/etc/snort/sample.rules
Read rules from stdin and validate:
snort -c $my_path/etc/snort/snort.lua --stdin-rules < \
$my_path/etc/snort/sample.rules
Enable warnings for Lua configurations and make warnings fatal:
snort -c $my_path/etc/snort/snort.lua --warn-all --pedantic
Tell Snort++ where to look for additional Lua scripts:
snort --script-path /path/to/script/dir
IDS Mode
Run Snort++ in IDS mode, reading packets from a pcap:
snort -c $my_path/etc/snort/snort.lua -R $my_path/etc/snort/sample.rules \
-r /path/to/my.pcap
Log any generated alerts to the console using the "-A" option:
snort -c $my_path/etc/snort/snort.lua -R $my_path/etc/snort/sample.rules \
-r /path/to/my.pcap -A alert_full
Add or modify a configuration from the command line using the "--lua" option:
snort -c $my_path/etc/snort/snort.lua -r /path/to/my.pcap \
--lua 'ips = { enable_builtin_rules = true }'
Note: The "--lua" option can be specified multiple times.
Run Snort++ in IDS mode on an entire directory of pcaps, processing each input source on a separate thread:
snort -c $my_path/etc/snort/snort.lua --pcap-dir /path/to/pcap/dir \
--pcap-filter '*.pcap' --max-packet-threads 8
Output Files
To make it simple to configure outputs when you run with multiple packet
threads, output files are not explicitly configured. Instead, you can use
the options below to format the paths:
/[][][]
Log to unified in the current directory:
snort -c $my_path/etc/snort/snort.lua -r /path/to/my.pcap -A unified2
Log to unified in the current directory with a different prefix:
snort -c $my_path/etc/snort/snort.lua -r /path/to/my.pcap -A unified2 \
--run-prefix take2
Log to unified in /tmp:
snort -c $my_path/etc/snort/snort.lua -r /path/to/my.pcap -A unified2 \
-l /tmp
Run 4 packet threads and log with thread number prefix (0-3):
snort -c $my_path/etc/snort/snort.lua --pcap-dir /path/to/pcap/dir \
--pcap-filter '*.pcap' -z 4 -A unified2
Run 4 packet threads and log in thread number subdirs (0-3):
snort -c $my_path/etc/snort/snort.lua --pcap-dir /path/to/pcap/dir \
--pcap-filter '*.pcap' -z 4 -A unified2 --id-subdir
NOTE: subdirectories are created automatically if required. Log filename is based on module name that writes the file. All text mode outputs
default to stdout. These options can be combined.
Shell
You must build with --enable-shell to make the command line shell available.
Enable shell mode:
snort --shell
You will see the shell mode command prompt, which looks like this:
o")~
(The prompt can be changed with the SNORT_PROMPT environment variable.)
You can pause immediately after loading the configuration and again before
exiting with:
snort --shell --pause
In that case you must issue the resume() command to continue. Enter quit()
to terminate Snort or detach() to exit the shell. You can list the
available commands with help().
To enable local telnet access on port 12345:
snort --shell -j 12345
The command line interface is still under development. Suggestions are
welcome.
Signals
The following examples assume that Snort++ is currently running and
has a process ID of
.
Modify and Reload Configuration:
echo 'suppress = { { gid = 1, sid = 2215 } }' >> $my_path/etc/snort/snort.lua
kill -hup
Dump stats to stdout:
kill -usr1
Shutdown normally:
kill -term
Exit without flushing packets:
kill -quit
List available signals:
snort --help-signals
Note: The available signals may vary from platform to platform.
