add some pretty big caveats to the doc

README.rst

@@ -52,14 +52,33 @@ currently provided by ``ipsetd``.
 Managing replicated ipsets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Use the ``ipsetc`` command to manipulate sets. It supports the
-``add``, ``del`` and ``create`` commands, using the same syntax as
-``ipset``.
-
-Note that ``ipsetd`` assumes full control of the ipset you create with
-it: if you perform local changes (perhaps using the ``ipset``
-tool), they will not be replicated and will lead to inconsistencies
-in the cluster.
+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*).