summaryrefslogtreecommitdiff
path: root/docs/admin/engines/settings.rst
blob: f9a1dad4f4f3143cea64c5f68b65742543416f67 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
.. _settings.yml:

================
``settings.yml``
================

This page describe the options possibilities of the :origin:`searx/settings.yml`
file.

.. sidebar:: Further reading ..

   - :ref:`use_default_settings.yml`
   - :ref:`search API`

.. contents:: Contents
   :depth: 2
   :local:
   :backlinks: entry

.. _settings location:

settings.yml location
=====================

The initial ``settings.yml`` we be load from these locations:

1. the full path specified in the ``SEARXNG_SETTINGS_PATH`` environment variable.
2. ``/etc/searxng/settings.yml``

If these files don't exist (or are empty or can't be read), SearXNG uses the
:origin:`searx/settings.yml` file.  Read :ref:`settings use_default_settings` to
see how you can simplify your *user defined* ``settings.yml``.


.. _settings global:

Global Settings
===============

.. _settings brand:

``brand:``
----------

.. code:: yaml

   brand:
     issue_url: https://github.com/searxng/searxng/issues
     docs_url: https://docs.searxng.org
     public_instances: https://searx.space
     wiki_url: https://github.com/searxng/searxng/wiki

``issue_url`` :
  If you host your own issue tracker change this URL.

``docs_url`` :
  If you host your own documentation change this URL.

``public_instances`` :
  If you host your own https://searx.space change this URL.

``wiki_url`` :
  Link to your wiki (or ``false``)

.. _settings general:

``general:``
------------

.. code:: yaml

   general:
     debug: false
     instance_name:  "SearXNG"
     privacypolicy_url: false
     donation_url: false
     contact_url: false
     enable_metrics: true

``debug`` : ``$SEARXNG_DEBUG``
  Allow a more detailed log if you run SearXNG directly. Display *detailed* error
  messages in the browser too, so this must be deactivated in production.

``donation_url`` :
  Set value to ``true`` to use your own donation page written in the
  :ref:`searx/info/en/donate.md <searx.infopage>` and use ``false`` to disable
  the donation link altogether.

``privacypolicy_url``:
  Link to privacy policy.

``contact_url``:
  Contact ``mailto:`` address or WEB form.

``enable_metrics``:
  Enabled by default. Record various anonymous metrics availabled at ``/stats``,
  ``/stats/errors`` and ``/preferences``.

.. _settings search:

``search:``
-----------

.. code:: yaml

   search:
     safe_search: 0
     autocomplete: ""
     default_lang: ""
     ban_time_on_fail: 5
     max_ban_time_on_fail: 120
     suspended_times:
       SearxEngineAccessDenied: 86400
       SearxEngineCaptcha: 86400
       SearxEngineTooManyRequests: 3600
       cf_SearxEngineCaptcha: 1296000
       cf_SearxEngineAccessDenied: 86400
       recaptcha_SearxEngineCaptcha: 604800
     formats:
       - html

``safe_search``:
  Filter results.

  - ``0``: None
  - ``1``: Moderate
  - ``2``: Strict

``autocomplete``:
  Existing autocomplete backends, leave blank to turn it off.

  - ``dbpedia``
  - ``duckduckgo``
  - ``google``
  - ``startpage``
  - ``swisscows``
  - ``qwant``
  - ``wikipedia``

``default_lang``:
  Default search language - leave blank to detect from browser information or
  use codes from :origin:`searx/languages.py`.

``languages``:
  List of available languages - leave unset to use all codes from
  :origin:`searx/languages.py`.  Otherwise list codes of available languages.
  The ``all`` value is shown as the ``Default language`` in the user interface
  (in most cases, it is meant to send the query without a language parameter ;
  in some cases, it means the English language) Example:

  .. code:: yaml

     languages:
       - all
       - en
       - en-US
       - de
       - it-IT
       - fr
       - fr-BE

``ban_time_on_fail``:
  Ban time in seconds after engine errors.

``max_ban_time_on_fail``:
  Max ban time in seconds after engine errors.

``suspended_times``:
  Engine suspension time after error (in seconds; set to 0 to disable)

  ``SearxEngineAccessDenied``: 86400
    For error "Access denied" and "HTTP error [402, 403]"

  ``SearxEngineCaptcha``: 86400
    For error "CAPTCHA"

  ``SearxEngineTooManyRequests``: 3600
    For error "Too many request" and "HTTP error 429"

  Cloudflare CAPTCHA:
     - ``cf_SearxEngineCaptcha``: 1296000
     - ``cf_SearxEngineAccessDenied``: 86400

  Google CAPTCHA:
    - ``recaptcha_SearxEngineCaptcha``: 604800

``formats``:
  Result formats available from web, remove format to deny access (use lower
  case).

  - ``html``
  - ``csv``
  - ``json``
  - ``rss``


.. _settings server:

``server:``
-----------

.. code:: yaml

   server:
       base_url: http://example.org/location  # change this!
       port: 8888
       bind_address: "127.0.0.1"
       secret_key: "ultrasecretkey"           # change this!
       limiter: false
       image_proxy: false
       default_http_headers:
         X-Content-Type-Options : nosniff
         X-XSS-Protection : 1; mode=block
         X-Download-Options : noopen
         X-Robots-Tag : noindex, nofollow
         Referrer-Policy : no-referrer


``base_url`` : ``$SEARXNG_URL`` :ref:`buildenv <make buildenv>`
  The base URL where SearXNG is deployed.  Used to create correct inbound links.
  If you change the value, don't forget to rebuild instance's environment
  (:ref:`utils/brand.env <make buildenv>`)

``port`` & ``bind_address``: ``$SEARXNG_PORT`` & ``$SEARXNG_BIND_ADDRESS`` :ref:`buildenv <make buildenv>`
  Port number and *bind address* of the SearXNG web application if you run it
  directly using ``python searx/webapp.py``.  Doesn't apply to a SearXNG
  services running behind a proxy and using socket communications.  If you
  change the value, don't forget to rebuild instance's environment
  (:ref:`utils/brand.env <make buildenv>`)

``secret_key`` : ``$SEARXNG_SECRET``
  Used for cryptography purpose.

.. _limiter:

``limiter`` :
  Rate limit the number of request on the instance, block some bots.  The
  :ref:`limiter plugin` requires a :ref:`settings redis` database.

.. _image_proxy:

``image_proxy`` :
  Allow your instance of SearXNG of being able to proxy images.  Uses memory space.

.. _HTTP headers: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers

``default_http_headers`` :
  Set additional HTTP headers, see `#755 <https://github.com/searx/searx/issues/715>`__


.. _settings ui:

``ui:``
-------

.. _cache busting:
   https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#caching_static_assets_with_cache_busting

.. code:: yaml

   ui:
     static_use_hash: false
     default_locale: ""
     query_in_title: false
     infinite_scroll: false
     center_alignment: false
     cache_url: https://web.archive.org/web/
     default_theme: simple
     theme_args:
       simple_style: auto

.. _static_use_hash:

``static_use_hash`` :
  Enables `cache busting`_ of static files.

``default_locale`` :
  SearXNG interface language.  If blank, the locale is detected by using the
  browser language.  If it doesn't work, or you are deploying a language
  specific instance of searx, a locale can be defined using an ISO language
  code, like ``fr``, ``en``, ``de``.

``query_in_title`` :
  When true, the result page's titles contains the query it decreases the
  privacy, since the browser can records the page titles.

``infinite_scroll``:
  When true, automatically loads the next page when scrolling to bottom of the current page.

``center_alignment`` : default ``false``
  When enabled, the results are centered instead of being in the left (or RTL)
  side of the screen.  This setting only affects the *desktop layout*
  (:origin:`min-width: @tablet <searx/static/themes/simple/src/less/definitions.less>`)

.. cache_url:

``cache_url`` : ``https://web.archive.org/web/``
  URL prefix of the internet archive or cache, don't forgett trailing slash (if
  needed).  The default is https://web.archive.org/web/ alternatives are:

  - https://webcache.googleusercontent.com/search?q=cache:
  - https://archive.today/

``default_theme`` :
  Name of the theme you want to use by default on your SearXNG instance.

``theme_args.simple_style``:
  Style of simple theme: ``auto``, ``light``, ``dark``

``results_on_new_tab``:
  Open result links in a new tab by default.

.. _settings redis:

``redis:``
----------

.. _Redis.from_url(url): https://redis-py.readthedocs.io/en/stable/connections.html#redis.client.Redis.from_url

A redis DB can be connected by an URL, in :py:obj:`searx.redisdb` you
will find a description to test your redis connection in SerXNG.  When using
sockets, don't forget to check the access rights on the socket::

  ls -la /usr/local/searxng-redis/run/redis.sock
  srwxrwx--- 1 searxng-redis searxng-redis ... /usr/local/searxng-redis/run/redis.sock

In this example read/write access is given to the *searxng-redis* group.  To get
access rights to redis instance (the socket), your SearXNG (or even your
developer) account needs to be added to the *searxng-redis* group.

``url``
  URL to connect redis database, see `Redis.from_url(url)`_ & :ref:`redis db`::

    redis://[[username]:[password]]@localhost:6379/0
    rediss://[[username]:[password]]@localhost:6379/0
    unix://[[username]:[password]]@/path/to/socket.sock?db=0

.. admonition:: Tip for developers

   To set up a local redis instance, first set the socket path of the Redis DB
   in your YAML setting:

   .. code:: yaml

      redis:
        url: unix:///usr/local/searxng-redis/run/redis.sock?db=0

   Then use the following commands to install the redis instance ::

     $ ./manage redis.build
     $ sudo -H ./manage redis.install
     $ sudo -H ./manage redis.addgrp "${USER}"
     # don't forget to logout & login to get member of group


.. _settings outgoing:

``outgoing:``
-------------

Communication with search engines.

.. code:: yaml

   outgoing:
     request_timeout: 2.0       # default timeout in seconds, can be override by engine
     max_request_timeout: 10.0  # the maximum timeout in seconds
     useragent_suffix: ""       # information like an email address to the administrator
     pool_connections: 100      # Maximum number of allowable connections, or null
                                # for no limits. The default is 100.
     pool_maxsize: 10           # Number of allowable keep-alive connections, or null
                                # to always allow. The default is 10.
     enable_http2: true         # See https://www.python-httpx.org/http2/
     # uncomment below section if you want to use a custom server certificate
     # see https://www.python-httpx.org/advanced/#changing-the-verification-defaults
     # and https://www.python-httpx.org/compatibility/#ssl-configuration
     #  verify: ~/.mitmproxy/mitmproxy-ca-cert.cer
     #
     # uncomment below section if you want to use a proxyq see: SOCKS proxies
     #   https://2.python-requests.org/en/latest/user/advanced/#proxies
     # are also supported: see
     #   https://2.python-requests.org/en/latest/user/advanced/#socks
     #
     #  proxies:
     #    all://:
     #      - http://proxy1:8080
     #      - http://proxy2:8080
     #
     #  using_tor_proxy: true
     #
     # Extra seconds to add in order to account for the time taken by the proxy
     #
     #  extra_proxy_timeout: 10.0
     #

``request_timeout`` :
  Global timeout of the requests made to others engines in seconds.  A bigger
  timeout will allow to wait for answers from slow engines, but in consequence
  will slow SearXNG reactivity (the result page may take the time specified in the
  timeout to load). Can be override by :ref:`settings engine`

``useragent_suffix`` :
  Suffix to the user-agent SearXNG uses to send requests to others engines.  If an
  engine wish to block you, a contact info here may be useful to avoid that.

``keepalive_expiry`` :
  Number of seconds to keep a connection in the pool. By default 5.0 seconds.

.. _httpx proxies: https://www.python-httpx.org/advanced/#http-proxying

``proxies`` :
  Define one or more proxies you wish to use, see `httpx proxies`_.
  If there are more than one proxy for one protocol (http, https),
  requests to the engines are distributed in a round-robin fashion.

``source_ips`` :
  If you use multiple network interfaces, define from which IP the requests must
  be made. Example:

  * ``0.0.0.0`` any local IPv4 address.
  * ``::`` any local IPv6 address.
  * ``192.168.0.1``
  * ``[ 192.168.0.1, 192.168.0.2 ]`` these two specific IP addresses
  * ``fe80::60a2:1691:e5a2:ee1f``
  * ``fe80::60a2:1691:e5a2:ee1f/126`` all IP addresses in this network.
  * ``[ 192.168.0.1, fe80::/126 ]``

``retries`` :
  Number of retry in case of an HTTP error.  On each retry, SearXNG uses an
  different proxy and source ip.

``retry_on_http_error`` :
  Retry request on some HTTP status code.

  Example:

  * ``true`` : on HTTP status code between 400 and 599.
  * ``403`` : on HTTP status code 403.
  * ``[403, 429]``: on HTTP status code 403 and 429.

``enable_http2`` :
  Enable by default. Set to ``false`` to disable HTTP/2.

.. _httpx verification defaults: https://www.python-httpx.org/advanced/#changing-the-verification-defaults
.. _httpx ssl configuration: https://www.python-httpx.org/compatibility/#ssl-configuration

``verify``: : ``$SSL_CERT_FILE``, ``$SSL_CERT_DIR``
  Allow to specify a path to certificate.
  see `httpx verification defaults`_.

  In addition to ``verify``, SearXNG supports the ``$SSL_CERT_FILE`` (for a file) and
  ``$SSL_CERT_DIR`` (for a directory) OpenSSL variables.
  see `httpx ssl configuration`_.

``max_redirects`` :
  30 by default. Maximum redirect before it is an error.


.. _settings categories_as_tabs:

``categories_as_tabs:``
-----------------------

A list of the categories that are displayed as tabs in the user interface.
Categories not listed here can still be searched with the :ref:`search-syntax`.

.. code-block:: yaml

  categories_as_tabs:
    general:
    images:
    videos:
    news:
    map:
    music:
    it:
    science:
    files:
    social media:

Engines are added to ``categories:`` (compare :ref:`engine categories`), the
categories listed in ``categories_as_tabs`` are shown as tabs in the UI.  If
there are no active engines in a category, the tab is not displayed (e.g. if a
user disables all engines in a category).

On the preferences page (``/preferences``) -- under *engines* -- there is an
additional tab, called *other*.  In this tab are all engines listed that are not
in one of the UI tabs (not included in ``categories_as_tabs``).

.. _settings engine:

Engine settings
===============

.. sidebar:: Further reading ..

   - :ref:`configured engines`
   - :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

   - name: example engine
     engine: example
     shortcut: demo
     base_url: 'https://{language}.example.com/'
     send_accept_language_header: false
     categories: general
     timeout: 3.0
     api_key: 'apikey'
     disabled: false
     language: en_US
     tokens: [ 'my-secret-token' ]
     weight: 1
     display_error_messages: true
     about:
        website: https://example.com
        wikidata_id: Q306656
        official_api_documentation: https://example.com/api-doc
        use_official_api: true
        require_api_key: true
        results: HTML
     enable_http: false
     enable_http2: false
     retries: 1
     retry_on_http_error: true # or 403 or [404, 429]
     max_connections: 100
     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 that will be used across SearXNG to define this engine.  In settings, on
  the result page...

``engine`` :
  Name of the python file used to handle requests and responses to and from this
  search engine.

``shortcut`` :
  Code used to execute bang requests (in this case using ``!bi``)

``base_url`` : optional
  Part of the URL that should be stable across every request.  Can be useful to
  use multiple sites using only one engine, or updating the site URL without
  touching at the code.

``send_accept_language_header`` :
  Several engines that support languages (or regions) deal with the HTTP header
  ``Accept-Language`` to build a response that fits to the locale.  When this
  option is activated, the language (locale) that is selected by the user is used
  to build and send a ``Accept-Language`` header in the request to the origin
  search engine.

.. _engine categories:

``categories`` : optional
  Specifies to which categories the engine should be added.  Engines can be
  assigned to multiple categories.

  Categories can be shown as tabs (:ref:`settings categories_as_tabs`) in the
  UI.  A search in a tab (in the UI) will query all engines that are active in
  this tab.  In the preferences page (``/preferences``) -- under *engines* --
  users can select what engine should be active when querying in this tab.

  Alternatively, :ref:`\!bang <search-syntax>` can be used to search all engines
  in a category, regardless of whether they are active or not, or whether they
  are in a tab of the UI or not.  For example, ``!dictionaries`` can be used to
  query all search engines in that category (group).

``timeout`` : optional
  Timeout of the search with the current search engine.  **Be careful, it will
  modify the global timeout of SearXNG.**

``api_key`` : optional
  In a few cases, using an API needs the use of a secret key.  How to obtain them
  is described in the file.

``disabled`` : optional
  To disable by default the engine, but not deleting it.  It will allow the user
  to manually activate it in the settings.

``inactive``: optional
  Remove the engine from the settings (*disabled & removed*).

``language`` : optional
  If you want to use another language for a specific engine, you can define it
  by using the ISO code of language (and region), like ``fr``, ``en-US``,
  ``de-DE``.

``tokens`` : optional
  A list of secret tokens to make this engine *private*, more details see
  :ref:`private engines`.

``weight`` : default ``1``
  Weighting of the results of this engine.

``display_error_messages`` : default ``true``
  When an engine returns an error, the message is displayed on the user interface.

``network`` : optional
  Use the network configuration from another engine.
  In addition, there are two default networks:

  - ``ipv4`` set ``local_addresses`` to ``0.0.0.0`` (use only IPv4 local addresses)
  - ``ipv6`` set ``local_addresses`` to ``::`` (use only IPv6 local addresses)

.. note::

   A few more options are possible, but they are pretty specific to some
   engines, and so won't be described here.


Example: Multilingual Search
----------------------------

SearXNG does not support true multilingual search.  You have to use the language
prefix in your search query when searching in a different language.

But there is a workaround: By adding a new search engine with a different
language, SearXNG will search in your default and other language.

Example configuration in settings.yml for a German and English speaker:

.. code-block:: yaml

    search:
        default_lang : "de"
        ...

    engines:
      - name : google english
        engine : google
        language : en
        ...

When searching, the default google engine will return German results and
"google english" will return English results.


.. _settings use_default_settings:

use_default_settings
====================

.. sidebar:: ``use_default_settings: true``

   - :ref:`settings location`
   - :ref:`use_default_settings.yml`
   - :origin:`/etc/searxng/settings.yml <utils/templates/etc/searxng/settings.yml>`

The user defined ``settings.yml`` is loaded from the :ref:`settings location`
and can relied on the default configuration :origin:`searx/settings.yml` using:

 ``use_default_settings: true``

``server:``
  In the following example, the actual settings are the default settings defined
  in :origin:`searx/settings.yml` with the exception of the ``secret_key`` and
  the ``bind_address``:

  .. code-block:: yaml

    use_default_settings: true
    server:
        secret_key: "ultrasecretkey"   # change this!
        bind_address: "0.0.0.0"

``engines:``
  With ``use_default_settings: true``, each settings can be override in a
  similar way, the ``engines`` section is merged according to the engine
  ``name``.  In this example, SearXNG will load all the default engines, will
  enable the ``bing`` engine and define a :ref:`token <private engines>` for
  the arch linux engine:

  .. code-block:: yaml

    use_default_settings: true
    server:
      secret_key: "ultrasecretkey"   # change this!
    engines:
      - name: arch linux wiki
        tokens: ['$ecretValue']
      - name: bing
        disabled: false


``engines:`` / ``remove:``
  It is possible to remove some engines from the default settings. The following
  example is similar to the above one, but SearXNG doesn't load the the google
  engine:

  .. code-block:: yaml

    use_default_settings:
      engines:
        remove:
          - google
    server:
      secret_key: "ultrasecretkey"   # change this!
    engines:
      - name: arch linux wiki
        tokens: ['$ecretValue']

``engines:`` / ``keep_only:``
  As an alternative, it is possible to specify the engines to keep. In the
  following example, SearXNG has only two engines:

  .. code-block:: yaml

    use_default_settings:
      engines:
        keep_only:
          - google
          - duckduckgo
    server:
      secret_key: "ultrasecretkey"   # change this!
    engines:
      - name: google
        tokens: ['$ecretValue']
      - name: duckduckgo
        tokens: ['$ecretValue']