This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<spanid="settings-engine"></span><h1><codeclass="docutils literal notranslate"><spanclass="pre">engine:</span></code><aclass="headerlink"href="#engine"title="Link to this heading">¶</a></h1>
<spanclass="w"></span><spanclass="nt">retry_on_http_error</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">true</span><spanclass="w"></span><spanclass="c1"># or 403 or [404, 429]</span>
</pre></div>
</div>
<dlclass="simple">
<dt><codeclass="docutils literal notranslate"><spanclass="pre">name</span></code> :</dt><dd><p>Name that will be used across SearXNG to define this engine. In settings, on
the result page…</p>
</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">engine</span></code> :</dt><dd><p>Name of the python file used to handle requests and responses to and from this
search engine.</p>
</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">shortcut</span></code> :</dt><dd><p>Code used to execute bang requests (in this case using <codeclass="docutils literal notranslate"><spanclass="pre">!bi</span></code>)</p>
</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">base_url</span></code><spanclass="classifier">optional</span></dt><dd><p>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.</p>
</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">send_accept_language_header</span></code> :</dt><dd><p>Several engines that support languages (or regions) deal with the HTTP header
<codeclass="docutils literal notranslate"><spanclass="pre">Accept-Language</span></code> 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 <codeclass="docutils literal notranslate"><spanclass="pre">Accept-Language</span></code> header in the request to the origin
search engine.</p>
</dd>
</dl>
<dlid="engine-categories">
<dt><codeclass="docutils literal notranslate"><spanclass="pre">categories</span></code><spanclass="classifier">optional</span></dt><dd><p>Specifies to which categories the engine should be added. Engines can be
assigned to multiple categories.</p>
<p>Categories can be shown as tabs (<aclass="reference internal"href="settings_categories_as_tabs.html#settings-categories-as-tabs"><spanclass="std std-ref">categories_as_tabs:</span></a>) 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 (<codeclass="docutils literal notranslate"><spanclass="pre">/preferences</span></code>) – under <em>engines</em>–
users can select what engine should be active when querying in this tab.</p>
<p>Alternatively, <aclass="reference internal"href="../../user/search-syntax.html#search-syntax"><spanclass="std std-ref">!bang</span></a> 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, <codeclass="docutils literal notranslate"><spanclass="pre">!dictionaries</span></code> can be used to
query all search engines in that category (group).</p>
</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">timeout</span></code><spanclass="classifier">optional</span></dt><dd><p>Timeout of the search with the current search engine. Overwrites
<codeclass="docutils literal notranslate"><spanclass="pre">request_timeout</span></code> from <aclass="reference internal"href="settings_outgoing.html#settings-outgoing"><spanclass="std std-ref">outgoing:</span></a>. <strong>Be careful, it will
modify the global timeout of SearXNG.</strong></p>
</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">api_key</span></code><spanclass="classifier">optional</span></dt><dd><p>In a few cases, using an API needs the use of a secret key. How to obtain them
is described in the file.</p>
</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">disabled</span></code><spanclass="classifier">optional</span></dt><dd><p>To disable by default the engine, but not deleting it. It will allow the user
to manually activate it in the settings.</p>
</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">inactive</span></code>: optional</dt><dd><p>Remove the engine from the settings (<em>disabled & removed</em>).</p>
</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">language</span></code><spanclass="classifier">optional</span></dt><dd><p>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 <codeclass="docutils literal notranslate"><spanclass="pre">fr</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">en-US</span></code>,
<dt><codeclass="docutils literal notranslate"><spanclass="pre">tokens</span></code><spanclass="classifier">optional</span></dt><dd><p>A list of secret tokens to make this engine <em>private</em>, more details see
<dt><codeclass="docutils literal notranslate"><spanclass="pre">weight</span></code><spanclass="classifier">default <codeclass="docutils literal notranslate"><spanclass="pre">1</span></code></span></dt><dd><p>Weighting of the results of this engine.</p>
</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">display_error_messages</span></code><spanclass="classifier">default <codeclass="docutils literal notranslate"><spanclass="pre">true</span></code></span></dt><dd><p>When an engine returns an error, the message is displayed on the user interface.</p>
</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">network</span></code><spanclass="classifier">optional</span></dt><dd><p>Use the network configuration from another engine.
In addition, there are two default networks:</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">ipv4</span></code> set <codeclass="docutils literal notranslate"><spanclass="pre">local_addresses</span></code> to <codeclass="docutils literal notranslate"><spanclass="pre">0.0.0.0</span></code> (use only IPv4 local addresses)</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">ipv6</span></code> set <codeclass="docutils literal notranslate"><spanclass="pre">local_addresses</span></code> to <codeclass="docutils literal notranslate"><spanclass="pre">::</span></code> (use only IPv6 local addresses)</p></li>
</ul>
</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">enable_http</span></code><spanclass="classifier">optional</span></dt><dd><p>Enable HTTP for this engine (by default only HTTPS is enabled).</p>
</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">retry_on_http_error</span></code><spanclass="classifier">optional</span></dt><dd><p>Retry request on some HTTP status code.</p>
<p>Example:</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">true</span></code> : on HTTP status code between 400 and 599.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">403</span></code> : on HTTP status code 403.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">[403,</span><spanclass="pre">429]</span></code>: on HTTP status code 403 and 429.</p></li>
</ul>
</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">proxies</span></code> :</dt><dd><p>Overwrites proxy settings from <aclass="reference internal"href="settings_outgoing.html#settings-outgoing"><spanclass="std std-ref">outgoing:</span></a>.</p>
</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">using_tor_proxy</span></code> :</dt><dd><p>Using tor proxy (<codeclass="docutils literal notranslate"><spanclass="pre">true</span></code>) or not (<codeclass="docutils literal notranslate"><spanclass="pre">false</span></code>) for this engine. The default is
taken from <codeclass="docutils literal notranslate"><spanclass="pre">using_tor_proxy</span></code> of the <aclass="reference internal"href="settings_outgoing.html#settings-outgoing"><spanclass="std std-ref">outgoing:</span></a>.</p>
<dt><aclass="reference external"href="https://www.python-httpx.org/advanced/#pool-limit-configuration">Pool limit configuration</a>, overwrites value <codeclass="docutils literal notranslate"><spanclass="pre">pool_maxsize</span></code> from</dt><dd><p><aclass="reference internal"href="settings_outgoing.html#settings-outgoing"><spanclass="std std-ref">outgoing:</span></a> for this engine.</p>
</dd>
</dl>
</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">max_connections</span></code> :</dt><dd><p><aclass="reference external"href="https://www.python-httpx.org/advanced/#pool-limit-configuration">Pool limit configuration</a>, overwrites value <codeclass="docutils literal notranslate"><spanclass="pre">pool_connections</span></code> from
<aclass="reference internal"href="settings_outgoing.html#settings-outgoing"><spanclass="std std-ref">outgoing:</span></a> for this engine.</p>
</dd>
<dt><codeclass="docutils literal notranslate"><spanclass="pre">keepalive_expiry</span></code> :</dt><dd><p><aclass="reference external"href="https://www.python-httpx.org/advanced/#pool-limit-configuration">Pool limit configuration</a>, overwrites value <codeclass="docutils literal notranslate"><spanclass="pre">keepalive_expiry</span></code> from
<aclass="reference internal"href="settings_outgoing.html#settings-outgoing"><spanclass="std std-ref">outgoing:</span></a> for this engine.</p>
</dd>
</dl>
<sectionid="private-engines-tokens">
<spanid="private-engines"></span><h2>Private Engines (<codeclass="docutils literal notranslate"><spanclass="pre">tokens</span></code>)<aclass="headerlink"href="#private-engines-tokens"title="Link to this heading">¶</a></h2>
<p>Administrators might find themselves wanting to limit access to some of the
enabled engines on their instances. It might be because they do not want to
expose some private information through <aclass="reference internal"href="../../dev/engines/index.html#offline-engines"><spanclass="std std-ref">Offline Engines</span></a>. Or they would
rather share engines only with their trusted friends or colleagues.</p>
<asideclass="sidebar">
<pclass="sidebar-title">info</p>
<p>Initial sponsored by <aclass="reference external"href="https://nlnet.nl/discovery">Search and Discovery Fund</a> of <aclass="reference external"href="https://nlnet.nl/">NLnet Foundation</a>.</p>
</aside>
<p>To solve this issue the concept of <em>private engines</em> exists.</p>
<p>A new option was added to engines named <cite>tokens</cite>. It expects a list of strings.
If the user making a request presents one of the tokens of an engine, they can
access information about the engine and make search requests.</p>
<p>Example configuration to restrict access to the Arch Linux Wiki engine:</p>
<divclass="highlight-yaml notranslate"><divclass="highlight"><pre><span></span><spanclass="p p-Indicator">-</span><spanclass="w"></span><spanclass="nt">name</span><spanclass="p">:</span><spanclass="w"></span><spanclass="l l-Scalar l-Scalar-Plain">arch linux wiki</span>