From: Russ Combs <rucombs@cisco.com>
Date: Mon, 9 Mar 2015 15:20:57 +0000 (-0400)
Subject: added doc/usage.txt
X-Git-Tag: 3.0.0-233~1031
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=da0155fea5c421fbcfb676a6accfc585e59a88dc;p=thirdparty%2Fsnort3.git

added doc/usage.txt
---

diff --git a/ChangeLog b/ChangeLog
index 9fa26f730..0a6ace0cf 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+Pending - build 141
+
+-- added doc/usage.txt
+
 15/02/27 - build 140
 
 -- uncrustify, see crusty.cfg
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 7372d5f37..1543d5f13 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -48,11 +48,12 @@ set (UNBUILT_SOURCES
     params.txt
     reference.txt
     snort2lua.txt
+    snorty.png
     snort_manual.txt
     start.txt
     style.txt
     terms.txt
-    snorty.png
+    usage.txt
 #   config_changes.txt  If ruby executable is not found
 )
 
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 75f0cb133..c7a5c4407 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -37,10 +37,11 @@ overview.txt \
 params.txt \
 reference.txt \
 snort2lua.txt \
+snorty.png \
 start.txt \
 style.txt \
 terms.txt \
-snorty.png
+usage.txt
 
 all_sources = \
 $(unbuilt_sources) \
diff --git a/doc/reference.txt b/doc/reference.txt
index 4ead489ca..2a79078b8 100644
--- a/doc/reference.txt
+++ b/doc/reference.txt
@@ -2,6 +2,10 @@
 
 include::terms.txt[]
 
+=== Usage
+
+include::usage.txt[]
+
 === Optional Features
 
 include::features.txt[]
diff --git a/doc/usage.txt b/doc/usage.txt
new file mode 100644
index 000000000..d4a6d0371
--- /dev/null
+++ b/doc/usage.txt
@@ -0,0 +1,227 @@
+NOTE: 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.
+
+
+==== Setting up the 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
+
+
+==== Getting help
+
+Print the help summary:
+
+    snort --help
+
+This outputs:
+
+    Snort has several options to get more help:
+
+    -? list command line options (same as --help)
+    --help this overview of help
+    --help-commands [<module prefix>] output matching commands
+    --help-config [<module prefix>] output matching config options
+    --help-counts [<module prefix>] output matching peg counts
+    --help-module <module> output description of given module
+    --help-modules list all available modules with brief help
+    --help-plugins list all available plugins with brief help
+    --help-options [<option prefix>] output matching command line options
+    --help-signals dump available control signals
+    --list-buffers output available inspection buffers
+    --list-builtin [<module prefix>] output matching builtin rules
+    --list-gids [<module prefix>] output matching generators
+    --list-modules [<module type>] list all known modules
+    --list-plugins list all known modules
+    --show-plugins list module and plugin versions
+
+    --help* and --list* options preempt other processing so should be last on the
+    command line since any following options are ignored.  To ensure options like
+    --markup and --plugin-path take effect, place them ahead of the help or list
+    options.
+
+    Options that filter output based on a matching prefix, such as --help-config
+    won't output anything if there is no match.  If no prefix is given, everything
+    matches.
+
+    Report bugs to bugs@snort.org.
+
+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 packets
+
+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:
+
+    <logdir>/[<run_prefix>][<id#>][<X>]<name>
+
+* logdir is set with -l and defaults to ./
+
+* run_prefix is set with --run-prefix else not used
+
+* id# is the packet thread number that writes the file; with one packet
+thread, id# (zero) is omitted without --id-zero
+
+* X is / if you use --id-subdir, else _ if id# is used
+
+* name is based on module name that writes the file
+
+* all text mode outputs default to stdout
+
+
+==== 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.
+
+
+==== Interacting with Snort++ via 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.
+