doc: command line options

doc/sphinx/command-line-options.rst

@@ -0,0 +1,78 @@
+Command Line Options
+====================
+
+.. toctree::
+
+   dropping-privileges
+
+You can use command line options in two ways. Using only one line
+followed by one character or using two lines followed by a word, like
+this:
+
+::
+
+  -a
+  --long-option
+
+::
+
+
+  -c     The -c option the most important option. After -c you can enter the path to the location of
+         suricata.yaml.
+
+  -i     After the -i option you can enter the interface card you would like to use to sniff packets from.
+         It concerns sniffing packets with libpcap in the pcap live mode.
+
+  -r     After the -r option you can enter the path to the pcap-file in which packets are recorded. That way
+         you can inspect the packets in that file in the pcap/offline mode.
+
+  -s     With the -s option you can set a file with signatures, which will be loaded together with the rules
+         set  in yaml.
+
+  -l     With the -l option you can set the default log directory. If you already have the default-log-dir set
+         in yaml, it  will not be used by Suricata if you use the -l option. It will use the log dir that is set
+         with the -l
+         option. If you do not set a directory with the -l option, Suricata will use the directory that is set
+         in yaml.
+
+
+  -D     Normally if you run Suricata on your console, it keeps your console occupied. You
+         can not use it for other purposes, and when you close the window, Suricata stops running.
+         If you run Suricata as deamon (using the -D option), it runs at the background and you will be able
+         to use the console for other tasks without disturbing the engine running.
+
+  --list-app-layer-protos              : list supported app layer protocols
+
+  --list-keywords[=all|csv|<kword>]    : list keywords implemented by the engine
+
+
+  --list-runmodes             The option --list-runmodes lists all possible runmodes.
+
+  --runmode (in combination with the command line opion -i or -r)
+                              With the --runmode option you can
+                              set the runmode that you would like to use. This command line option can override the
+                              yaml runmode option. For more information about runmodes see: [[Runmodes]].
+
+
+Unit Tests
+~~~~~~~~~~
+
+::
+
+  -u                 With the -u option you can run unit tests to test Suricata's code.
+
+  -U                 With the -U option you can select which of the unit tests you want to run. This option uses REGEX.
+                     Example of use:
+                     suricata -u -U http
+
+  --list-unittests   The --list-unittests option shows a list with all possible unit tests.
+
+  --fatal-unittests  With the --fatal-unittests option you can run unit tests but it will stop immediately after one test fails
+                     so you can see directly where it went wrong.
+
+PF_RING options
+~~~~~~~~~~~~~~~
+
+In order to use PF_RING-enabled libpcap, you must start suricata with
+the --pfring-int= switch or it will not invoke the PF_RING
+enhancements in libpcap.

doc/sphinx/dropping-privileges.rst

@@ -0,0 +1,69 @@
+Dropping Privileges After Startup
+=================================
+
+Currently, libcap-ng is needed for dropping privileges on Suricata
+after startup. For libcap, see status of feature request number #276
+-- Libcap support for dropping privileges.
+
+Download the current version of libcap-ng from upstream, see also
+http://people.redhat.com/sgrubb/libcap-ng/ChangeLog
+
+::
+
+  wget http://people.redhat.com/sgrubb/libcap-ng/libcap-ng-0.7.4.tar.gz
+  tar -xzvf libcap-ng-0.7.4.tar.gz
+  cd libcap-ng-0.7.4
+  ./configure
+  make
+  make install
+
+Download, configure, compile, and install Suricata for your particular
+setup. See [[**FIXME** Suricata Installation]] Depending on your environment,
+you may need to add the --with-libpcap_ng-libraries and
+--with-libpcap_ng-includes options during the configure step. e.g:
+
+::
+
+  ./configure --with-libcap_ng-libraries=/usr/local/lib \
+    --with-libcap_ng-includes=/usr/local/include
+
+Now, when you run Suricata, tell it what user and/or group you want it
+to run as after startup with the --user and --group options.
+e.g. (this assumes a 'suri' user and group):
+
+::
+
+  /usr/local/bin/suricata -c /etc/suricata/suricata.yaml \
+    -D -i eth0 --user=suri --group=suri
+
+You will also want to make sure your user/group permissions are set so
+suricata can still write to its log files which are usually located in
+/var/log/suricata.
+
+::
+
+  mkdir -p /var/log/suricata
+  chown -R root:suri /var/log/suricata
+  chmod -R 775 /var/log/suricata
+
+If you rely on the pid files be aware that as of version 1.4.x
+Suricata writes the pid file before it switches uids.  This means that
+the pid file will be owned by root and will not be readable by the
+alternative uid.  If this is an issue for you then a work around is to
+set the sgid bit on the directory that the pid file will be created
+in.  This will cause all files in this directory to inherit the gid
+from the parent directory rather than the creating process.
+
+::
+
+  chmod g+s ~sensors/sensor1/run
+
+  ls -ld ~sensors/sensor1/run
+  drwxr-sr-x 2 sensors sensors 4096 Aug  9 09:20 ~sensors/sensor1/run
+
+and so after running suricata we get
+
+::
+
+  ls -ld ~sensors/sensor1/run/suricata.pid
+  -rw-r----- 1 root sensors 6 Aug  9 09:20 ~sensors/sensor1/run/suricata.pid

doc/sphinx/index.rst

@@ -6,4 +6,5 @@ Suricata User Guide
    :titlesonly:
 
    what-is-suricata
+   command-line-options
    rules/index.rst