From 37493b0a1ea8bfede427e4d68c2a17dfdb8a6078 Mon Sep 17 00:00:00 2001
From: Markus Heiser <markus.heiser@darmarit.de>
Date: Fri, 25 Mar 2022 10:23:15 +0100
Subject: [PATCH] [doc] add some documentation about the limiter plugin (and
 redis)

Requested-by: https://github.com/searxng/searxng/discussions/993#discussioncomment-2396914
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
---
 docs/admin/engines/settings.rst    | 25 ++++++++++++++++++++-----
 docs/admin/filtron.rst             | 14 ++++++++------
 docs/src/searx.plugins.limiter.rst |  4 ++++
 searx/plugins/limiter.py           |  4 ++++
 4 files changed, 36 insertions(+), 11 deletions(-)

diff --git a/docs/admin/engines/settings.rst b/docs/admin/engines/settings.rst
index a55e2575b..2726674d5 100644
--- a/docs/admin/engines/settings.rst
+++ b/docs/admin/engines/settings.rst
@@ -226,6 +226,17 @@ Global Settings
 
 .. _Redis.from_url(url): https://redis-py.readthedocs.io/en/stable/connections.html#redis.client.Redis.from_url
 
+A redis DB can be connected by an URL, in :py:obj:`searx.shared.redisdb` you
+will find a description to test your redis connection in SerXNG.  When using
+sockets, don't forget to check the access rights on the socket::
+
+  ls -la /usr/local/searxng-redis/run/redis.sock
+  srwxrwx--- 1 searxng-redis searxng-redis ... /usr/local/searxng-redis/run/redis.sock
+
+In this example read/write access is given to the *searxng-redis* group.  To get
+access rights to redis instance (the socket), your SearXNG (or even your
+developer) account needs to be added to the *searxng-redis* group.
+
 ``url``
   URL to connect redis database, see `Redis.from_url(url)`_ & :ref:`redis db`::
 
@@ -235,17 +246,21 @@ Global Settings
 
 .. admonition:: Tip for developers
 
-   To set up a redis instance simply use::
+   To set up a local redis instance using sockets simply use::
 
      $ ./manage redis.build
      $ sudo -H ./manage redis.install
-
-   To get access rights to this instance, your developer account needs to be
-   added to the *searxng-redis* group::
-
      $ sudo -H ./manage redis.addgrp "${USER}"
      # don't forget to logout & login to get member of group
 
+   The YAML setting for such a redis instance is:
+
+   .. code:: yaml
+
+      redis:
+        url: unix:///usr/local/searxng-redis/run/redis.sock?db=0
+
+
 .. _settings outgoing:
 
 ``outgoing:``
diff --git a/docs/admin/filtron.rst b/docs/admin/filtron.rst
index f08149ae9..60d7cbeba 100644
--- a/docs/admin/filtron.rst
+++ b/docs/admin/filtron.rst
@@ -5,17 +5,19 @@
 How to protect an instance
 ==========================
 
+.. tip::
+
+   To protect your instance a installation of filtron (as described here) is no
+   longer needed, alternatively activate the :ref:`limiter plugin` in your
+   ``settings.yml``. Note that the :ref:`limiter plugin` requires a :ref:`Redis
+   <settings redis>` database.
+
+
 .. sidebar:: further reading
 
    - :ref:`filtron.sh`
    - :ref:`nginx searxng site`
 
-
-.. contents:: Contents
-   :depth: 2
-   :local:
-   :backlinks: entry
-
 .. _filtron: https://github.com/searxng/filtron
 
 SearXNG depends on external search services.  To avoid the abuse of these services
diff --git a/docs/src/searx.plugins.limiter.rst b/docs/src/searx.plugins.limiter.rst
index 4984cd37a..75d06f5c2 100644
--- a/docs/src/searx.plugins.limiter.rst
+++ b/docs/src/searx.plugins.limiter.rst
@@ -4,6 +4,10 @@
 Limiter Plugin
 ==============
 
+.. sidebar:: info
+
+   The :ref:`limiter plugin` requires a :ref:`Redis <settings redis>` database.
+
 .. automodule:: searx.plugins.limiter
   :members:
 
diff --git a/searx/plugins/limiter.py b/searx/plugins/limiter.py
index 6accf2c1c..c3ec64283 100644
--- a/searx/plugins/limiter.py
+++ b/searx/plugins/limiter.py
@@ -3,6 +3,10 @@
 # pyright: basic
 """Some bot protection / rate limitation
 
+To monitore rate limits and protect privacy the IP addresses are getting stored
+with a hash so the limiter plugin knows who to block.  A redis database is
+needed to store the hash values.
+
 Enable the plugin in ``settings.yml``:
 
 - ``server.limiter: true``