diff --git a/doc/userguide/command-line-options.rst b/doc/userguide/command-line-options.rst index ed522eff5d..77f6a381a6 100644 --- a/doc/userguide/command-line-options.rst +++ b/doc/userguide/command-line-options.rst @@ -5,114 +5,7 @@ Command Line Options Suricata's command line options: -.. option:: -h - - Display a brief usage overview. - -.. option:: -V - - Displays the version of Suricata. - -.. option:: -c - - Select suricata.yaml configuration file. - -.. option:: -i - - After the -i option you can enter the interface card you would like - to use to sniff packets from. This option will try to use the best - capture method available. - -.. option:: -v - - The -v option enables more verbosity of Suricata's output. Supply - multiple times for more verbosity. - -.. option:: -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. - -.. option:: -s - - With the -s option you can set a file with signatures, which will - be loaded together with the rules set in the yaml. - -.. option:: -S - - With the -S option you can set a file with signatures, which will - be loaded exclusively, regardless of the rules set in the yaml. - -.. option:: -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. - -.. option:: -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. - -.. option:: --runmode - - 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. - - Runmodes are: workers, autofp and single. - -For more information about runmodes see: :doc:`performance/runmodes` - -.. option:: --build-info - - Gives an overview of the configure and build options that were - supplied to Suricata's build process at compile time. - -Capture Options -~~~~~~~~~~~~~~~ - -.. option:: --af-packet[=] - - Enable capture of packet using AF_PACKET on Linux. If no device is - supplied, the list of devices from the af-packet section in the - yaml is used. - -.. option:: --netmap[=] - - Enable capture of packet using NETMAP on FreeBSD or Linux. If no - device is supplied, the list of devices from the netmap section - in the yaml is used. - -Advanced Options -~~~~~~~~~~~~~~~~ - -.. option:: --dump-config - - Displays a list of key value pairs with Suricata's configuration. - -.. option:: --set = - - Override any configuration option. - -.. option:: --list-app-layer-protos - - List supported app layer protocols. - -.. option:: --list-keywords[=all|csv|] - - List keywords implemented by the engine - -.. option:: --list-runmodes - - The option --list-runmodes lists all possible runmodes. +.. include:: partials/options.rst Unit Tests ~~~~~~~~~~ @@ -123,24 +16,4 @@ Builtin unittests are only available if Suricata has been built with Running unittests does not take a configuration file. Use -l to supply an output directory. -.. option:: -u - - With the -u option you can run unit tests to test Suricata's code. - -.. option:: -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 - -.. option:: --list-unittests - - The --list-unittests option shows a list with all possible unit - tests. - -.. option:: --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. - +.. include:: partials/options-unittests.rst diff --git a/doc/userguide/manpages/suricata.rst b/doc/userguide/manpages/suricata.rst index bb8922d4c9..c290dfd42c 100644 --- a/doc/userguide/manpages/suricata.rst +++ b/doc/userguide/manpages/suricata.rst @@ -14,183 +14,14 @@ Monitoring engine. Open Source and owned by a community run non-profit foundation, the Open Information Security Foundation (OISF). OPTIONS -------- +-------------- -.. option:: -c +.. include:: ../partials/options.rst - Path to configuration file. +OPTIONS FOR DEVELOPERS +---------------------- -.. option:: -T - - Test configuration. - -.. option:: -i - - Run in PCAP live mode on provided interface. - -.. option:: -F - - Use BPF filter from file. - -.. option:: -r - - Run in pcap offline mode reading files from pcap file. - -.. option:: -q - - Run inline of the NFQUEUE queue ID provided. May be provided - multiple times. - -.. option:: -s - - Path to a signature file to load. Will be loaded in addition to the - rule files specified in the configuration file. - -.. option:: -S - - Path to signature file to load exclusively. Signature files - specified in the configuration file will not be loaded. - -.. option:: -l - - Set log directory. Overrides the default-log-directory provided in - the configuration file. - -.. option:: -D - - Run as a daemon. - -.. option:: -k [all|none] - - Force (all) the checksum check or disable (none) all checksum - checks. - -.. option:: -V - - Display version. - -.. option:: -v[v] - - Increase the verbosity of logging. This is Suricata application - logging, not event or NSM logging. - -.. option:: -u - - Run the unit tests and exit. Requires that Suricata be compiled - with *--enable-unittests*. - -.. option:: -U, --unittest-filter=REGEX - - File the executed unit tests with a regular expression. - -.. option:: --list-unittests - - List all unit tests. - -.. option:: --fatal-unittests - - Enables fatal failure on a unit test error. Suricata will exit - instead of continuuing more tests. - -.. option:: --unittests-coverage - - Display unit test coverage report. - -.. option:: --list-app-layer-protos - - List all supported application layer protocols. - -.. option:: --list-keywords=[all|csv|] - - List all supported rule keywords. - -.. option:: --list-runmodes - - List all supported run modes. - -.. option:: --runmode - - Run with a specific run mode. Run modes may be viewed with the - *--list-runmodes* option. Usually one of *workers*, *autofp*, or - *single*. - -.. option:: --engine-analysis - - Print reports on analysis of different sections in the engine and - exit. Please have a look at the conf parameter engine-analysis on - what reports can be printed - -.. option:: --pidfile - - Write the process ID to file. Overrides the *pid-file* option in - the configuration file and forces the file to be written when not - running as a daemon. - -.. option:: --init-errors-fatal - - Exit with a failure when errors are encountered loading signatures. - -.. option:: --disable-detection - - Disable the detection engine. - -.. option:: --dump-config - - Dump the configuration loaded from the configuration file to the - terminal and exit. - -.. option:: --build-info - - Display the build information the Suricata was built with. - -.. option:: --pcap= - - Run in PCAP mode. If no device is provided the interfaces - provided in the *pcap* section of the configuration file will be - used. - -.. option:: --pcap-buffer-size= - - Set the size of the PCAP buffer (0 - 2147483647). - -.. option:: --af-packet= - - Run in AF_PACKET mode. If no device is provided the interfaces - provided in the *af-packet* section of the configuration file will be - used. - -.. option:: --simulate-ips - - Force the engine into IPS mode. Useful for QA. - -.. option:: --user= - - Set the process user after initialization. Overrides the user - provided in the *run-as* section of the configuration file. - -.. option:: --group= - - Set the process group to group after initialization. Overrides the - group provided in the *run-as* section of the configuration file. - -.. option:: --erf-in= - - Run in offline mode reading the specific ERF file (Endace - extensible record format). - -.. option:: --unix-socket= - - Use file as the Suricata unix control socket. Overrides the - *filename* provided in the *unix-command* section of the - configuration file. - -.. option:: --set = - - Set a configuration value. Useful for overriding basic - configuration parameters in the configuration. For example, to - change the default log directory:: - - --set default-log-dir=/var/tmp +.. include:: ../partials/options-unittests.rst FILES AND DIRECTORIES --------------------- diff --git a/doc/userguide/partials/options-unittests.rst b/doc/userguide/partials/options-unittests.rst new file mode 100644 index 0000000000..68087fa091 --- /dev/null +++ b/doc/userguide/partials/options-unittests.rst @@ -0,0 +1,25 @@ +.. Options for developers - unittests. + +.. option:: -u + + Run the unit tests and exit. Requires that Suricata be compiled + with *--enable-unittests*. + +.. option:: -U, --unittest-filter=REGEX + + 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 + +.. option:: --list-unittests + + List all unit tests. + +.. option:: --fatal-unittests + + Enables fatal failure on a unit test error. Suricata will exit + instead of continuuing more tests. + +.. option:: --unittests-coverage + + Display unit test coverage report. diff --git a/doc/userguide/partials/options.rst b/doc/userguide/partials/options.rst new file mode 100644 index 0000000000..70e2ae985d --- /dev/null +++ b/doc/userguide/partials/options.rst @@ -0,0 +1,222 @@ +.. Start with the most common basic options. + +.. option:: -h + + Display a brief usage overview. + +.. option:: -V + + Displays the version of Suricata. + +.. option:: -c + + Path to configuration file. + +.. option:: -T + + Test configuration. + +.. option:: -v + + The -v option enables more verbosity of Suricata's output. Supply + multiple times for more verbosity. + +.. Basic input options. + +.. option:: -r + + Run in pcap offline mode reading files from pcap file. + +.. option:: -i + + After the -i option you can enter the interface card you would like + to use to sniff packets from. This option will try to use the best + capture method available. + +.. option:: --pcap[=] + + Run in PCAP mode. If no device is provided the interfaces + provided in the *pcap* section of the configuration file will be + used. + +.. option:: --af-packet[=] + + Enable capture of packet using AF_PACKET on Linux. If no device is + supplied, the list of devices from the af-packet section in the + yaml is used. + +.. option:: -q + + Run inline of the NFQUEUE queue ID provided. May be provided + multiple times. + +.. Back to other basic options. + +.. option:: -s + + With the -s option you can set a file with signatures, which will + be loaded together with the rules set in the yaml. + +.. option:: -S + + With the -S option you can set a file with signatures, which will + be loaded exclusively, regardless of the rules set in the yaml. + +.. option:: -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. + +.. option:: -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. + +.. option:: --runmode + + 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. + + Runmodes are: *workers*, *autofp* and *single*. + + For more information about runmodes see :doc:`Runmodes + ` in the user guide. + +.. option:: -F + + Use BPF filter from file. + +.. option:: -k [all|none] + + Force (all) the checksum check or disable (none) all checksum + checks. + +.. option:: --user= + + Set the process user after initialization. Overrides the user + provided in the *run-as* section of the configuration file. + +.. option:: --group= + + Set the process group to group after initialization. Overrides the + group provided in the *run-as* section of the configuration file. + +.. option:: --pidfile + + Write the process ID to file. Overrides the *pid-file* option in + the configuration file and forces the file to be written when not + running as a daemon. + +.. option:: --init-errors-fatal + + Exit with a failure when errors are encountered loading signatures. + +.. option:: --disable-detection + + Disable the detection engine. + +.. Information options. + +.. option:: --dump-config + + Dump the configuration loaded from the configuration file to the + terminal and exit. + +.. option:: --build-info + + Display the build information the Suricata was built with. + +.. option:: --list-app-layer-protos + + List all supported application layer protocols. + +.. option:: --list-keywords=[all|csv|] + + List all supported rule keywords. + +.. option:: --list-runmodes + + List all supported run modes. + +.. Advanced options. + +.. option:: --set = + + Set a configuration value. Useful for overriding basic + configuration parameters in the configuration. For example, to + change the default log directory:: + + --set default-log-dir=/var/tmp + +.. option:: --engine-analysis + + Print reports on analysis of different sections in the engine and + exit. Please have a look at the conf parameter engine-analysis on + what reports can be printed + +.. option:: --unix-socket= + + Use file as the Suricata unix control socket. Overrides the + *filename* provided in the *unix-command* section of the + configuration file. + +.. Advanced input options. + +.. option:: --pcap-buffer-size= + + Set the size of the PCAP buffer (0 - 2147483647). + +.. option:: --netmap[=] + + Enable capture of packet using NETMAP on FreeBSD or Linux. If no + device is supplied, the list of devices from the netmap section + in the yaml is used. + +.. option:: --pfring[=] + + Enable PF_RING packet capture. If no device provided, the devices in + the Suricata configuration will be used. + +.. option:: --pfring-cluster-id + + Set the PF_RING cluster ID. + +.. option:: --pfring-cluster-type + + Set the PF_RING cluster type (cluster_round_robin, cluster_flow). + +.. option:: -d + + Run inline using IPFW divert mode. + +.. option:: --dag + + Enable packet capture off a DAG card. If capturing off a specific + stream the stream can be select using a device name like + "dag0:4". This option may be provided multiple times read off + multiple devices and/or streams. + +.. option:: --napatech + + Enable packet capture using the Napatech Streams API. + +.. option:: --mpipe + + Enable packet capture using the TileGX mpipe interface. + +.. option:: --erf-in= + + Run in offline mode reading the specific ERF file (Endace + extensible record format). + +.. option:: --simulate-ips + + Simulate IPS mode when running in a non-IPS mode.