Adding upstream version 1:7.0.3.upstream/1%7.0.3

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 582 insertions, 0 deletions

diff --git a/doc/userguide/suricata.1 b/doc/userguide/suricata.1
new file mode 100644
index 0000000..f8f3efa
--- /dev/null
+++ b/doc/userguide/suricata.1
@@ -0,0 +1,582 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "SURICATA" "1" "Feb 08, 2024" "7.0.3" "Suricata"
+.SH NAME
+suricata \- Suricata
+.SH SYNOPSIS
+.sp
+\fBsuricata\fP [OPTIONS] [BPF FILTER]
+.SH DESCRIPTION
+.sp
+\fBsuricata\fP is a high performance Network IDS, IPS and Network Security
+Monitoring engine. Open Source and owned by a community run non\-profit
+foundation, the Open Information Security Foundation (OISF).
+.sp
+\fBsuricata\fP can be used to analyze live traffic and pcap files. It can
+generate alerts based on rules. \fBsuricata\fP will generate traffic logs.
+.sp
+When used with live traffic \fBsuricata\fP can be passive or active. Active
+modes are: inline in a L2 bridge setup, inline with L3 integration with
+host firewall (NFQ, IPFW, WinDivert), or out of band using active responses.
+.SH OPTIONS
+.INDENT 0.0
+.TP
+.B \-h
+Display a brief usage overview.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-V
+Displays the version of Suricata.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-c <path>
+Path to configuration file.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-include <path>
+Additional configuration files to include. Multiple additional
+configuration files can be provided and will be included in the
+order specified on the command line.  These additional configuration
+files are loaded as if they existed at the end of the main
+configuration file.
+.sp
+Example including one additional file:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-include /etc/suricata/other.yaml
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Example including more than one additional file:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-include /etc/suricata/other.yaml \-\-include /etc/suricata/extra.yaml
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-T
+Test configuration.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-v
+Increase the verbosity of the Suricata application logging by
+increasing the log level from the default. This option can be
+passed multiple times to further increase the verbosity.
+.INDENT 7.0
+.IP \(bu 2
+\-v: INFO
+.IP \(bu 2
+\-vv: PERF
+.IP \(bu 2
+\-vvv: CONFIG
+.IP \(bu 2
+\-vvvv: DEBUG
+.UNINDENT
+.sp
+This option will not decrease the log level set in the
+configuration file if it is already more verbose than the level
+requested with this option.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-r <path>
+Run in pcap offline mode (replay mode) reading files from pcap file. If
+<path> specifies a directory, all files in that directory will be processed
+in order of modified time maintaining flow state between files.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-pcap\-file\-continuous
+Used with the \-r option to indicate that the mode should stay alive until
+interrupted. This is useful with directories to add new files and not reset
+flow state between files.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-pcap\-file\-recursive
+Used with the \-r option when the path provided is a directory.  This option
+enables recursive traversal into subdirectories to a maximum depth of 255.
+This option cannot be combined with \-\-pcap\-file\-continuous.  Symlinks are
+ignored.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-pcap\-file\-delete
+Used with the \-r option to indicate that the mode should delete pcap files
+after they have been processed. This is useful with pcap\-file\-continuous to
+continuously feed files to a directory and have them cleaned up when done. If
+this option is not set, pcap files will not be deleted after processing.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-i <interface>
+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. Can be used several times to sniff packets from
+several interfaces.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-pcap[=<device>]
+Run in PCAP mode. If no device is provided the interfaces
+provided in the \fIpcap\fP section of the configuration file will be
+used.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-af\-packet[=<device>]
+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.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-af\-xdp[=<device>]
+Enable capture of packet using AF_XDP on Linux. If no device is
+supplied, the list of devices from the af\-xdp section in the
+yaml is used.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-q <queue id>
+Run inline of the NFQUEUE queue ID provided. May be provided
+multiple times.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-s <filename.rules>
+With the \-s option you can set a file with signatures, which will
+be loaded together with the rules set in the yaml.
+.sp
+It is possible to use globbing when specifying rules files.
+For example, \fB\-s \(aq/path/to/rules/*.rules\(aq\fP
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-S <filename.rules>
+With the \-S option you can set a file with signatures, which will
+be loaded exclusively, regardless of the rules set in the yaml.
+.sp
+It is possible to use globbing when specifying rules files.
+For example, \fB\-S \(aq/path/to/rules/*.rules\(aq\fP
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-l <directory>
+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.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-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 daemon
+(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.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-runmode <runmode>
+With the \fI\-\-runmode\fP option you can set the runmode that you would
+like to use. This command line option can override the yaml runmode
+option.
+.sp
+Runmodes are: \fIworkers\fP, \fIautofp\fP and \fIsingle\fP\&.
+.sp
+For more information about runmodes see \fI\%Runmodes\fP in the user guide.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-F <bpf filter file>
+Use BPF filter from file.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-k [all|none]
+Force (all) the checksum check or disable (none) all checksum
+checks.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-user=<user>
+Set the process user after initialization. Overrides the user
+provided in the \fIrun\-as\fP section of the configuration file.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-group=<group>
+Set the process group to group after initialization. Overrides the
+group provided in the \fIrun\-as\fP section of the configuration file.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-pidfile <file>
+Write the process ID to file. Overrides the \fIpid\-file\fP option in
+the configuration file and forces the file to be written when not
+running as a daemon.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-init\-errors\-fatal
+Exit with a failure when errors are encountered loading signatures.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-strict\-rule\-keywords[=all|<keyword>|<keywords(csv)]
+Applies to: classtype, reference and app\-layer\-event.
+.sp
+By default missing reference or classtype values are warnings and
+not errors. Additionally, loading outdated app\-layer\-event events are
+also not treated as errors, but as warnings instead.
+.sp
+If this option is enabled these warnings are considered errors.
+.sp
+If no value, or the value \(aqall\(aq, is specified, the option applies to
+all of the keywords above. Alternatively, a comma separated list can
+be supplied with the keyword names it should apply to.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-disable\-detection
+Disable the detection engine.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-disable\-hashing
+Disable support for hash algorithms such as md5, sha1 and sha256.
+.sp
+By default hashing is enabled. Disabling hashing will also disable some
+Suricata features such as the filestore, ja3, and rule keywords that use hash
+algorithms.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-dump\-config
+Dump the configuration loaded from the configuration file to the
+terminal and exit.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-dump\-features
+Dump the features provided by Suricata modules and exit. Features
+list (a subset of) the configuration values and are intended to
+assist with comparing provided features with those required by
+one or more rules.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-build\-info
+Display the build information the Suricata was built with.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-list\-app\-layer\-protos
+List all supported application layer protocols.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-list\-keywords=[all|csv|<kword>]
+List all supported rule keywords.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-list\-runmodes
+List all supported run modes.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-set <key>=<value>
+Set a configuration value. Useful for overriding basic
+configuration parameters. For example, to change the default log
+directory:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-set default\-log\-dir=/var/tmp
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This option cannot be used to add new entries to a list in the
+configuration file, such as a new output. It can only be used to
+modify a value in a list that already exists.
+.sp
+For example, to disable the \fBeve\-log\fP in the default
+configuration file:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-set outputs.1.eve\-log.enabled=no
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Also note that the index values may change as the \fBsuricata.yaml\fP
+is updated.
+.sp
+See the output of \fB\-\-dump\-config\fP for existing values that could
+be modified with their index.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-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
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-unix\-socket=<file>
+Use file as the Suricata unix control socket. Overrides the
+\fIfilename\fP provided in the \fIunix\-command\fP section of the
+configuration file.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-reject\-dev=<device>
+Use \fIdevice\fP to send out RST / ICMP error packets with
+the \fIreject\fP keyword.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-pcap\-buffer\-size=<size>
+Set the size of the PCAP buffer (0 \- 2147483647).
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-netmap[=<device>]
+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.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-pfring[=<device>]
+Enable PF_RING packet capture. If no device provided, the devices in
+the Suricata configuration will be used.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-pfring\-cluster\-id <id>
+Set the PF_RING cluster ID.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-pfring\-cluster\-type <type>
+Set the PF_RING cluster type (cluster_round_robin, cluster_flow).
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-d <divert\-port>
+Run inline using IPFW divert mode.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-dag <device>
+Enable packet capture off a DAG card. If capturing off a specific
+stream the stream can be select using a device name like
+\(dqdag0:4\(dq. This option may be provided multiple times read off
+multiple devices and/or streams.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-napatech
+Enable packet capture using the Napatech Streams API.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-erf\-in=<file>
+Run in offline mode reading the specific ERF file (Endace
+extensible record format).
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-simulate\-ips
+Simulate IPS mode when running in a non\-IPS mode.
+.UNINDENT
+.SH OPTIONS FOR DEVELOPERS
+.INDENT 0.0
+.TP
+.B \-u
+Run the unit tests and exit. Requires that Suricata be configured
+with \fI\-\-enable\-unittests\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-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
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-list\-unittests
+Lists available unit tests.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-fatal\-unittests
+Enables fatal failure on a unit test error. Suricata will exit
+instead of continuing more tests.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-unittests\-coverage
+Display unit test coverage report.
+.UNINDENT
+.SH SIGNALS
+.sp
+Suricata will respond to the following signals:
+.sp
+SIGUSR2
+.INDENT 0.0
+.INDENT 3.5
+Causes Suricata to perform a live rule reload.
+.UNINDENT
+.UNINDENT
+.sp
+SIGHUP
+.INDENT 0.0
+.INDENT 3.5
+Causes Suricata to close and re\-open all log files. This can be
+used to re\-open log files after they may have been moved away by
+log rotation utilities.
+.UNINDENT
+.UNINDENT
+.SH FILES AND DIRECTORIES
+.INDENT 0.0
+.TP
+.B /usr/local/etc/suricata/suricata.yaml
+Default location of the Suricata configuration file.
+.TP
+.B /usr/local/var/log/suricata
+Default Suricata log directory.
+.UNINDENT
+.SH EXAMPLES
+.sp
+To capture live traffic from interface \fIeno1\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+suricata \-i eno1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+To analyze a pcap file and output logs to the CWD:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+suricata \-r /path/to/capture.pcap
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+To capture using \fIAF_PACKET\fP and override the flow memcap setting from the \fIsuricata.yaml\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+suricata \-\-af\-packet \-\-set flow.memcap=1gb
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+To analyze a pcap file with a custom rule file:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+suricata \-r /pcap/to/capture.pcap \-S /path/to/custom.rules
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH BUGS
+.sp
+Please visit Suricata\(aqs support page for information about submitting
+bugs or feature requests.
+.SH NOTES
+.INDENT 0.0
+.IP \(bu 2
+Suricata Home Page
+.INDENT 2.0
+.INDENT 3.5
+\fI\%https://suricata.io/\fP
+.UNINDENT
+.UNINDENT
+.IP \(bu 2
+Suricata Support Page
+.INDENT 2.0
+.INDENT 3.5
+\fI\%https://suricata.io/support/\fP
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SH COPYRIGHT
+2016-2024, OISF
+.\" Generated by docutils manpage writer.
+.