README.rst 2.48 KB
Newer Older
ale's avatar
ale committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
++++++
ipsetd
++++++


``ipsetd`` maintains a consistent ipset_ across multiple servers. It
uses the RAFT_ protocol to replicate set membership between the
cluster nodes.

It can be useful to maintain responsive distributed blacklists, or
for automated anti-DDOS mechanisms.


Building
--------

Once you have your ``GOPATH`` set up, check out the source code in the
appropriate directory (in this case,
``$GOPATH/src/git.autistici.org/ale/ipsetd``) and build the
command-line programs::

    $ go get ./...
    $ go build ipsetd.go
24
    $ go build client/ipsetc/ipsetc.go
ale's avatar
ale committed
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54

Install the binaries (``ipsetc`` and ``ipsetd``) somewhere you can
find them.


Usage
-----

Running the daemon
~~~~~~~~~~~~~~~~~~

Start the ``ipsetd`` daemon on each cluster node. To bootstrap the
cluster:

1. pick a machine and run ``ipsetd`` without the ``--peer`` option
2. on all other machines, start ``ipsetd`` once with the ``--peer``
   option pointing at the first machine

Once the cluster has been bootstrapped, there is no need to use the
``--peer`` option on further invocations, as the cluster membership is
encoded in the RAFT log.

You might want to limit access to the TCP port used by the daemon
(1313 is the default) using iptables, as no authentication is
currently provided by ``ipsetd``.


Managing replicated ipsets
~~~~~~~~~~~~~~~~~~~~~~~~~~

ale's avatar
ale committed
55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81
Use the ``ipsetc`` command to manipulate sets, as you would use the
standard ``ipset`` tool. The *add*, *del* and *create* commands are
supported, using a syntax similar to that of ``ipset``. For example::

    $ ipsetc --create blacklist hash:ip
    $ ipsetc --add blacklist 82.94.249.234

will create and populates an IP-based hash set called *blacklist*.


Caveats and TODOs
~~~~~~~~~~~~~~~~~

Note that ``ipsetd`` expects full control over the ipset that it
manages: if you perform local changes (perhaps using the standard
``ipset`` tool), they will not be replicated and will lead to
inconsistencies in the cluster.

Note also that, due to the log-based nature of the underlying RAFT
protocol, commands are not executed synchronously with requests, so
there is no way to retrieve or display their output or exit status.
This means that you should make sure that the ipset commands are
syntactically correct before invoking ``ipsetc``, or they will
silently fail when applied by the individual nodes in the cluster.

There is currently no way to remove nodes from the cluster (must
implement *LeaveCommand*).
ale's avatar
ale committed
82 83 84 85 86 87 88



.. _ipset: http://ipset.netfilter.org/
.. _RAFT: https://github.com/goraft/raft