diff options
Diffstat (limited to 'doc/quickstart.rst')
| -rw-r--r-- | doc/quickstart.rst | 209 |
1 files changed, 209 insertions, 0 deletions
diff --git a/doc/quickstart.rst b/doc/quickstart.rst new file mode 100644 index 0000000..bf57de5 --- /dev/null +++ b/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 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. + |