git.iko.soy/searx
on v1.0.0 help sign in
searx/docs/admin/settings.rst
356 lines 11 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 # Number of different hosts
134 pool_maxsize : 10 # Number of simultaneous requests by host
135 # uncomment below section if you want to use a proxy
136 # proxies:
137 # http:
138 # - http://proxy1:8080
139 # - http://proxy2:8080
140 # https:
141 # - http://proxy1:8080
142 # - http://proxy2:8080
143 # uncomment below section only if you have more than one network interface
144 # which can be the source of outgoing search requests
145 # source_ips:
146 # - 1.1.1.1
147 # - 1.1.1.2
150``request_timeout`` :
151 Global timeout of the requests made to others engines in seconds. A bigger
152 timeout will allow to wait for answers from slow engines, but in consequence
153 will slow searx reactivity (the result page may take the time specified in the
154 timeout to load). Can be override by :ref:`settings engine`
156``useragent_suffix`` :
157 Suffix to the user-agent searx uses to send requests to others engines. If an
158 engine wish to block you, a contact info here may be useful to avoid that.
160.. _requests proxies: https://requests.readthedocs.io/en/latest/user/advanced/#proxies
161.. _PySocks: https://pypi.org/project/PySocks/
163``proxies`` :
164 Define one or more proxies you wish to use, see `requests proxies`_.
165 If there are more than one proxy for one protocol (http, https),
166 requests to the engines are distributed in a round-robin fashion.
168 - Proxy: `see <https://2.python-requests.org/en/latest/user/advanced/#proxies>`__.
169 - SOCKS proxies are also supported: `see <https://2.python-requests.org/en/latest/user/advanced/#socks>`__
171``source_ips`` :
172 If you use multiple network interfaces, define from which IP the requests must
173 be made. This parameter is ignored when ``proxies`` is set.
176``locales:``
177------------
179.. code:: yaml
181 locales:
182 en : English
183 de : Deutsch
184 he : Hebrew
185 hu : Magyar
186 fr : Français
187 es : Español
188 it : Italiano
189 nl : Nederlands
190 ja : 日本語 (Japanese)
191 tr : Türkçe
192 ru : Russian
193 ro : Romanian
195``locales`` :
196 Locales codes and their names. Available translations of searx interface.
199.. _settings engine:
201Engine settings
202===============
204.. sidebar:: Further reading ..
206 - :ref:`engines-dev`
208.. code:: yaml
210 - name : bing
211 engine : bing
212 shortcut : bi
213 base_url : 'https://{language}.wikipedia.org/'
214 categories : general
215 timeout : 3.0
216 api_key : 'apikey'
217 disabled : True
218 language : en_US
219 #proxies:
220 # http:
221 # - http://proxy1:8080
222 # - http://proxy2:8080
223 # https:
224 # - http://proxy1:8080
225 # - http://proxy2:8080
226 # - socks5://user:password@proxy3:1080
227 # - socks5h://user:password@proxy4:1080
229``name`` :
230 Name that will be used across searx to define this engine. In settings, on
231 the result page...
233``engine`` :
234 Name of the python file used to handle requests and responses to and from this
235 search engine.
237``shortcut`` :
238 Code used to execute bang requests (in this case using ``!bi`` or ``?bi``)
240``base_url`` : optional
241 Part of the URL that should be stable across every request. Can be useful to
242 use multiple sites using only one engine, or updating the site URL without
243 touching at the code.
245``categories`` : optional
246 Define in which categories this engine will be active. Most of the time, it is
247 defined in the code of the engine, but in a few cases it is useful, like when
248 describing multiple search engine using the same code.
250``timeout`` : optional
251 Timeout of the search with the current search engine. **Be careful, it will
252 modify the global timeout of searx.**
254``api_key`` : optional
255 In a few cases, using an API needs the use of a secret key. How to obtain them
256 is described in the file.
258``disabled`` : optional
259 To disable by default the engine, but not deleting it. It will allow the user
260 to manually activate it in the settings.
262``language`` : optional
263 If you want to use another language for a specific engine, you can define it
264 by using the full ISO code of language and country, like ``fr_FR``, ``en_US``,
265 ``de_DE``.
267``weigth`` : default ``1``
268 Weighting of the results of this engine.
270``display_error_messages`` : default ``True``
271 When an engine returns an error, the message is displayed on the user interface.
273.. note::
275 A few more options are possible, but they are pretty specific to some
276 engines, and so won't be described here.
279.. _settings use_default_settings:
281use_default_settings
282====================
284.. sidebar:: ``use_default_settings: True``
286 - :ref:`settings location`
287 - :ref:`use_default_settings.yml`
288 - :origin:`/etc/searx/settings.yml <utils/templates/etc/searx/use_default_settings.yml>`
290The user defined ``settings.yml`` is loaded from the :ref:`settings location`
291and can relied on the default configuration :origin:`searx/settings.yml` using:
293 ``use_default_settings: True``
295``server:``
296 In the following example, the actual settings are the default settings defined
297 in :origin:`searx/settings.yml` with the exception of the ``secret_key`` and
298 the ``bind_address``:
300 .. code-block:: yaml
302 use_default_settings: True
303 server:
304 secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA"
305 bind_address: "0.0.0.0"
307``engines:``
308 With ``use_default_settings: True``, each settings can be override in a
309 similar way, the ``engines`` section is merged according to the engine
310 ``name``. In this example, searx will load all the engine and the arch linux
311 wiki engine has a :ref:`token<private engines>`:
313 .. code-block:: yaml
315 use_default_settings: True
316 server:
317 secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA"
318 engines:
319 - name: arch linux wiki
320 tokens: ['$ecretValue']
322``engines:`` / ``remove:``
323 It is possible to remove some engines from the default settings. The following
324 example is similar to the above one, but searx doesn't load the the google
325 engine:
327 .. code-block:: yaml
329 use_default_settings:
330 engines:
331 remove:
332 - google
333 server:
334 secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA"
335 engines:
336 - name: arch linux wiki
337 tokens: ['$ecretValue']
339``engines:`` / ``keep_only:``
340 As an alternative, it is possible to specify the engines to keep. In the
341 following example, searx has only two engines:
343 .. code-block:: yaml
345 use_default_settings:
346 engines:
347 keep_only:
348 - google
349 - duckduckgo
350 server:
351 secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA"
352 engines:
353 - name: google
354 tokens: ['$ecretValue']
355 - name: duckduckgo
356 tokens: ['$ecretValue']