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 6.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.