settings.rst 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357
  1. .. _settings.yml:
  2. ================
  3. ``settings.yml``
  4. ================
  5. This page describe the options possibilities of the :origin:`searx/settings.yml`
  6. file.
  7. .. sidebar:: Further reading ..
  8. - :ref:`use_default_settings.yml`
  9. - :ref:`search API`
  10. .. contents:: Contents
  11. :depth: 2
  12. :local:
  13. :backlinks: entry
  14. .. _settings location:
  15. settings.yml location
  16. =====================
  17. First, searx will try to load settings.yml from these locations:
  18. 1. the full path specified in the ``SEARX_SETTINGS_PATH`` environment variable.
  19. 2. ``/etc/searx/settings.yml``
  20. If these files don't exist (or are empty or can't be read), searx uses the
  21. :origin:`searx/settings.yml` file.
  22. .. _settings global:
  23. Global Settings
  24. ===============
  25. ``general:``
  26. ------------
  27. .. code:: yaml
  28. general:
  29. debug : False # Debug mode, only for development
  30. instance_name : "searx" # displayed name
  31. git_url: https://github.com/searx/searx
  32. git_branch: master
  33. issue_url: https://github.com/searx/searx/issues
  34. docs_url: https://searx.github.io/searx
  35. public_instances: https://searx.space
  36. contact_url: False # mailto:contact@example.com
  37. wiki_url: https://github.com/searx/searx/wiki
  38. twitter_url: https://twitter.com/Searx_engine
  39. ``debug`` :
  40. Allow a more detailed log if you run searx directly. Display *detailed* error
  41. messages in the browser too, so this must be deactivated in production.
  42. ``contact_url``:
  43. Contact ``mailto:`` address or WEB form.
  44. ``git_url`` and ``git_branch``:
  45. Changes this, to point to your searx fork (branch).
  46. ``docs_url``
  47. If you host your own documentation, change this URL.
  48. ``wiki_url``:
  49. Link to your wiki (or ``False``)
  50. ``twitter_url``:
  51. Link to your tweets (or ``False``)
  52. ``server:``
  53. -----------
  54. .. code:: yaml
  55. server:
  56. port : 8888
  57. bind_address : "127.0.0.1" # address to listen on
  58. secret_key : "ultrasecretkey" # change this!
  59. base_url : False # set custom base_url (or False)
  60. image_proxy : False # proxying image results through searx
  61. default_locale : "" # default interface locale
  62. default_theme : oscar # ui theme
  63. default_http_headers:
  64. X-Content-Type-Options : nosniff
  65. X-XSS-Protection : 1; mode=block
  66. X-Download-Options : noopen
  67. X-Robots-Tag : noindex, nofollow
  68. Referrer-Policy : no-referrer
  69. ``port`` & ``bind_address``:
  70. Port number and *bind address* of the searx web application if you run it
  71. directly using ``python searx/webapp.py``. Doesn't apply to searx running on
  72. Apache or Nginx.
  73. ``secret_key`` :
  74. Used for cryptography purpose.
  75. ``base_url`` :
  76. The base URL where searx is deployed. Used to create correct inbound links.
  77. ``image_proxy`` :
  78. Allow your instance of searx of being able to proxy images. Uses memory space.
  79. ``default_locale`` :
  80. Searx interface language. If blank, the locale is detected by using the
  81. browser language. If it doesn't work, or you are deploying a language
  82. specific instance of searx, a locale can be defined using an ISO language
  83. code, like ``fr``, ``en``, ``de``.
  84. ``default_theme`` :
  85. Name of the theme you want to use by default on your searx instance.
  86. .. _HTTP headers: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers
  87. ``default_http_headers``:
  88. Set additional HTTP headers, see `#755 <https://github.com/searx/searx/issues/715>`__
  89. ``outgoing:``
  90. -------------
  91. .. code:: yaml
  92. outgoing: # communication with search engines
  93. request_timeout : 2.0 # default timeout in seconds, can be override by engine
  94. # max_request_timeout: 10.0 # the maximum timeout in seconds
  95. useragent_suffix : "" # informations like an email address to the administrator
  96. pool_connections : 100 # Number of different hosts
  97. pool_maxsize : 10 # Number of simultaneous requests by host
  98. # uncomment below section if you want to use a proxy
  99. # proxies:
  100. # http:
  101. # - http://proxy1:8080
  102. # - http://proxy2:8080
  103. # https:
  104. # - http://proxy1:8080
  105. # - http://proxy2:8080
  106. # uncomment below section only if you have more than one network interface
  107. # which can be the source of outgoing search requests
  108. # source_ips:
  109. # - 1.1.1.1
  110. # - 1.1.1.2
  111. ``request_timeout`` :
  112. Global timeout of the requests made to others engines in seconds. A bigger
  113. timeout will allow to wait for answers from slow engines, but in consequence
  114. will slow searx reactivity (the result page may take the time specified in the
  115. timeout to load). Can be override by :ref:`settings engine`
  116. ``useragent_suffix`` :
  117. Suffix to the user-agent searx uses to send requests to others engines. If an
  118. engine wish to block you, a contact info here may be useful to avoid that.
  119. .. _requests proxies: https://requests.readthedocs.io/en/latest/user/advanced/#proxies
  120. .. _PySocks: https://pypi.org/project/PySocks/
  121. ``proxies`` :
  122. Define one or more proxies you wish to use, see `requests proxies`_.
  123. If there are more than one proxy for one protocol (http, https),
  124. requests to the engines are distributed in a round-robin fashion.
  125. - Proxy: `see <https://2.python-requests.org/en/latest/user/advanced/#proxies>`__.
  126. - SOCKS proxies are also supported: `see <https://2.python-requests.org/en/latest/user/advanced/#socks>`__
  127. ``source_ips`` :
  128. If you use multiple network interfaces, define from which IP the requests must
  129. be made. This parameter is ignored when ``proxies`` is set.
  130. ``locales:``
  131. ------------
  132. .. code:: yaml
  133. locales:
  134. en : English
  135. de : Deutsch
  136. he : Hebrew
  137. hu : Magyar
  138. fr : Français
  139. es : Español
  140. it : Italiano
  141. nl : Nederlands
  142. ja : 日本語 (Japanese)
  143. tr : Türkçe
  144. ru : Russian
  145. ro : Romanian
  146. ``locales`` :
  147. Locales codes and their names. Available translations of searx interface.
  148. .. _settings engine:
  149. Engine settings
  150. ===============
  151. .. sidebar:: Further reading ..
  152. - :ref:`engines-dev`
  153. .. code:: yaml
  154. - name : bing
  155. engine : bing
  156. shortcut : bi
  157. base_url : 'https://{language}.wikipedia.org/'
  158. categories : general
  159. timeout : 3.0
  160. api_key : 'apikey'
  161. disabled : True
  162. language : en_US
  163. #proxies:
  164. # http:
  165. # - http://proxy1:8080
  166. # - http://proxy2:8080
  167. # https:
  168. # - http://proxy1:8080
  169. # - http://proxy2:8080
  170. # - socks5://user:password@proxy3:1080
  171. # - socks5h://user:password@proxy4:1080
  172. ``name`` :
  173. Name that will be used across searx to define this engine. In settings, on
  174. the result page...
  175. ``engine`` :
  176. Name of the python file used to handle requests and responses to and from this
  177. search engine.
  178. ``shortcut`` :
  179. Code used to execute bang requests (in this case using ``!bi`` or ``?bi``)
  180. ``base_url`` : optional
  181. Part of the URL that should be stable across every request. Can be useful to
  182. use multiple sites using only one engine, or updating the site URL without
  183. touching at the code.
  184. ``categories`` : optional
  185. Define in which categories this engine will be active. Most of the time, it is
  186. defined in the code of the engine, but in a few cases it is useful, like when
  187. describing multiple search engine using the same code.
  188. ``timeout`` : optional
  189. Timeout of the search with the current search engine. **Be careful, it will
  190. modify the global timeout of searx.**
  191. ``api_key`` : optional
  192. In a few cases, using an API needs the use of a secret key. How to obtain them
  193. is described in the file.
  194. ``disabled`` : optional
  195. To disable by default the engine, but not deleting it. It will allow the user
  196. to manually activate it in the settings.
  197. ``language`` : optional
  198. If you want to use another language for a specific engine, you can define it
  199. by using the full ISO code of language and country, like ``fr_FR``, ``en_US``,
  200. ``de_DE``.
  201. ``weigth`` : default ``1``
  202. Weighting of the results of this engine.
  203. ``display_error_messages`` : default ``True``
  204. When an engine returns an error, the message is displayed on the user interface.
  205. .. note::
  206. A few more options are possible, but they are pretty specific to some
  207. engines, and so won't be described here.
  208. .. _settings use_default_settings:
  209. use_default_settings
  210. ====================
  211. .. sidebar:: ``use_default_settings: True``
  212. - :ref:`settings location`
  213. - :ref:`use_default_settings.yml`
  214. - :origin:`/etc/searx/settings.yml <utils/templates/etc/searx/use_default_settings.yml>`
  215. The user defined ``settings.yml`` is loaded from the :ref:`settings location`
  216. and can relied on the default configuration :origin:`searx/settings.yml` using:
  217. ``use_default_settings: True``
  218. ``server:``
  219. In the following example, the actual settings are the default settings defined
  220. in :origin:`searx/settings.yml` with the exception of the ``secret_key`` and
  221. the ``bind_address``:
  222. .. code-block:: yaml
  223. use_default_settings: True
  224. server:
  225. secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA"
  226. bind_address: "0.0.0.0"
  227. ``engines:``
  228. With ``use_default_settings: True``, each settings can be override in a
  229. similar way, the ``engines`` section is merged according to the engine
  230. ``name``. In this example, searx will load all the engine and the arch linux
  231. wiki engine has a :ref:`token<private engines>`:
  232. .. code-block:: yaml
  233. use_default_settings: True
  234. server:
  235. secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA"
  236. engines:
  237. - name: arch linux wiki
  238. tokens: ['$ecretValue']
  239. ``engines:`` / ``remove:``
  240. It is possible to remove some engines from the default settings. The following
  241. example is similar to the above one, but searx doesn't load the the google
  242. engine:
  243. .. code-block:: yaml
  244. use_default_settings:
  245. engines:
  246. remove:
  247. - google
  248. server:
  249. secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA"
  250. engines:
  251. - name: arch linux wiki
  252. tokens: ['$ecretValue']
  253. ``engines:`` / ``keep_only:``
  254. As an alternative, it is possible to specify the engines to keep. In the
  255. following example, searx has only two engines:
  256. .. code-block:: yaml
  257. use_default_settings:
  258. engines:
  259. keep_only:
  260. - google
  261. - duckduckgo
  262. server:
  263. secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA"
  264. engines:
  265. - name: google
  266. tokens: ['$ecretValue']
  267. - name: duckduckgo
  268. tokens: ['$ecretValue']