jandieman
/
searxng
mirror of https://github.com/searxng/searxng.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

[docs] revision of the article "settings.yml" 

This patch is a marginal revision of the article "settings.yml", most changes
are from normalizing the YAML syntax.

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
This commit is contained in:
Markus Heiser 2021-06-03 18:56:39 +02:00
parent 5caebb379f
commit c647c8b7a5
1 changed files with 125 additions and 101 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

226
docs/admin/settings.rst
View File

@ -22,13 +22,14 @@ file.
settings.yml location settings.yml location
===================== =====================
First, searx will try to load settings.yml from these locations: The initial ``settings.yml`` we be load from these locations:
1. the full path specified in the ``SEARX_SETTINGS_PATH`` environment variable. 1. the full path specified in the ``SEARX_SETTINGS_PATH`` environment variable.
2. ``/etc/searx/settings.yml`` 2. ``/etc/searx/settings.yml``
If these files don't exist (or are empty or can't be read), searx uses the If these files don't exist (or are empty or can't be read), searx uses the
:origin:`searx/settings.yml` file. :origin:`searx/settings.yml` file. Read :ref:`settings use_default_settings` to
see how you can simplify your *user defined* ``settings.yml``.
.. _settings global: .. _settings global:
@ -42,17 +43,19 @@ Global Settings
.. code:: yaml .. code:: yaml
general: general:
debug : False # Debug mode, only for development debug: false # Debug mode, only for development
instance_name : "searxng" # displayed name instance_name: "searxng" # displayed name
contact_url: False # mailto:contact@example.com contact_url: false # mailto:contact@example.com
.. code:: yaml
brand: brand:
git_url: https://github.com/searxng/searxng git_url: https://github.com/searxng/searxng
git_branch: master git_branch: master
issue_url: https://github.com/searxng/searxng/issues issue_url: https://github.com/searxng/searxng/issues
docs_url: https://searxng/searxng.github.io/searxng docs_url: https://searxng/searxng.github.io/searxng
public_instances: https://searx.space public_instances: https://searx.space
wiki_url: https://github.com/searxng/searxng/wiki wiki_url: https://github.com/searxng/searxng/wiki
``debug`` : ``debug`` :
Allow a more detailed log if you run searx directly. Display *detailed* error Allow a more detailed log if you run searx directly. Display *detailed* error
@ -68,10 +71,10 @@ Global Settings
If you host your own documentation, change this URL. If you host your own documentation, change this URL.
``wiki_url``: ``wiki_url``:
Link to your wiki (or ``False``) Link to your wiki (or ``false``)
``twitter_url``: ``twitter_url``:
Link to your tweets (or ``False``) Link to your tweets (or ``false``)
``server:`` ``server:``
@ -80,19 +83,19 @@ Global Settings
.. code:: yaml .. code:: yaml
server: server:
port : 8888 port: 8888
bind_address : "127.0.0.1" # address to listen on bind_address: "127.0.0.1" # address to listen on
secret_key : "ultrasecretkey" # change this! secret_key: "ultrasecretkey" # change this!
base_url : False # set custom base_url (or False) base_url: false # set custom base_url (or false)
image_proxy : False # proxying image results through searx image_proxy: false # proxying image results through searx
default_locale : "" # default interface locale default_locale: "" # default interface locale
default_theme : oscar # ui theme default_theme: oscar # ui theme
default_http_headers: default_http_headers:
X-Content-Type-Options : nosniff X-Content-Type-Options : nosniff
X-XSS-Protection : 1; mode=block X-XSS-Protection : 1; mode=block
X-Download-Options : noopen X-Download-Options : noopen
X-Robots-Tag : noindex, nofollow X-Robots-Tag : noindex, nofollow
Referrer-Policy : no-referrer Referrer-Policy : no-referrer
``port`` & ``bind_address``: ``port`` & ``bind_address``:
Port number and *bind address* of the searx web application if you run it Port number and *bind address* of the searx web application if you run it
@ -125,26 +128,30 @@ Global Settings
``outgoing:`` ``outgoing:``
------------- -------------
Communication with search engines.
.. code:: yaml .. code:: yaml
outgoing: # communication with search engines outgoing:
request_timeout : 2.0 # default timeout in seconds, can be override by engine request_timeout: 2.0 # default timeout in seconds, can be override by engine
# max_request_timeout: 10.0 # the maximum timeout in seconds max_request_timeout: 10.0 # the maximum timeout in seconds
useragent_suffix : "" # informations like an email address to the administrator useragent_suffix: "" # informations like an email address to the administrator
pool_connections : 100 # Maximum number of allowable connections, or None for no limits. The default is 100. pool_connections: 100 # Maximum number of allowable connections, or null
pool_maxsize : 10 # Number of allowable keep-alive connections, or None to always allow. The default is 10. # for no limits. The default is 100.
enable_http2: True # See https://www.python-httpx.org/http2/ pool_maxsize: 10 # Number of allowable keep-alive connections, or null
# uncomment below section if you want to use a proxy # to always allow. The default is 10.
# proxies: enable_http2: true # See https://www.python-httpx.org/http2/
# all://: # uncomment below section if you want to use a proxy
# - http://proxy1:8080 # proxies:
# - http://proxy2:8080 # all://:
# uncomment below section only if you have more than one network interface # - http://proxy1:8080
# which can be the source of outgoing search requests # - http://proxy2:8080
# source_ips: # uncomment below section only if you have more than one network interface
# - 1.1.1.1 # which can be the source of outgoing search requests
# - 1.1.1.2 # source_ips:
# - fe80::/126 # - 1.1.1.1
# - 1.1.1.2
# - fe80::/126
``request_timeout`` : ``request_timeout`` :
@ -180,8 +187,8 @@ Global Settings
* ``[ 192.168.0.1, fe80::/126 ]`` * ``[ 192.168.0.1, fe80::/126 ]``
``retries`` : ``retries`` :
Number of retry in case of an HTTP error. Number of retry in case of an HTTP error. On each retry, searx uses an
On each retry, searx uses an different proxy and source ip. different proxy and source ip.
``retry_on_http_error`` : ``retry_on_http_error`` :
Retry request on some HTTP status code. Retry request on some HTTP status code.
@ -193,7 +200,7 @@ Global Settings
* ``[403, 429]``: on HTTP status code 403 and 429. * ``[403, 429]``: on HTTP status code 403 and 429.
``enable_http2`` : ``enable_http2`` :
Enable by default. Set to ``False`` to disable HTTP/2. Enable by default. Set to ``false`` to disable HTTP/2.
``max_redirects`` : ``max_redirects`` :
30 by default. Maximum redirect before it is an error. 30 by default. Maximum redirect before it is an error.
@ -205,18 +212,18 @@ Global Settings
.. code:: yaml .. code:: yaml
locales: locales:
en : English en: English
de : Deutsch de: Deutsch
he : Hebrew he: Hebrew
hu : Magyar hu: Magyar
fr : Français fr: Français
es : Español es: Español
it : Italiano it: Italiano
nl : Nederlands nl: Nederlands
ja : 日本語 (Japanese) ja: 日本語 (Japanese)
tr : Türkçe tr: Türkçe
ru : Russian ru: Russian
ro : Romanian ro: Romanian
``locales`` : ``locales`` :
Locales codes and their names. Available translations of searx interface. Locales codes and their names. Available translations of searx interface.
@ -232,33 +239,46 @@ Engine settings
- :ref:`general engine settings` - :ref:`general engine settings`
- :ref:`engines-dev` - :ref:`engines-dev`
In the code example below a *full fledged* example of a YAML setup from a dummy
engine is shown. Most of the options have a default value or even are optional.
.. code:: yaml .. code:: yaml
- name : bing - name: example engine
engine : bing engine: example
shortcut : bi shortcut: demo
base_url : 'https://{language}.wikipedia.org/' base_url: 'https://{language}.example.com/'
categories : general categories: general
timeout : 3.0 timeout: 3.0
api_key : 'apikey' api_key: 'apikey'
disabled : True disabled: false
language : en_US language: en_US
#enable_http: False tokens: [ 'my-secret-token' ]
#enable_http2: False weigth: 1
#retries: 1 display_error_messages: true
#retry_on_http_error: True # or 403 or [404, 429] about:
#max_connections: 100 website: https://example.com
#max_keepalive_connections: 10 wikidata_id: Q306656
#keepalive_expiry: 5.0 official_api_documentation: https://example.com/api-doc
#proxies: use_official_api: true
# http: require_api_key: true
# - http://proxy1:8080 results: HTML
# - http://proxy2:8080 enable_http: false
# https: enable_http2: false
# - http://proxy1:8080 retries: 1
# - http://proxy2:8080 retry_on_http_error: true # or 403 or [404, 429]
# - socks5://user:password@proxy3:1080 max_connections: 100
# - socks5h://user:password@proxy4:1080 max_keepalive_connections: 10
keepalive_expiry: 5.0
proxies:
http:
- http://proxy1:8080
- http://proxy2:8080
https:
- http://proxy1:8080
- http://proxy2:8080
- socks5://user:password@proxy3:1080
- socks5h://user:password@proxy4:1080
``name`` : ``name`` :
Name that will be used across searx to define this engine. In settings, on Name that will be used across searx to define this engine. In settings, on
@ -298,10 +318,14 @@ Engine settings
by using the full ISO code of language and country, like ``fr_FR``, ``en_US``, by using the full ISO code of language and country, like ``fr_FR``, ``en_US``,
``de_DE``. ``de_DE``.
``tokens`` : optional
A list of secret tokens to make this engine *private*, more details see
:ref:`private engines`.
``weigth`` : default ``1`` ``weigth`` : default ``1``
Weighting of the results of this engine. Weighting of the results of this engine.
``display_error_messages`` : default ``True`` ``display_error_messages`` : default ``true``
When an engine returns an error, the message is displayed on the user interface. When an engine returns an error, the message is displayed on the user interface.
``network``: optional ``network``: optional
@ -321,7 +345,7 @@ Engine settings
use_default_settings use_default_settings
==================== ====================
.. sidebar:: ``use_default_settings: True`` .. sidebar:: ``use_default_settings: true``
- :ref:`settings location` - :ref:`settings location`
- :ref:`use_default_settings.yml` - :ref:`use_default_settings.yml`
@ -330,7 +354,7 @@ use_default_settings
The user defined ``settings.yml`` is loaded from the :ref:`settings location` The user defined ``settings.yml`` is loaded from the :ref:`settings location`
and can relied on the default configuration :origin:`searx/settings.yml` using: and can relied on the default configuration :origin:`searx/settings.yml` using:
``use_default_settings: True`` ``use_default_settings: true``
``server:`` ``server:``
In the following example, the actual settings are the default settings defined In the following example, the actual settings are the default settings defined
@ -339,22 +363,22 @@ and can relied on the default configuration :origin:`searx/settings.yml` using:
.. code-block:: yaml .. code-block:: yaml
use_default_settings: True use_default_settings: true
server: server:
secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA" secret_key: "ultrasecretkey" # change this!
bind_address: "0.0.0.0" bind_address: "0.0.0.0"
``engines:`` ``engines:``
With ``use_default_settings: True``, each settings can be override in a With ``use_default_settings: true``, each settings can be override in a
similar way, the ``engines`` section is merged according to the engine similar way, the ``engines`` section is merged according to the engine
``name``. In this example, searx will load all the engine and the arch linux ``name``. In this example, searx will load all the engine and the arch linux
wiki engine has a :ref:`token<private engines>`: wiki engine has a :ref:`token <private engines>`:
.. code-block:: yaml .. code-block:: yaml
use_default_settings: True use_default_settings: true
server: server:
secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA" secret_key: "ultrasecretkey" # change this!
engines: engines:
- name: arch linux wiki - name: arch linux wiki
tokens: ['$ecretValue'] tokens: ['$ecretValue']
@ -367,11 +391,11 @@ and can relied on the default configuration :origin:`searx/settings.yml` using:
.. code-block:: yaml .. code-block:: yaml
use_default_settings: use_default_settings:
engines: engines:
remove: remove:
- google - google
server: server:
secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA" secret_key: "ultrasecretkey" # change this!
engines: engines:
- name: arch linux wiki - name: arch linux wiki
tokens: ['$ecretValue'] tokens: ['$ecretValue']
@ -383,12 +407,12 @@ and can relied on the default configuration :origin:`searx/settings.yml` using:
.. code-block:: yaml .. code-block:: yaml
use_default_settings: use_default_settings:
engines: engines:
keep_only: keep_only:
- google - google
- duckduckgo - duckduckgo
server: server:
secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA" secret_key: "ultrasecretkey" # change this!
engines: engines:
- name: google - name: google
tokens: ['$ecretValue'] tokens: ['$ecretValue']