diff options
Diffstat (limited to 'docs/admin/installation-uwsgi.rst')
| -rw-r--r-- | docs/admin/installation-uwsgi.rst | 206 |
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: + ... |