mirror of https://github.com/searxng/searxng
doc: proofread of the all reST sources (no content change)
Normalize reST sources with best practice and KISS in mind. to name a few points: - simplify reST tables - make use of ``literal`` markup for monospace rendering - fix code-blocks for better rendering in HTML - normalize section header markup - limit all lines to a maximum of 79 characters - add option -H to the sudo command used in code blocks - drop useless indentation of lists - ... [1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>pull/1/head
parent
0011890043
commit
e9fff4fde6
@ -1,94 +1,96 @@
|
||||
.. _adminapi:
|
||||
|
||||
==================
|
||||
Administration API
|
||||
------------------
|
||||
==================
|
||||
|
||||
Get configuration data
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
======================
|
||||
|
||||
.. code:: sh
|
||||
.. code:: http
|
||||
|
||||
GET /config
|
||||
GET /config HTTP/1.1
|
||||
|
||||
Sample response
|
||||
```````````````
|
||||
---------------
|
||||
|
||||
.. code:: json
|
||||
|
||||
{
|
||||
"autocomplete": "",
|
||||
"categories": [
|
||||
"map",
|
||||
"it",
|
||||
"images",
|
||||
],
|
||||
"default_locale": "",
|
||||
"default_theme": "oscar",
|
||||
"engines": [
|
||||
{
|
||||
"categories": [
|
||||
"map"
|
||||
],
|
||||
"enabled": true,
|
||||
"name": "openstreetmap",
|
||||
"shortcut": "osm"
|
||||
},
|
||||
{
|
||||
"categories": [
|
||||
"it"
|
||||
],
|
||||
"enabled": true,
|
||||
"name": "arch linux wiki",
|
||||
"shortcut": "al"
|
||||
},
|
||||
{
|
||||
"categories": [
|
||||
"images"
|
||||
],
|
||||
"enabled": true,
|
||||
"name": "google images",
|
||||
"shortcut": "goi"
|
||||
},
|
||||
{
|
||||
"categories": [
|
||||
"it"
|
||||
],
|
||||
"enabled": false,
|
||||
"name": "bitbucket",
|
||||
"shortcut": "bb"
|
||||
},
|
||||
],
|
||||
"instance_name": "searx",
|
||||
"locales": {
|
||||
"de": "Deutsch (German)",
|
||||
"en": "English",
|
||||
"eo": "Esperanto (Esperanto)",
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"enabled": true,
|
||||
"name": "HTTPS rewrite"
|
||||
},
|
||||
{
|
||||
"enabled": false,
|
||||
"name": "Vim-like hotkeys"
|
||||
}
|
||||
],
|
||||
"safe_search": 0
|
||||
}
|
||||
|
||||
.. code:: sh
|
||||
|
||||
{
|
||||
"autocomplete": "",
|
||||
"categories": [
|
||||
"map",
|
||||
"it",
|
||||
"images",
|
||||
],
|
||||
"default_locale": "",
|
||||
"default_theme": "oscar",
|
||||
"engines": [
|
||||
{
|
||||
"categories": [
|
||||
"map"
|
||||
],
|
||||
"enabled": true,
|
||||
"name": "openstreetmap",
|
||||
"shortcut": "osm"
|
||||
},
|
||||
{
|
||||
"categories": [
|
||||
"it"
|
||||
],
|
||||
"enabled": true,
|
||||
"name": "arch linux wiki",
|
||||
"shortcut": "al"
|
||||
},
|
||||
{
|
||||
"categories": [
|
||||
"images"
|
||||
],
|
||||
"enabled": true,
|
||||
"name": "google images",
|
||||
"shortcut": "goi"
|
||||
},
|
||||
{
|
||||
"categories": [
|
||||
"it"
|
||||
],
|
||||
"enabled": false,
|
||||
"name": "bitbucket",
|
||||
"shortcut": "bb"
|
||||
},
|
||||
],
|
||||
"instance_name": "searx",
|
||||
"locales": {
|
||||
"de": "Deutsch (German)",
|
||||
"en": "English",
|
||||
"eo": "Esperanto (Esperanto)",
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"enabled": true,
|
||||
"name": "HTTPS rewrite"
|
||||
},
|
||||
{
|
||||
"enabled": false,
|
||||
"name": "Vim-like hotkeys"
|
||||
}
|
||||
],
|
||||
"safe_search": 0
|
||||
}
|
||||
|
||||
Embed search bar
|
||||
----------------
|
||||
================
|
||||
|
||||
The search bar can be embedded into websites. Just paste the example into the HTML of the site.
|
||||
URL of the searx instance and values are customizable.
|
||||
The search bar can be embedded into websites. Just paste the example into the
|
||||
HTML of the site. URL of the searx instance and values are customizable.
|
||||
|
||||
.. code:: html
|
||||
|
||||
<form method="post" action="https://searx.me/">
|
||||
<!-- search query --> <input type="text" name="q" />
|
||||
<!-- categories --> <input type="hidden" name="categories" value="general,social media" />
|
||||
<!-- language --> <input type="hidden" name="lang" value="all" />
|
||||
<!-- locale --> <input type="hidden" name="locale" value="en" />
|
||||
<!-- date filter --> <input type="hidden" name="time_range" value="month" />
|
||||
</form>
|
||||
|
||||
<form method="post" action="https://searx.me/">
|
||||
<!-- search --> <input type="text" name="q" />
|
||||
<!-- categories --> <input type="hidden" name="categories" value="general,social media" />
|
||||
<!-- language --> <input type="hidden" name="lang" value="all" />
|
||||
<!-- locale --> <input type="hidden" name="locale" value="en" />
|
||||
<!-- date filter --> <input type="hidden" name="time_range" value="month" />
|
||||
</form>
|
||||
|
@ -1,42 +1,43 @@
|
||||
Searx admin interface: manage your instance from your browser
|
||||
=============================================================
|
||||
Searx admin interface
|
||||
=============================================================
|
||||
|
||||
One of the biggest advantages of searx is being extremely customizable. But at first it can be daunting to newcomers.
|
||||
A barrier of taking advantage of this feature is our ugly settings file which is sometimes hard to understand and edit.
|
||||
.. _searx-admin: https://github.com/kvch/searx-admin#searx-admin
|
||||
.. _NLnet Foundation: https://nlnet.nl/
|
||||
|
||||
To make self-hosting searx more accessible a new tool is introduced, called ``searx-admin``.
|
||||
It is a web application which is capable of managing your instance and manipulating its settings via a web UI.
|
||||
It aims to replace editing of ``settings.yml`` for less experienced administrators or people
|
||||
who prefer graphical admin interfaces.
|
||||
manage your instance from your browser
|
||||
|
||||
.. figure:: searx-admin-engines.png
|
||||
:scale: 50 %
|
||||
:alt: Screenshot of engine list
|
||||
:align: center
|
||||
:figclass: align-center
|
||||
|
||||
Configuration page of engines
|
||||
.. sidebar:: Installation
|
||||
|
||||
Installation guide can be found in the repository of searx-admin_.
|
||||
|
||||
Since ``searx-admin`` acts as a supervisor for searx, we have decided to implement it
|
||||
as a standalone tool instead of part of searx. Another reason for making it a standalone
|
||||
tool is that the codebase and dependencies of searx should not grow because of a fully optional feature,
|
||||
which does not affect existing instances.
|
||||
One of the biggest advantages of searx is being extremely customizable. But at
|
||||
first it can be daunting to newcomers. A barrier of taking advantage of this
|
||||
feature is our ugly settings file which is sometimes hard to understand and
|
||||
edit.
|
||||
|
||||
To make self-hosting searx more accessible a new tool is introduced, called
|
||||
``searx-admin``. It is a web application which is capable of managing your
|
||||
instance and manipulating its settings via a web UI. It aims to replace editing
|
||||
of ``settings.yml`` for less experienced administrators or people who prefer
|
||||
graphical admin interfaces.
|
||||
|
||||
Installation
|
||||
------------
|
||||
.. figure:: searx-admin-engines.png
|
||||
:alt: Screenshot of engine list
|
||||
|
||||
Installation guide can be found in the repository of searx-admin:
|
||||
https://github.com/kvch/searx-admin#installation--usage
|
||||
Configuration page of engines
|
||||
|
||||
Acknowledgements
|
||||
----------------
|
||||
Since ``searx-admin`` acts as a supervisor for searx, we have decided to
|
||||
implement it as a standalone tool instead of part of searx. Another reason for
|
||||
making it a standalone tool is that the codebase and dependencies of searx
|
||||
should not grow because of a fully optional feature, which does not affect
|
||||
existing instances.
|
||||
|
||||
This development was sponsored by `NLnet Foundation`_.
|
||||
|
||||
.. _NLnet Foundation: https://nlnet.nl/
|
||||
Acknowledgements
|
||||
================
|
||||
|
||||
This development was sponsored by `NLnet Foundation`_.
|
||||
|
||||
| Happy hacking.
|
||||
| kvch // 2017.08.22 21:25
|
||||
|
@ -1,45 +1,48 @@
|
||||
=======
|
||||
Plugins
|
||||
-------
|
||||
=======
|
||||
|
||||
Plugins can extend or replace functionality of various components of
|
||||
searx.
|
||||
Plugins can extend or replace functionality of various components of searx.
|
||||
|
||||
Example plugin
|
||||
~~~~~~~~~~~~~~
|
||||
==============
|
||||
|
||||
.. code:: python
|
||||
|
||||
name = 'Example plugin'
|
||||
description = 'This plugin extends the suggestions with the word "example"'
|
||||
default_on = False # disabled by default
|
||||
name = 'Example plugin'
|
||||
description = 'This plugin extends the suggestions with the word "example"'
|
||||
default_on = False # disabled by default
|
||||
|
||||
js_dependencies = tuple() # optional, list of static js files
|
||||
css_dependencies = tuple() # optional, list of static css files
|
||||
js_dependencies = tuple() # optional, list of static js files
|
||||
css_dependencies = tuple() # optional, list of static css files
|
||||
|
||||
|
||||
# attach callback to the post search hook
|
||||
# request: flask request object
|
||||
# ctx: the whole local context of the post search hook
|
||||
def post_search(request, ctx):
|
||||
ctx['search'].suggestions.add('example')
|
||||
return True
|
||||
# attach callback to the post search hook
|
||||
# request: flask request object
|
||||
# ctx: the whole local context of the post search hook
|
||||
def post_search(request, ctx):
|
||||
ctx['search'].suggestions.add('example')
|
||||
return True
|
||||
|
||||
Plugin entry points
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
===================
|
||||
|
||||
Entry points (hooks) define when a plugin runs. Right now only three hooks are implemented. So feel free to implement a hook if it fits the behaviour of your plugin.
|
||||
Entry points (hooks) define when a plugin runs. Right now only three hooks are
|
||||
implemented. So feel free to implement a hook if it fits the behaviour of your
|
||||
plugin.
|
||||
|
||||
Pre search hook
|
||||
```````````````
|
||||
---------------
|
||||
|
||||
Runs BEFORE the search request. Function to implement: ``pre_search``
|
||||
|
||||
Post search hook
|
||||
````````````````
|
||||
----------------
|
||||
|
||||
Runs AFTER the search request. Function to implement: ``post_search``
|
||||
|
||||
Result hook
|
||||
```````````
|
||||
-----------
|
||||
|
||||
Runs when a new result is added to the result list. Function to implement: ``on_result``
|
||||
Runs when a new result is added to the result list. Function to implement:
|
||||
``on_result``
|
||||
|
@ -1,43 +1,77 @@
|
||||
===========================
|
||||
Why use a private instance?
|
||||
===========================
|
||||
|
||||
"Is it worth to run my own instance?" is a common question among searx users. Before answering this question, see what options a searx user has.
|
||||
"Is it worth to run my own instance?" is a common question among searx users.
|
||||
Before answering this question, see what options a searx user has.
|
||||
|
||||
Public instances are open to everyone who has access to its URL. Usually, these are operated by unknown parties (from the users' point of view). Private instances can be used by a select group of people. It is for example a searx of group of friends or a company which can be accessed through VPN. Also it can be single user one which runs on the user's laptop.
|
||||
Public instances are open to everyone who has access to its URL. Usually, these
|
||||
are operated by unknown parties (from the users' point of view). Private
|
||||
instances can be used by a select group of people. It is for example a searx of
|
||||
group of friends or a company which can be accessed through VPN. Also it can be
|
||||
single user one which runs on the user's laptop.
|
||||
|
||||
To gain more insight on how these instances work let's dive into how searx protects its users.
|
||||
To gain more insight on how these instances work let's dive into how searx
|
||||
protects its users.
|
||||
|
||||
How does searx protect privacy?
|
||||
-------------------------------
|
||||
===============================
|
||||
|
||||
Searx protects the privacy of its users in multiple ways regardless of the type of the instance (private, public). Removal of private data from search requests comes in three forms:
|
||||
Searx protects the privacy of its users in multiple ways regardless of the type
|
||||
of the instance (private, public). Removal of private data from search requests
|
||||
comes in three forms:
|
||||
|
||||
1. removal of private data from requests going to search services
|
||||
2. not forwarding anything from a third party services through search services (e.g. advertisement)
|
||||
2. not forwarding anything from a third party services through search services
|
||||
(e.g. advertisement)
|
||||
3. removal of private data from requests going to the result pages
|
||||
|
||||
Removing private data means not sending cookies to external search engines and generating a random browser profile for every request. Thus, it does not matter if a public or private instance handles the request, because it is anonymized in both cases. IP addresses will be the IP of the instance. But searx can be configured to use proxy or Tor. `Result proxy <https://github.com/asciimoo/morty>`__ is supported, too.
|
||||
Removing private data means not sending cookies to external search engines and
|
||||
generating a random browser profile for every request. Thus, it does not matter
|
||||
if a public or private instance handles the request, because it is anonymized in
|
||||
both cases. IP addresses will be the IP of the instance. But searx can be
|
||||
configured to use proxy or Tor. `Result proxy
|
||||
<https://github.com/asciimoo/morty>`__ is supported, too.
|
||||
|
||||
Searx does not serve ads or tracking content unlike most search services. So
|
||||
private data is not forwarded to third parties who might monetize it. Besides
|
||||
protecting users from search services, both referring page and search query are
|
||||
hidden from visited result pages.
|
||||
|
||||
Searx does not serve ads or tracking content unlike most search services. So private data is not forwarded to third parties who might monetize it. Besides protecting users from search services, both referring page and search query are hidden from visited result pages.
|
||||
|
||||
What are the consequences of using public instances?
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
----------------------------------------------------
|
||||
|
||||
If someone uses a public instance, he/she has to trust the administrator of that instance.
|
||||
This means that the user of the public instance does not know whether his/her requests are logged, aggregated and sent or sold to a third party.
|
||||
If someone uses a public instance, he/she has to trust the administrator of that
|
||||
instance. This means that the user of the public instance does not know whether
|
||||
his/her requests are logged, aggregated and sent or sold to a third party.
|
||||
|
||||
Also, public instances without proper protection are more vulnerable to abusing the search service, In this case the external service in exchange returns CAPTCHAs or bans the IP of the instance. Thus, search requests return less results.
|
||||
Also, public instances without proper protection are more vulnerable to abusing
|
||||
the search service, In this case the external service in exchange returns
|
||||
CAPTCHAs or bans the IP of the instance. Thus, search requests return less
|
||||
results.
|
||||
|
||||
I see. What about private instances?
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
------------------------------------
|
||||
|
||||
If users run their own instances, everything is in their control: the source code, logging settings and private data. Unknown instance administrators do not have to be trusted.
|
||||
If users run their own instances, everything is in their control: the source
|
||||
code, logging settings and private data. Unknown instance administrators do not
|
||||
have to be trusted.
|
||||
|
||||
Furthermore, as the default settings of their instance is editable, there is no need to use cookies to tailor searx to their needs. So preferences will not be reset to defaults when clearing browser cookies. As settings are stored on their computer, it will not be accessible to others as long as their computer is not compromised.
|
||||
Furthermore, as the default settings of their instance is editable, there is no
|
||||
need to use cookies to tailor searx to their needs. So preferences will not be
|
||||
reset to defaults when clearing browser cookies. As settings are stored on
|
||||
their computer, it will not be accessible to others as long as their computer is
|
||||
not compromised.
|
||||
|
||||
Conclusion
|
||||
----------
|
||||
==========
|
||||
|
||||
Always use an instance which is operated by people you trust. The privacy features of searx are available to users no matter what kind of instance they use.
|
||||
Always use an instance which is operated by people you trust. The privacy
|
||||
features of searx are available to users no matter what kind of instance they
|
||||
use.
|
||||
|
||||
If someone is on the go or just wants to try searx for the first time public instances are the best choices. Additionally, public instance are making a world a better place, because those who cannot or do not want to run an instance, have access to a privacy respecting search service.
|
||||
If someone is on the go or just wants to try searx for the first time public
|
||||
instances are the best choices. Additionally, public instance are making a
|
||||
world a better place, because those who cannot or do not want to run an
|
||||
instance, have access to a privacy respecting search service.
|
||||
|
Loading…
Reference in New Issue