[doc] update documentation of the installation procedures

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>

1 files changed, 162 insertions, 44 deletions

diff --git a/docs/admin/installation-uwsgi.rst b/docs/admin/installation-uwsgi.rst
index 1021283f9..eea52ab3e 100644
--- a/docs/admin/installation-uwsgi.rst
+++ b/docs/admin/installation-uwsgi.rst
@@ -1,7 +1,7 @@
 .. _searxng uwsgi:
 
 =====
-uwsgi
+uWSGI
 =====
 
 .. sidebar:: further reading
@@ -29,37 +29,51 @@ uwsgi
 Origin uWSGI
 ============
 
-How uWSGI is implemented by distributors is different.  uWSGI itself
-recommend two methods
+.. _Tyrant mode:
+   https://uwsgi-docs.readthedocs.io/en/latest/Emperor.html#tyrant-mode-secure-multi-user-hosting
 
-`systemd.unit`_ template files as described here `One service per app in systemd`_.
+How uWSGI is implemented by distributors varies. The uWSGI project itself
+recommends two methods:
 
-  There is one `systemd unit template`_ and one `uwsgi ini file`_ per uWSGI-app
-  placed at dedicated locations.  Take archlinux and a searxng.ini as example::
+1. `systemd.unit`_ template file as described here `One service per app in systemd`_:
 
-    unit template    -->  /usr/lib/systemd/system/uwsgi@.service
-    uwsgi ini files  -->  /etc/uwsgi/searxng.ini
+  There is one `systemd unit template`_ on the system installed and one `uwsgi
+  ini file`_ per uWSGI-app placed at dedicated locations.  Take archlinux and a
+  ``searxng.ini`` as example::
 
-  The SearXNG app can be maintained as know from common systemd units::
+    systemd template unit: /usr/lib/systemd/system/uwsgi@.service
+            contains: [Service]
+                      ExecStart=/usr/bin/uwsgi --ini /etc/uwsgi/%I.ini
 
-    systemctl enable  uwsgi@searx
-    systemctl start   uwsgi@searx
-    systemctl restart uwsgi@searx
-    systemctl stop    uwsgi@searx
+    SearXNG application:   /etc/uwsgi/searxng.ini
+            links to: /etc/uwsgi/apps-available/searxng.ini
 
-The `uWSGI Emperor`_ mode which fits for maintaining a large range of uwsgi apps.
+  The SearXNG app (template ``/etc/uwsgi/%I.ini``) can be maintained as known
+  from common systemd units:
+
+  .. code:: sh
+
+     $ systemctl enable  uwsgi@searxng
+     $ systemctl start   uwsgi@searxng
+     $ systemctl restart uwsgi@searxng
+     $ systemctl stop    uwsgi@searxng
+
+2. The `uWSGI Emperor`_ which fits for maintaining a large range of uwsgi
+   apps and there is a `Tyrant mode`_ to secure multi-user hosting.
 
   The Emperor mode is a special uWSGI instance that will monitor specific
-  events.  The Emperor mode (service) is started by a (common, not template)
-  systemd unit.  The Emperor service will scan specific directories for `uwsgi
-  ini file`_\s (also know as *vassals*).  If a *vassal* is added, removed or the
-  timestamp is modified, a corresponding action takes place: a new uWSGI
-  instance is started, reload or stopped.  Take Fedora and a searxng.ini as
-  example::
+  events.  The Emperor mode (the service) is started by a (common, not template)
+  systemd unit.
+
+  The Emperor service will scan specific directories for `uwsgi ini file`_\s
+  (also know as *vassals*).  If a *vassal* is added, removed or the timestamp is
+  modified, a corresponding action takes place: a new uWSGI instance is started,
+  reload or stopped.  Take Fedora and a ``searxng.ini`` as example::
+
+    to install & start SearXNG instance create --> /etc/uwsgi.d/searxng.ini
+    to reload the instance edit timestamp      --> touch /etc/uwsgi.d/searxng.ini
+    to stop instance remove ini                --> rm /etc/uwsgi.d/searxng.ini
 
-    to start a new SearXNG instance create --> /etc/uwsgi.d/searxng.ini
-    to reload the instance edit timestamp  --> touch /etc/uwsgi.d/searxng.ini
-    to stop instance remove ini            --> rm /etc/uwsgi.d/searxng.ini
 
 Distributors
 ============
@@ -70,10 +84,22 @@ modes and their defaults.  Another point they might differ is the packaging of
 plugins (if so, compare :ref:`install packages`) and what the default python
 interpreter is (python2 vs. python3).
 
-Fedora starts a Emperor by default, while archlinux does not start any uwsgi
-service by default.  Worth to know; debian (ubuntu) follow a complete different
-approach.  *debian*: your are familiar with the apache infrastructure? .. they
-do similar for the uWSGI infrastructure (with less comfort), the folders are::
+While archlinux does not start a uWSGI service by default, Fedora (RHEL) starts
+a Emperor in `Tyrant mode`_ by default (you should have read :ref:`uWSGI Tyrant
+mode pitfalls`).  Worth to know; debian (ubuntu) follow a complete different
+approach, read see :ref:`Debian's uWSGI layout`.
+
+.. _Debian's uWSGI layout:
+
+Debian's uWSGI layout
+---------------------
+
+.. _uwsgi.README.Debian:
+    https://salsa.debian.org/uwsgi-team/uwsgi/-/raw/debian/latest/debian/uwsgi.README.Debian
+
+Be aware, Debian's uWSGI layout is quite different from the standard uWSGI
+configuration.  Your are familiar with :ref:`Debian's Apache layout`? .. they do
+similar for the uWSGI infrastructure. The folders are::
 
     /etc/uwsgi/apps-available/
     /etc/uwsgi/apps-enabled/
@@ -82,29 +108,52 @@ The `uwsgi ini file`_ is enabled by a symbolic link::
 
   ln -s /etc/uwsgi/apps-available/searxng.ini /etc/uwsgi/apps-enabled/
 
-From debian's documentation (``/usr/share/doc/uwsgi/README.Debian.gz``): You
-could control specific instance(s) by issuing::
+More details you will find in the uwsgi.README.Debian_
+(``/usr/share/doc/uwsgi/README.Debian.gz``).  Some commands you should know on
+Debian:
 
-  service uwsgi <command> <confname> <confname> ...
+.. code:: none
 
-  sudo -H service uwsgi start searx
-  sudo -H service uwsgi stop  searx
+    Commands recognized by init.d script
+    ====================================
 
-My experience is, that this command is a bit buggy.
+    You can issue to init.d script following commands:
+      * start        | starts daemon
+      * stop         | stops daemon
+      * reload       | sends to daemon SIGHUP signal
+      * force-reload | sends to daemon SIGTERM signal
+      * restart      | issues 'stop', then 'start' commands
+      * status       | shows status of daemon instance (running/not running)
 
-.. _uwsgi configuration:
+    'status' command must be issued with exactly one argument: '<confname>'.
 
-Alltogether
-===========
+    Controlling specific instances of uWSGI
+    =======================================
 
-Create the configuration ini-file according to your distribution (see below) and
-restart the uwsgi application.
+    You could control specific instance(s) by issuing:
+
+        SYSTEMCTL_SKIP_REDIRECT=1 service uwsgi <command> <confname> <confname>...
+
+    where:
+      * <command> is one of 'start', 'stop' etc.
+      * <confname> is the name of configuration file (without extension)
+
+    For example, this is how instance for /etc/uwsgi/apps-enabled/hello.xml is
+    started:
+
+        SYSTEMCTL_SKIP_REDIRECT=1 service uwsgi start hello
+
+
+.. _uWSGI maintenance:
+
+uWSGI maintenance
+=================
 
 .. tabs::
 
    .. group-tab:: Ubuntu / debian
 
-      .. kernel-include:: $DOCS_BUILD/includes/searx.rst
+      .. kernel-include:: $DOCS_BUILD/includes/searxng.rst
          :start-after: START searxng uwsgi-description ubuntu-20.04
          :end-before: END searxng uwsgi-description ubuntu-20.04
 
@@ -112,7 +161,7 @@ restart the uwsgi application.
 
    .. group-tab:: Arch Linux
 
-      .. kernel-include:: $DOCS_BUILD/includes/searx.rst
+      .. kernel-include:: $DOCS_BUILD/includes/searxng.rst
          :start-after: START searxng uwsgi-description arch
          :end-before: END searxng uwsgi-description arch
 
@@ -120,16 +169,28 @@ restart the uwsgi application.
 
    .. group-tab::  Fedora / RHEL
 
-      .. kernel-include:: $DOCS_BUILD/includes/searx.rst
+      .. kernel-include:: $DOCS_BUILD/includes/searxng.rst
          :start-after: START searxng uwsgi-description fedora
          :end-before: END searxng uwsgi-description fedora
 
 
+.. _uwsgi setup:
+
+uWSGI setup
+===========
+
+Create the configuration ini-file according to your distribution and restart the
+uwsgi application.  As shown below, the :ref:`installation scripts` installs by
+default:
+
+- a uWSGI setup that listens on a socket and
+- enables :ref:`cache busting <static_use_hash>`.
+
 .. tabs::
 
    .. group-tab:: Ubuntu / debian
 
-      .. kernel-include:: $DOCS_BUILD/includes/searx.rst
+      .. kernel-include:: $DOCS_BUILD/includes/searxng.rst
          :start-after: START searxng uwsgi-appini ubuntu-20.04
          :end-before: END searxng uwsgi-appini ubuntu-20.04
 
@@ -137,7 +198,7 @@ restart the uwsgi application.
 
    .. group-tab:: Arch Linux
 
-      .. kernel-include:: $DOCS_BUILD/includes/searx.rst
+      .. kernel-include:: $DOCS_BUILD/includes/searxng.rst
          :start-after: START searxng uwsgi-appini arch
          :end-before: END searxng uwsgi-appini arch
 
@@ -145,6 +206,63 @@ restart the uwsgi application.
 
    .. group-tab::  Fedora / RHEL
 
-      .. kernel-include:: $DOCS_BUILD/includes/searx.rst
+      .. kernel-include:: $DOCS_BUILD/includes/searxng.rst
          :start-after: START searxng uwsgi-appini fedora
          :end-before: END searxng uwsgi-appini fedora
+
+
+.. _uWSGI Tyrant mode pitfalls:
+
+Pitfalls of the Tyrant mode
+===========================
+
+The implementation of the process owners and groups in the `Tyrant mode`_ is
+somewhat unusual and requires special consideration.  In `Tyrant mode`_ mode the
+Emperor will run the vassal using the UID/GID of the vassal configuration file
+(user and group of the app ``.ini`` file).
+
+.. _#2099@uWSGI: https://github.com/unbit/uwsgi/issues/2099
+.. _#752@uWSGI: https://github.com/unbit/uwsgi/pull/752
+.. _#2425uWSGI: https://github.com/unbit/uwsgi/issues/2425
+
+Without option ``emperor-tyrant-initgroups=true`` in ``/etc/uwsgi.ini`` the
+process won't get the additional groups, but this option is not available in
+2.0.x branch (see `#2099@uWSGI`_) the feature `#752@uWSGI`_ has been merged (on
+Oct. 2014) to the master branch of uWSGI but had never been released; the last
+major release is from Dec. 2013, since the there had been only bugfix releases
+(see `#2425uWSGI`_). To shorten up:
+
+  **In Tyrant mode, there is no way to get additional groups, and the uWSGI
+  process misses additional permissions that may be needed.**
+
+By example, on Fedora (RHEL): If you try to install a redis DB with socket
+communication and you want to connect from the SearXNG uWSGI, you will see a
+*Permission denied* in the log of your instance::
+
+  ERROR:searx.shared.redis: [searxng (993)] can't connect redis DB ...
+  ERROR:searx.shared.redis:   Error 13 connecting to unix socket: /usr/local/searxng-redis/run/redis.sock. Permission denied.
+  ERROR:searx.plugins.limiter: init limiter DB failed!!!
+
+Even if your *searxng* user of the uWSGI process is added to additional groups
+to give access to the socket from the redis DB::
+
+  $ groups searxng
+  searxng : searxng searxng-redis
+
+To see the effective groups of the uwsgi process, you have to look at the status
+of the process, by example::
+
+  $ ps -aef | grep '/usr/sbin/uwsgi --ini searxng.ini'
+  searxng       93      92  0 12:43 ?        00:00:00 /usr/sbin/uwsgi --ini searxng.ini
+  searxng      186      93  0 12:44 ?        00:00:01 /usr/sbin/uwsgi --ini searxng.ini
+
+Here you can see that the additional "Groups" of PID 186 are unset (missing gid
+of ``searxng-redis``)::
+
+  $ cat /proc/186/task/186/status
+  ...
+  Uid:      993     993     993     993
+  Gid:      993     993     993     993
+  FDSize:   128
+  Groups:
+  ...