From 39feb141bc8361915b3d80a976852b38851e0419 Mon Sep 17 00:00:00 2001
From: Markus Heiser <markus.heiser@darmarit.de>
Date: Sat, 11 Jan 2020 12:50:40 +0100
Subject: [PATCH] docs(admin): add description of the utils/filtron.sh script

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
---
 docs/admin/filtron.rst | 34 +++++++++++++++++++++++++++---
 utils/filtron.sh       | 48 +++++++++++++++++++++++-------------------
 2 files changed, 57 insertions(+), 25 deletions(-)

diff --git a/docs/admin/filtron.rst b/docs/admin/filtron.rst
index 07dcb9bc5..009ca1c29 100644
--- a/docs/admin/filtron.rst
+++ b/docs/admin/filtron.rst
@@ -2,12 +2,40 @@
 How to protect an instance
 ==========================
 
+.. _filtron: https://github.com/asciimoo/filtron
+
 Searx depens on external search services.  To avoid the abuse of these services
 it is advised to limit the number of requests processed by searx.
 
-An application firewall, ``filtron`` solves exactly this problem.  Information
-on how to install it can be found at the `project page of filtron
-<https://github.com/asciimoo/filtron>`__.
+An application firewall, filtron_ solves exactly this problem.  Filtron is just
+a middleware between your web server (nginx, apache, ...) and searx.
+
+
+filtron & go
+============
+
+.. _Go: https://golang.org/
+.. _filtron README: https://github.com/asciimoo/filtron/blob/master/README.md
+
+Filtron needs Go_ installed.  If Go_ is preinstalled, filtron_ is simply
+installed by ``go get`` package management (see `filtron README`_).  If you use
+filtron as middleware, a more isolated setup is recommended.
+
+#. Create a separated user account (``filtron``).
+#. Download and install Go_ binary in users $HOME (``~filtron``).
+#. Install filtron with the package management of Go_ (``go get -v -u
+   github.com/asciimoo/filtron``)
+#. Setup a proper rule configuration :origin:`[ref]
+   <utils/templates/etc/filtron/rules.json>` (``/etc/filtron/rules.json``).
+#. Setup a systemd service unit :origin:`[ref]
+   <utils/templates/lib/systemd/system/filtron.service>`
+   (``/lib/systemd/system/filtron.service``).
+
+To simplify such a installation and the maintenance of; use our script
+``utils/filtron.sh``:
+
+.. program-output:: ../utils/filtron.sh --help
+   :ellipsis: 0,5
 
 
 Sample configuration of filtron
diff --git a/utils/filtron.sh b/utils/filtron.sh
index 593c0fcf7..597d0c634 100755
--- a/utils/filtron.sh
+++ b/utils/filtron.sh
@@ -45,18 +45,22 @@ usage:
   $(basename "$0") shell
   $(basename "$0") install    [all|user]
   $(basename "$0") remove     [all]
-  $(basename "$0") activate   [server]
-  $(basename "$0") deactivate [server]
-  $(basename "$0") show       [server]
+  $(basename "$0") activate   [service]
+  $(basename "$0") deactivate [service]
+  $(basename "$0") show       [service]
 
 shell
   start interactive shell from user ${SERVICE_USER}
-show server
-  show server status and log
-install / remove
-  all  - complete setup of filtron server
+install / remove all 
+  complete setup of filtron service
+activate
+  activate and start service daemon (systemd unit)
+deactivate service
+  stop and deactivate service daemon (systemd unit)
 install user
   add service user '$SERVICE_USER' at $SERVICE_HOME
+show service
+  show service status and log
 EOF
     [ ! -z ${1+x} ] &&  echo -e "$1"
 }
@@ -68,7 +72,7 @@ main(){
 
     case $1 in
 	--source-only)  ;;
-        -h|--help) usage ;;
+        -h|--help) usage; exit 0;;
 
 	shell)
 	    sudo_or_exit
@@ -76,9 +80,9 @@ main(){
 	    ;;
         show)
             case $2 in
-                server)
+                service)
 		    sudo_or_exit
-		    show_server
+		    show_service
 		    ;;
                 *) usage "$_usage"; exit 42;;
             esac ;;
@@ -99,13 +103,13 @@ main(){
         activate)
             sudo_or_exit
             case $2 in
-                server)  activate_server ;;
+                service)  activate_service ;;
                 *) usage "$_usage"; exit 42;;
             esac ;;
         deactivate)
             sudo_or_exit
             case $2 in
-                server)  deactivate_server ;;
+                service)  deactivate_service ;;
                 *) usage "$_usage"; exit 42;;
             esac ;;
         *) usage "ERROR: unknown or missing command $1"; exit 42;;
@@ -120,36 +124,36 @@ install_all() {
     wait_key
     install_filtron
     wait_key
-    install_server
+    install_service
     wait_key
 }
 
 remove_all() {
     rst_title "De-Install $SERVICE_NAME (service)"
-    remove_server
+    remove_service
     wait_key
     remove_user
     rm -r "$FILTRON_ETC" 2>&1 | prefix_stdout
     wait_key
 }
 
-install_server() {
+install_service() {
     rst_title "Install System-D Unit ${SERVICE_NAME}.service" section
     echo
     install_template ${SERVICE_SYSTEMD_UNIT} root root 644
     wait_key
-    activate_server
+    activate_service
 }
 
-remove_server() {
+remove_service() {
     if ! ask_yn "Do you really want to deinstall $SERVICE_NAME?"; then
         return
     fi
-    deactivate_server
+    deactivate_service
     rm "${SERVICE_SYSTEMD_UNIT}"  2>&1 | prefix_stdout
 }
 
-activate_server () {
+activate_service () {
     rst_title "Activate $SERVICE_NAME (service)" section
     echo
     tee_stderr <<EOF | bash 2>&1 | prefix_stdout
@@ -161,7 +165,7 @@ systemctl status $SERVICE_NAME.service
 EOF
 }
 
-deactivate_server () {
+deactivate_service () {
     rst_title "De-Activate $SERVICE_NAME (service)" section
     echo
     tee_stderr <<EOF | bash 2>&1 | prefix_stdout
@@ -238,8 +242,8 @@ EOF
     install_template --no-eval "$FILTRON_RULES" root root 644
 }
 
-show_server () {
-    rst_title "server status & log"
+show_service () {
+    rst_title "service status & log"
     echo
     systemctl status filtron.service
     echo