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.


=== 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 -L dump

Dump packets with application data and layer 2 headers

    snort -r /path/to/my.pcap -L dump -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 -Ldump" will work.

Dump packets from all pcaps in a directory:

    snort --pcap-dir /path/to/pcap/dir --pcap-filter '*.pcap' -L dump -d -e

Log packets to a directory:

    snort --pcap-dir /path/to/pcap/dir --pcap-filter '*.pcap' -L dump -l /path/to/log/dir


=== Configuration

Validate a configuration file:

    snort -c $my_path/etc/snort/snort.lua

Validate a configuration file and a separate rules 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 /path/to/my.pcap

Log any generated alerts to the console using the "-A" option:

    snort -c $my_path/etc/snort/snort.lua -r /path/to/my.pcap -A alert_full

Capture separate stdout, stderr, and stdlog files (out has startup and
shutdown output, err has warnings and errors, and log has alerts):

    snort -c $my_path/etc/snort/snort.lua -r /path/to/my.pcap -A csv \
        1>out 2>err 3>log

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 -A cmg \
        --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

Run Snort on 2 interfaces, eth0 and eth1:

    snort -c $my_path/etc/snort/snort.lua -i "eth0 eth1" -z 2 -A cmg

Run Snort inline with the afpacket DAQ:

    snort -c $my_path/etc/snort/snort.lua --daq afpacket -i "eth0:eth1" \
        -A cmg


=== Plugins

Load external plugins and use the "ex" alert:

    snort -c $my_path/etc/snort/snort.lua \
        --plugin-path $my_path/lib/snort_extra \
        -A alert_ex -r /path/to/my.pcap

Test the LuaJIT rule option 'find' loaded from stdin:

    snort -c $my_path/etc/snort/snort.lua \
        --script-path $my_path/lib/snort_extra \
        --stdin-rules -A cmg -r /path/to/my.pcap << END
    alert tcp any any -> any 80 (
        sid:3; msg:"found"; content:"GET";
        find:"pat='HTTP/1%.%d'" ; )
    END


=== 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:

    <logdir>/[<run_prefix>][<id#>][<X>]<name>

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.


=== DAQ Alternatives

Process hext packets from stdin:

    snort -c $my_path/etc/snort/snort.lua \
        --daq-dir $my_path/lib/snort/daqs --daq hext -i tty << END
    $packet 10.1.2.3 48620 -> 10.9.8.7 80
    "GET / HTTP/1.1\r\n"
    "Host: localhost\r\n"
    "\r\n"
    END

Process raw ethernet from hext file:

    snort -c $my_path/etc/snort/snort.lua \
        --daq-dir $my_path/lib/snort/daqs --daq hext \
        --daq-var dlt=1 -r <hext-file>

Process a directory of plain files (ie non-pcap) with 4 threads with 8K
buffers:

    snort -c $my_path/etc/snort/snort.lua \
        --daq-dir $my_path/lib/snort/daqs --daq file \
        --pcap-dir path/to/files -z 4 -s 8192

Bridge two TCP connections on port 8000 and inspect the traffic:

    snort -c $my_path/etc/snort/snort.lua \
        --daq-dir $my_path/lib/snort/daqs --daq socket


=== Logger Alternatives

Dump TCP stream payload in hext mode:

    snort -c $my_path/etc/snort/snort.lua -L hext
    
Output timestamp, pkt_num, proto, pkt_gen, dgm_len, dir, src_ap, dst_ap,
rule, action for each alert:

    snort -c $my_path/etc/snort/snort.lua -A csv

Output the old test format alerts:

    snort -c $my_path/etc/snort/snort.lua \
        --lua "alert_csv = { fields = 'pkt_num gid sid rev', separator = '\t' }"


=== Shell

You must build with --enable-shell to make the command line shell available.

Enable shell mode:

    snort --shell <args>

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 <args>

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 <args>

The command line interface is still under development.  Suggestions are 
welcome.


=== Signals

NOTE: The following examples assume that Snort is currently running and has
a process ID of <pid>.

Modify and Reload Configuration:

    echo 'suppress = { { gid = 1, sid = 2215 } }' >> $my_path/etc/snort/snort.lua
    kill -hup <pid>

Dump stats to stdout:

    kill -usr1 <pid>

Shutdown normally:

    kill -term <pid>

Exit without flushing packets:

    kill -quit <pid>

List available signals:

    snort --help-signals

NOTE: The available signals may vary from platform to platform.

