12 KiB
settings.yml
This page describe the options possibilities of the searx/settings.yml
file.
Further reading ..
use_default_settings.yml
search API
Contents
settings.yml location
The initial settings.yml
we be load from these locations:
- the full path specified in the
SEARX_SETTINGS_PATH
environment variable. /etc/searx/settings.yml
If these files don't exist (or are empty or can't be read), SearXNG uses the searx/settings.yml
file. Read settings use_default_settings
to see how you can simplify your user defined settings.yml
.
Global Settings
brand:
brand:
issue_url: https://github.com/searxng/searxng/issues
docs_url: https://searxng/searxng.github.io/searxng
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
)
general:
general:
debug: false # Debug mode, only for development
instance_name: "SearXNG" # displayed name
contact_url: false # mailto:contact@example.com
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.
contact_url
:Contact
mailto:
address or WEB form.
server:
server:
base_url: false # set custom base_url (or false)
port: 8888
bind_address: "127.0.0.1" # address to listen on
secret_key: "ultrasecretkey" # change this!
image_proxy: false # proxying image results through searx
default_locale: "" # default interface locale
default_theme: oscar # ui theme
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
buildenv
Changing a value tagged by buildenv <make buildenv>
, needs to rebuild instance's environment utils/brand.env <make buildenv>
.
base_url
:buildenv SEARX_URL <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 (
utils/brand.env <make buildenv>
)port
&bind_address
:buildenv SEARX_PORT & SEARX_BIND_ADDRESS <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 SearXNG running on Apache or Nginx.secret_key
:$SEARXNG_SECRET
Used for cryptography purpose.
image_proxy
:Allow your instance of SearXNG of being able to proxy images. Uses memory space.
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
.default_theme
:Name of the theme you want to use by default on your SearXNG instance.
default_http_headers
:Set additional HTTP headers, see #755
outgoing:
Communication with search engines.
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: "" # informations 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 proxy
# proxies:
# all://:
# - http://proxy1:8080
# - http://proxy2:8080
# uncomment below section only if you have more than one network interface
# which can be the source of outgoing search requests
# source_ips:
# - 1.1.1.1
# - 1.1.1.2
# - fe80::/126
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
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.
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 addressesfe80::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.max_redirects
:30 by default. Maximum redirect before it is an error.
Engine settings
Further reading ..
configured engines
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.
- name: example engine
engine: example
shortcut: demo
base_url: 'https://{language}.example.com/'
categories: general
timeout: 3.0
api_key: 'apikey'
disabled: false
language: en_US
tokens: [ 'my-secret-token' ]
weigth: 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
or?bi
)base_url
: optionalPart 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.
categories
: optionalDefine in which categories this engine will be active. Most of the time, it is defined in the code of the engine, but in a few cases it is useful, like when describing multiple search engine using the same code.
timeout
: optionalTimeout of the search with the current search engine. Be careful, it will modify the global timeout of searx.
api_key
: optionalIn a few cases, using an API needs the use of a secret key. How to obtain them is described in the file.
disabled
: optionalTo disable by default the engine, but not deleting it. It will allow the user to manually activate it in the settings.
language
: optionalIf you want to use another language for a specific engine, you can define it by using the full ISO code of language and country, like
fr_FR
,en_US
,de_DE
.tokens
: optionalA list of secret tokens to make this engine private, more details see
private engines
.weigth
: default1
Weighting of the results of this engine.
display_error_messages
: defaulttrue
When an engine returns an error, the message is displayed on the user interface.
network
: optionalUse the network configuration from another engine. In addition, there are two default networks: *
ipv4
setlocal_addresses
to0.0.0.0
(use only IPv4 local addresses) *ipv6
setlocal_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.
use_default_settings
use_default_settings: true
settings location
use_default_settings.yml
/etc/searx/settings.yml <utils/templates/etc/searx/use_default_settings.yml>
The user defined settings.yml
is loaded from the settings location
and can relied on the default configuration searx/settings.yml
using:
use_default_settings: true
server:
In the following example, the actual settings are the default settings defined in
searx/settings.yml
with the exception of thesecret_key
and thebind_address
: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, theengines
section is merged according to the enginename
. In this example, SearXNG will load all the engine and the arch linux wiki engine has atoken <private engines>
:use_default_settings: true server: secret_key: "ultrasecretkey" # change this! engines: - name: arch linux wiki tokens: ['$ecretValue']
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:
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:
use_default_settings: engines: keep_only: - google - duckduckgo server: secret_key: "ultrasecretkey" # change this! engines: - name: google tokens: ['$ecretValue'] - name: duckduckgo tokens: ['$ecretValue']