git.iko.soy/searx
on master help sign in
docs(admin): add description of the utils/filtron.sh script
39feb14Markus Heiser
docs/admin/filtron.rst+31−3
compare with master
unifiedsplit
@@ -2,12 +2,40 @@
2How to protect an instance
2How to protect an instance
3==========================
3==========================
4
4
5+.. _filtron: https://github.com/asciimoo/filtron
6+
5Searx depens on external search services. To avoid the abuse of these services
7Searx depens on external search services. To avoid the abuse of these services
6it is advised to limit the number of requests processed by searx.
8it is advised to limit the number of requests processed by searx.
7
9
8−An application firewall, ``filtron`` solves exactly this problem. Information
10+An application firewall, filtron_ solves exactly this problem. Filtron is just
9−on how to install it can be found at the `project page of filtron
11+a middleware between your web server (nginx, apache, ...) and searx.
12+
13+
14+filtron & go
15+============
16+
17+.. _Go: https://golang.org/
18+.. _filtron README: https://github.com/asciimoo/filtron/blob/master/README.md
19+
20+Filtron needs Go_ installed. If Go_ is preinstalled, filtron_ is simply
21+installed by ``go get`` package management (see `filtron README`_). If you use
22+filtron as middleware, a more isolated setup is recommended.
23+
24+#. Create a separated user account (``filtron``).
25+#. Download and install Go_ binary in users $HOME (``~filtron``).
26+#. Install filtron with the package management of Go_ (``go get -v -u
10−<https://github.com/asciimoo/filtron>`__.
27+ github.com/asciimoo/filtron``)
28+#. Setup a proper rule configuration :origin:`[ref]
29+ <utils/templates/etc/filtron/rules.json>` (``/etc/filtron/rules.json``).
30+#. Setup a systemd service unit :origin:`[ref]
31+ <utils/templates/lib/systemd/system/filtron.service>`
32+ (``/lib/systemd/system/filtron.service``).
33+
34+To simplify such a installation and the maintenance of; use our script
35+``utils/filtron.sh``:
36+
37+.. program-output:: ../utils/filtron.sh --help
38+ :ellipsis: 0,5
11
39
12
40
13Sample configuration of filtron
41Sample configuration of filtron
utils/filtron.sh+26−22
@@ -45,18 +45,22 @@ usage:
45 $(basename "$0") shell
45 $(basename "$0") shell
46 $(basename "$0") install [all|user]
46 $(basename "$0") install [all|user]
47 $(basename "$0") remove [all]
47 $(basename "$0") remove [all]
48− $(basename "$0") activate [server]
48+ $(basename "$0") activate [service]
49− $(basename "$0") deactivate [server]
49+ $(basename "$0") deactivate [service]
50− $(basename "$0") show [server]
50+ $(basename "$0") show [service]
51
51
52shell
52shell
53 start interactive shell from user ${SERVICE_USER}
53 start interactive shell from user ${SERVICE_USER}
54−show server
55− show server status and log
56−install / remove
54+install / remove all
57− all - complete setup of filtron server
55+ complete setup of filtron service
56+activate
57+ activate and start service daemon (systemd unit)
58+deactivate service
59+ stop and deactivate service daemon (systemd unit)
58install user
60install user
59 add service user '$SERVICE_USER' at $SERVICE_HOME
61 add service user '$SERVICE_USER' at $SERVICE_HOME
62+show service
63+ show service status and log
60EOF
64EOF
61 [ ! -z ${1+x} ] && echo -e "$1"
65 [ ! -z ${1+x} ] && echo -e "$1"
62}
66}
@@ -68,7 +72,7 @@ main(){
68
72
69 case $1 in
73 case $1 in
70 --source-only) ;;
74 --source-only) ;;
71− -h|--help) usage ;;
75+ -h|--help) usage; exit 0;;
72
76
73 shell)
77 shell)
74 sudo_or_exit
78 sudo_or_exit
@@ -76,9 +80,9 @@ main(){
76 ;;
80 ;;
77 show)
81 show)
78 case $2 in
82 case $2 in
79− server)
83+ service)
80 sudo_or_exit
84 sudo_or_exit
81− show_server
85+ show_service
82 ;;
86 ;;
83 *) usage "$_usage"; exit 42;;
87 *) usage "$_usage"; exit 42;;
84 esac ;;
88 esac ;;
@@ -99,13 +103,13 @@ main(){
99 activate)
103 activate)
100 sudo_or_exit
104 sudo_or_exit
101 case $2 in
105 case $2 in
102− server) activate_server ;;
106+ service) activate_service ;;
103 *) usage "$_usage"; exit 42;;
107 *) usage "$_usage"; exit 42;;
104 esac ;;
108 esac ;;
105 deactivate)
109 deactivate)
106 sudo_or_exit
110 sudo_or_exit
107 case $2 in
111 case $2 in
108− server) deactivate_server ;;
112+ service) deactivate_service ;;
109 *) usage "$_usage"; exit 42;;
113 *) usage "$_usage"; exit 42;;
110 esac ;;
114 esac ;;
111 *) usage "ERROR: unknown or missing command $1"; exit 42;;
115 *) usage "ERROR: unknown or missing command $1"; exit 42;;
@@ -120,36 +124,36 @@ install_all() {
120 wait_key
124 wait_key
121 install_filtron
125 install_filtron
122 wait_key
126 wait_key
123− install_server
127+ install_service
124 wait_key
128 wait_key
125}
129}
126
130
127remove_all() {
131remove_all() {
128 rst_title "De-Install $SERVICE_NAME (service)"
132 rst_title "De-Install $SERVICE_NAME (service)"
129− remove_server
133+ remove_service
130 wait_key
134 wait_key
131 remove_user
135 remove_user
132 rm -r "$FILTRON_ETC" 2>&1 | prefix_stdout
136 rm -r "$FILTRON_ETC" 2>&1 | prefix_stdout
133 wait_key
137 wait_key
134}
138}
135
139
136−install_server() {
140+install_service() {
137 rst_title "Install System-D Unit ${SERVICE_NAME}.service" section
141 rst_title "Install System-D Unit ${SERVICE_NAME}.service" section
138 echo
142 echo
139 install_template ${SERVICE_SYSTEMD_UNIT} root root 644
143 install_template ${SERVICE_SYSTEMD_UNIT} root root 644
140 wait_key
144 wait_key
141− activate_server
145+ activate_service
142}
146}
143
147
144−remove_server() {
148+remove_service() {
145 if ! ask_yn "Do you really want to deinstall $SERVICE_NAME?"; then
149 if ! ask_yn "Do you really want to deinstall $SERVICE_NAME?"; then
146 return
150 return
147 fi
151 fi
148− deactivate_server
152+ deactivate_service
149 rm "${SERVICE_SYSTEMD_UNIT}" 2>&1 | prefix_stdout
153 rm "${SERVICE_SYSTEMD_UNIT}" 2>&1 | prefix_stdout
150}
154}
151
155
152−activate_server () {
156+activate_service () {
153 rst_title "Activate $SERVICE_NAME (service)" section
157 rst_title "Activate $SERVICE_NAME (service)" section
154 echo
158 echo
155 tee_stderr <<EOF | bash 2>&1 | prefix_stdout
159 tee_stderr <<EOF | bash 2>&1 | prefix_stdout
@@ -161,7 +165,7 @@ systemctl status $SERVICE_NAME.service
161EOF
165EOF
162}
166}
163
167
164−deactivate_server () {
168+deactivate_service () {
165 rst_title "De-Activate $SERVICE_NAME (service)" section
169 rst_title "De-Activate $SERVICE_NAME (service)" section
166 echo
170 echo
167 tee_stderr <<EOF | bash 2>&1 | prefix_stdout
171 tee_stderr <<EOF | bash 2>&1 | prefix_stdout
@@ -238,8 +242,8 @@ EOF
238 install_template --no-eval "$FILTRON_RULES" root root 644
242 install_template --no-eval "$FILTRON_RULES" root root 644
239}
243}
240
244
241−show_server () {
245+show_service () {
242− rst_title "server status & log"
246+ rst_title "service status & log"
243 echo
247 echo
244 systemctl status filtron.service
248 systemctl status filtron.service
245 echo
249 echo