git.iko.soy/searx
on ec4e48e help sign in
searx/docs/admin/settings.rst
394 lines 12 kB history raw
1.. _settings.yml:
3================
4``settings.yml``
5================
7This page describe the options possibilities of the :origin:`searx/settings.yml`
8file.
10.. sidebar:: Further reading ..
12 - :ref:`use_default_settings.yml`
13 - :ref:`search API`
15.. contents:: Contents
16 :depth: 2
17 :local:
18 :backlinks: entry
20.. _settings location:
22settings.yml location
23=====================
25First, searx will try to load settings.yml from these locations:
271. the full path specified in the ``SEARX_SETTINGS_PATH`` environment variable.
282. ``/etc/searx/settings.yml``
30If these files don't exist (or are empty or can't be read), searx uses the
31:origin:`searx/settings.yml` file.
34.. _settings global:
36Global Settings
37===============
39``general:``
40------------
42.. code:: yaml
44 general:
45 debug : False # Debug mode, only for development
46 instance_name : "searx" # displayed name
47 git_url: https://github.com/searx/searx
48 git_branch: master
49 issue_url: https://github.com/searx/searx/issues
50 docs_url: https://searx.github.io/searx
51 public_instances: https://searx.space
52 contact_url: False # mailto:contact@example.com
53 wiki_url: https://github.com/searx/searx/wiki
54 twitter_url: https://twitter.com/Searx_engine
56``debug`` :
57 Allow a more detailed log if you run searx directly. Display *detailed* error
58 messages in the browser too, so this must be deactivated in production.
60``contact_url``:
61 Contact ``mailto:`` address or WEB form.
63``git_url`` and ``git_branch``:
64 Changes this, to point to your searx fork (branch).
66``docs_url``
67 If you host your own documentation, change this URL.
69``wiki_url``:
70 Link to your wiki (or ``False``)
72``twitter_url``:
73 Link to your tweets (or ``False``)
76``server:``
77-----------
79.. code:: yaml
81 server:
82 port : 8888
83 bind_address : "127.0.0.1" # address to listen on
84 secret_key : "ultrasecretkey" # change this!
85 base_url : False # set custom base_url (or False)
86 image_proxy : False # proxying image results through searx
87 default_locale : "" # default interface locale
88 default_theme : oscar # ui theme
89 default_http_headers:
90 X-Content-Type-Options : nosniff
91 X-XSS-Protection : 1; mode=block
92 X-Download-Options : noopen
93 X-Robots-Tag : noindex, nofollow
94 Referrer-Policy : no-referrer
96``port`` & ``bind_address``:
97 Port number and *bind address* of the searx web application if you run it
98 directly using ``python searx/webapp.py``. Doesn't apply to searx running on
99 Apache or Nginx.
101``secret_key`` :
102 Used for cryptography purpose.
104``base_url`` :
105 The base URL where searx is deployed. Used to create correct inbound links.
107``image_proxy`` :
108 Allow your instance of searx of being able to proxy images. Uses memory space.
110``default_locale`` :
111 Searx interface language. If blank, the locale is detected by using the
112 browser language. If it doesn't work, or you are deploying a language
113 specific instance of searx, a locale can be defined using an ISO language
114 code, like ``fr``, ``en``, ``de``.
116``default_theme`` :
117 Name of the theme you want to use by default on your searx instance.
119.. _HTTP headers: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers
121``default_http_headers``:
122 Set additional HTTP headers, see `#755 <https://github.com/searx/searx/issues/715>`__
124``outgoing:``
125-------------
127.. code:: yaml
129 outgoing: # communication with search engines
130 request_timeout : 2.0 # default timeout in seconds, can be override by engine
131 # max_request_timeout: 10.0 # the maximum timeout in seconds
132 useragent_suffix : "" # informations like an email address to the administrator
133 pool_connections : 100 # Maximum number of allowable connections, or None for no limits. The default is 100.
134 pool_maxsize : 10 # Number of allowable keep-alive connections, or None to always allow. The default is 10.
135 enable_http2: True # See https://www.python-httpx.org/http2/
136 # uncomment below section if you want to use a proxy
137 # proxies:
138 # all://:
139 # - http://proxy1:8080
140 # - http://proxy2:8080
141 # uncomment below section only if you have more than one network interface
142 # which can be the source of outgoing search requests
143 # source_ips:
144 # - 1.1.1.1
145 # - 1.1.1.2
146 # - fe80::/126
149``request_timeout`` :
150 Global timeout of the requests made to others engines in seconds. A bigger
151 timeout will allow to wait for answers from slow engines, but in consequence
152 will slow searx reactivity (the result page may take the time specified in the
153 timeout to load). Can be override by :ref:`settings engine`
155``useragent_suffix`` :
156 Suffix to the user-agent searx uses to send requests to others engines. If an
157 engine wish to block you, a contact info here may be useful to avoid that.
159``keepalive_expiry``:
160 Number of seconds to keep a connection in the pool. By default 5.0 seconds.
162.. _httpx proxies: https://www.python-httpx.org/advanced/#http-proxying
164``proxies`` :
165 Define one or more proxies you wish to use, see `httpx proxies`_.
166 If there are more than one proxy for one protocol (http, https),
167 requests to the engines are distributed in a round-robin fashion.
169``source_ips`` :
170 If you use multiple network interfaces, define from which IP the requests must
171 be made. Example:
173 * ``0.0.0.0`` any local IPv4 address.
174 * ``::`` any local IPv6 address.
175 * ``192.168.0.1``
176 * ``[ 192.168.0.1, 192.168.0.2 ]`` these two specific IP addresses
177 * ``fe80::60a2:1691:e5a2:ee1f``
178 * ``fe80::60a2:1691:e5a2:ee1f/126`` all IP addresses in this network.
179 * ``[ 192.168.0.1, fe80::/126 ]``
181``retries`` :
182 Number of retry in case of an HTTP error.
183 On each retry, searx uses an different proxy and source ip.
185``retry_on_http_error`` :
186 Retry request on some HTTP status code.
188 Example:
190 * ``true`` : on HTTP status code between 400 and 599.
191 * ``403`` : on HTTP status code 403.
192 * ``[403, 429]``: on HTTP status code 403 and 429.
194``enable_http2`` :
195 Enable by default. Set to ``False`` to disable HTTP/2.
197``max_redirects`` :
198 30 by default. Maximum redirect before it is an error.
201``locales:``
202------------
204.. code:: yaml
206 locales:
207 en : English
208 de : Deutsch
209 he : Hebrew
210 hu : Magyar
211 fr : Français
212 es : Español
213 it : Italiano
214 nl : Nederlands
215 ja : 日本語 (Japanese)
216 tr : Türkçe
217 ru : Russian
218 ro : Romanian
220``locales`` :
221 Locales codes and their names. Available translations of searx interface.
224.. _settings engine:
226Engine settings
227===============
229.. sidebar:: Further reading ..
231 - :ref:`engines-dev`
233.. code:: yaml
235 - name : bing
236 engine : bing
237 shortcut : bi
238 base_url : 'https://{language}.wikipedia.org/'
239 categories : general
240 timeout : 3.0
241 api_key : 'apikey'
242 disabled : True
243 language : en_US
244 #enable_http: False
245 #enable_http2: False
246 #retries: 1
247 #retry_on_http_error: True # or 403 or [404, 429]
248 #max_connections: 100
249 #max_keepalive_connections: 10
250 #keepalive_expiry: 5.0
251 #proxies:
252 # http:
253 # - http://proxy1:8080
254 # - http://proxy2:8080
255 # https:
256 # - http://proxy1:8080
257 # - http://proxy2:8080
258 # - socks5://user:password@proxy3:1080
259 # - socks5h://user:password@proxy4:1080
261``name`` :
262 Name that will be used across searx to define this engine. In settings, on
263 the result page...
265``engine`` :
266 Name of the python file used to handle requests and responses to and from this
267 search engine.
269``shortcut`` :
270 Code used to execute bang requests (in this case using ``!bi`` or ``?bi``)
272``base_url`` : optional
273 Part of the URL that should be stable across every request. Can be useful to
274 use multiple sites using only one engine, or updating the site URL without
275 touching at the code.
277``categories`` : optional
278 Define in which categories this engine will be active. Most of the time, it is
279 defined in the code of the engine, but in a few cases it is useful, like when
280 describing multiple search engine using the same code.
282``timeout`` : optional
283 Timeout of the search with the current search engine. **Be careful, it will
284 modify the global timeout of searx.**
286``api_key`` : optional
287 In a few cases, using an API needs the use of a secret key. How to obtain them
288 is described in the file.
290``disabled`` : optional
291 To disable by default the engine, but not deleting it. It will allow the user
292 to manually activate it in the settings.
294``language`` : optional
295 If you want to use another language for a specific engine, you can define it
296 by using the full ISO code of language and country, like ``fr_FR``, ``en_US``,
297 ``de_DE``.
299``weigth`` : default ``1``
300 Weighting of the results of this engine.
302``display_error_messages`` : default ``True``
303 When an engine returns an error, the message is displayed on the user interface.
305``network``: optional
306 Use the network configuration from another engine.
307 In addition, there are two default networks:
308 * ``ipv4`` set ``local_addresses`` to ``0.0.0.0`` (use only IPv4 local addresses)
309 * ``ipv6`` set ``local_addresses`` to ``::`` (use only IPv6 local addresses)
311.. note::
313 A few more options are possible, but they are pretty specific to some
314 engines, and so won't be described here.
317.. _settings use_default_settings:
319use_default_settings
320====================
322.. sidebar:: ``use_default_settings: True``
324 - :ref:`settings location`
325 - :ref:`use_default_settings.yml`
326 - :origin:`/etc/searx/settings.yml <utils/templates/etc/searx/use_default_settings.yml>`
328The user defined ``settings.yml`` is loaded from the :ref:`settings location`
329and can relied on the default configuration :origin:`searx/settings.yml` using:
331 ``use_default_settings: True``
333``server:``
334 In the following example, the actual settings are the default settings defined
335 in :origin:`searx/settings.yml` with the exception of the ``secret_key`` and
336 the ``bind_address``:
338 .. code-block:: yaml
340 use_default_settings: True
341 server:
342 secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA"
343 bind_address: "0.0.0.0"
345``engines:``
346 With ``use_default_settings: True``, each settings can be override in a
347 similar way, the ``engines`` section is merged according to the engine
348 ``name``. In this example, searx will load all the engine and the arch linux
349 wiki engine has a :ref:`token<private engines>`:
351 .. code-block:: yaml
353 use_default_settings: True
354 server:
355 secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA"
356 engines:
357 - name: arch linux wiki
358 tokens: ['$ecretValue']
360``engines:`` / ``remove:``
361 It is possible to remove some engines from the default settings. The following
362 example is similar to the above one, but searx doesn't load the the google
363 engine:
365 .. code-block:: yaml
367 use_default_settings:
368 engines:
369 remove:
370 - google
371 server:
372 secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA"
373 engines:
374 - name: arch linux wiki
375 tokens: ['$ecretValue']
377``engines:`` / ``keep_only:``
378 As an alternative, it is possible to specify the engines to keep. In the
379 following example, searx has only two engines:
381 .. code-block:: yaml
383 use_default_settings:
384 engines:
385 keep_only:
386 - google
387 - duckduckgo
388 server:
389 secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA"
390 engines:
391 - name: google
392 tokens: ['$ecretValue']
393 - name: duckduckgo
394 tokens: ['$ecretValue']