IPTipset: Added documentation

Signed-off-by: David Sommerseth <davids@redhat.com>

1 files changed, 103 insertions, 0 deletions

diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
index 6353142..d107399 100644
--- a/docs/source/configuration.rst
+++ b/docs/source/configuration.rst
@@ -54,6 +54,12 @@ reporter called *Default* will be used.
    e-mail recipients.  Support for SSL and STARTTLS in addition to SMTP-AUTH
    are availble as well.
 
+* :ref:`lnk-IPTipset`
+
+   This "reporter" can add extracted IP addresses from a log file and add
+   it to an ipset table.  This table can be used by iptables to for example
+   block access.
+
 * :ref:`lnk-qpidreporter`
 
    This reporter will send the extracted log data to an
@@ -193,6 +199,103 @@ is also prefixed differently.
 
 
 .. index::
+   pair: Configuration; IPTipset
+.. _lnk-IPTipset:
+
+IPTipset
+--------
+To use this module, you need ipset and iptables installed and available.  This
+will also require logactio to run with root privileges, otherwise it lacks
+privileges to update the ipset and iptables rules.
+
+.. IMPORTANT::
+   This module expects only a single regex group to be extracted.  This value
+   **has** to be an IP address, otherwise the IPTipset module will fail when
+   executing the ipset command.
+
+The required configuration variables are:
+
+* ipset-name
+  This is the name of the ipset table to this specific section will use.
+
+Optional settings are:
+
+* ipset-create
+
+  Boolean variable which tells wether the IPTipset module should create
+  the ipset table when starting or not.  The values of "true" (case
+  or "1" will be understood as True, all other values as False.
+
+* ipset-hashsize, ipset-timeout, ipset-counters
+
+  These variables will be sent further to the 'ipset create' command and will
+  set hashsize, timeout and the counters flag.  ipset-counters is a boolean
+  flag, where the value of "true" (case insensitive) or "1" will be understood
+  as True, all other values as False.  The default value for ipset-hashsize
+  is 1024, ipset-timeout is not defined and ipset-counters is False by default.
+
+* ipset-save
+
+  This will enable the IPTipset module to save the state of the ipset table
+  when exiting.  If this file exists when LogActio is started again later on,
+  this state will be loaded automatically.
+
+* iptables-chains
+
+  If set, LogActio will insert the ipset checks into the listed iptables
+  chains.  Multiple chains can be listed, separated by comma.
+
+* iptables-insert-points
+
+  This is optional but only available if iptables-chains are used.   This
+  defines where in the different iptables chains the ipset rules will be
+  inserted.  By default it will be inserted at the top of the chain.  The
+  syntax is CHAIN:NUM, where CHAIN is the name provided in *iptables-chains*
+  and NUM is the value used when calling iptables.  The result is something
+  like 'iptables -I CHAIN NUM ...'.  Multiple chains can be defined,
+  separated by comma.
+
+* iptables-jump
+
+  This is required when using *iptables-chains*.  This defines what to do
+  when iptables get a positive match against the ipset table.  This sets the
+  '-j' options when iptables commands are executed.
+
+.. index::
+   pair: Examples; IPTipset
+
+IPTipset example
+~~~~~~~~~~~~~~~~
+
+.. code-block :: ini
+
+    [Reporter:ipsetblock]
+    module: IPTipset
+    ipset-name: BlockList
+    ipset-create: True
+    ipset-hashsize: 2048
+    ipset-timeout: 3600
+    ipset-counters: False
+    ipset-save: /var/lib/ipset/logactio-ipset.save
+    iptables-chains: INPUT,OUTPUT,FORWARD
+    iptables-insert-points: INPUT:2,FORWARD:4
+    iptables-jump: DROP
+
+This will configure a reported named ipsetblock.  Whenever this reporter
+is called, it will add an IP address to an ipset table named 'Blocklist'.
+This list will be created when LogActio starts, with a hashsize of 2048
+and a timeout of 1 hour (3600 seconds).  The ipset table state will be
+saved to /var/lib/ipset/logactio-ipset.save.  When starting LogActio
+the following commands will be run:
+
+.. code-block :: shell
+
+    # ipset --exist create BlockList hash:ipset hashsize 2048 timeout 3600
+    # iptables -I INPUT 2 -m set --match-set BlockList src -j DROP
+    # iptables -I OUTPUT -m set --match-set BlockList src -j DROP
+    # iptables -I FORWARD 4 -m set --match-set BlockList src -j DROP
+
+.. index::
    pair: Configuration; QpidReporter
 .. _lnk-qpidreporter: