From: Jason Ish Date: Sat, 5 Dec 2015 15:09:52 +0000 (-0600) Subject: doc: command line options X-Git-Tag: suricata-3.2beta1~249 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4f9f9c09ec96fb9d295aeabe7726431385fd1d44;p=thirdparty%2Fsuricata.git doc: command line options --- diff --git a/doc/sphinx/command-line-options.rst b/doc/sphinx/command-line-options.rst new file mode 100644 index 0000000000..2857d5032a --- /dev/null +++ b/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|] : 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. diff --git a/doc/sphinx/dropping-privileges.rst b/doc/sphinx/dropping-privileges.rst new file mode 100644 index 0000000000..6edfa36a11 --- /dev/null +++ b/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 diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst index 9c75ba6521..bbfbfb7d41 100644 --- a/doc/sphinx/index.rst +++ b/doc/sphinx/index.rst @@ -6,4 +6,5 @@ Suricata User Guide :titlesonly: what-is-suricata + command-line-options rules/index.rst