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, 209 insertions, 0 deletions

diff --git a/suricata-update/doc/quickstart.rst b/suricata-update/doc/quickstart.rst
new file mode 100644
index 0000000..012b4e3
--- /dev/null
+++ b/suricata-update/doc/quickstart.rst
@@ -0,0 +1,209 @@
+Quick Start
+###########
+
+Install Suricata Update
+=======================
+
+Suricata-Update is bundled with all supported versions of Suricata and
+should be installed when Suricata is installed. Please check if
+``suricata-update`` is already installed before proceeding with these
+installation directions, for example, the following command will tell
+you the version::
+
+    suricata-update -V
+
+You should only need to install Suricata-Update manually if it is
+required independently of a Suricata install.
+
+Suricata-Update is a tool written in Python and best installed with
+the ``pip`` tool for installing Python packages.
+
+Pip can install ``suricata-update`` globally making it available to
+all users or it can install ``suricata-update`` into your home
+directory.
+
+To install ``suricata-update`` globally::
+
+    pip install --upgrade suricata-update
+
+or to install it to your own directory::
+
+    pip install --user --upgrade suricata-update
+
+Pip can also be used to install the latest development version of
+Suricata-Update::
+
+    pip install --user --upgrade \
+        https://github.com/oisf/suricata-update/archive/master.zip
+
+.. note:: When installing to your home directory the
+          ``suricata-update`` program will be installed to
+          $HOME/.local/bin, so make sure this directory is in your
+          path::
+
+	    export PATH=$HOME/.local/bin:$PATH
+
+Directories and Permissions
+===========================
+
+In order for ``suricata-update`` to function, the following
+permissions are required:
+
+* Directory /etc/suricata: read/write access
+* Directory /var/lib/suricata/rules: read/write access
+* Directory /var/lib/suricata/update: read/write access
+
+One option is to simply run ``suricata-update`` as root or with
+``sudo``.
+
+.. note:: It is recommended to create a ``suricata`` group and setup
+          the above directories with the correct permissions for
+          the ``suricata`` group then add users to the ``suricata``
+          group.
+
+Steps to setup the above directories with the correct permissions:
+
+First, create a group ``suricata``::
+
+    sudo groupadd suricata
+
+Next, change the group of the directories and its files recursively::
+
+    sudo chgrp -R suricata /etc/suricata
+    sudo chgrp -R suricata /var/lib/suricata/rules
+    sudo chgrp -R suricata /var/lib/suricata/update
+
+.. note:: The paths ``/etc/suricata`` and ``/var/lib`` above are used
+          in the default configuration and are dependent on paths set
+          during compilation. By default, these paths are set to
+          ``/usr/local``.
+          Please check your configuration for appropriate paths.
+
+Setup the directories with the correct permissions for the ``suricata``
+group::
+
+    sudo chmod -R g+r /etc/suricata/
+    sudo chmod -R g+rw /var/lib/suricata/rules
+    sudo chmod -R g+rw /var/lib/suricata/update
+
+Now, add user to the group::
+
+    sudo usermod -a -G suricata username
+
+Verify whether group has been changed::
+
+    ls -al /etc/suricata
+    ls -al /var/lib/suricata/rules
+    ls -al /var/lib/suricata/update
+
+Reboot your system. Run ``suricata-update`` without a sudo to check
+if suricata-update functions.
+
+Update Your Rules
+=================
+
+Without doing any configuration the default operation of
+``suricata-update`` is to use the Emerging Threats Open ruleset.
+
+Example::
+
+  suricata-update
+
+This command will:
+
+* Look for the ``suricata`` program on your path to determine its
+  version.
+
+* Look for /etc/suricata/enable.conf, /etc/suricata/disable.conf,
+  /etc/suricata/drop.conf, and /etc/suricata/modify.conf to look for
+  filters to apply to the downloaded rules. These files are optional
+  and do not need to exist.
+
+* Download the Emerging Threats Open ruleset for your version of
+  Suricata, defaulting to 4.0.0 if not found.
+
+* Apply enable, disable, drop and modify filters as loaded above.
+
+* Write out the rules to ``/var/lib/suricata/rules/suricata.rules``.
+
+* Run Suricata in test mode on
+  ``/var/lib/suricata/rules/suricata.rules``.
+
+.. note:: Suricata-Update is also capable of triggering a rule reload,
+          but doing so requires some extra configuration that will be
+          covered later. See the documentation of
+          :command:`--reload-command=<command>` for more details.
+
+Configure Suricata to Load Suricata-Update Managed Rules
+========================================================
+
+.. note:: If ``suricata-update`` was installed for you by Suricata,
+          then your Suricata configuration should already be setup to
+          work with Suricata-Update.
+
+If upgrading from an older version of Suricata, or running a
+development version that may not be bundled with Suricata-Update, you
+will have to check that your ``suricata.yaml`` is configured for
+Suricata-Update. The main difference is the ``default-rule-path``
+which is ``/var/lib/suricata/rules`` when using Suricata-Update.
+
+You will want to update your ``suricata.yaml`` to have the following::
+
+  default-rule-path: /var/lib/suricata/rules
+  rule-files:
+    - suricata.rules
+
+If you have local rules you would like Suricata to load, these can be
+listed here as well by using the full path name.
+
+Discover Other Available Rule Sources
+=====================================
+
+First update the rule source index with the ``update-sources`` command,
+for example::
+
+  suricata-update update-sources
+
+Then list the sources from the index. Example::
+
+  suricata-update list-sources
+
+Now enable the **ptresearch/attackdetection** ruleset::
+
+  suricata-update enable-source ptresearch/attackdetection
+
+And update your rules again::
+
+  suricata-update
+
+List Enabled Sources
+====================
+
+::
+
+   suricata-update list-sources --enabled
+
+Disable a Source
+================
+
+::
+
+   suricata-update disable-source et/pro
+
+Disabling a source keeps the source configuration but disables. This
+is useful when a source requires parameters such as a code that you
+don't want to lose, which would happen if you removed a source.
+
+Enabling a disabled source re-enables without prompting for user
+inputs.
+
+Remove a Source
+===============
+
+::
+
+   suricata-update remove-source et/pro
+
+This removes the local configuration for this source. Re-enabling
+**et/pro** will requiring re-entering your access code.
+