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.
<p>Activating the favicons in SearXNG is very easy, but this <strong>generates a
significantly higher load</strong> in the client/server communication and increases
resources needed on the server.</p>
<p>To mitigate these disadvantages, various methods have been implemented,
including a <em>cache</em>. The cache must be parameterized according to your own
requirements and maintained regularly.</p>
<p>To activate favicons in SearXNG’s result list, set a default
<codeclass="docutils literal notranslate"><spanclass="pre">favicon_resolver</span></code> in the <aclass="reference internal"href="settings/settings_search.html#settings-search"><spanclass="std std-ref">search</span></a> settings:</p>
<p>With the above setting favicons are displayed, the user has the option to
deactivate this feature in his settings. If the user is to have the option of
selecting from several <em>resolvers</em>, a further setting is required / but this
setting will be discussed <aclass="reference internal"href="#register-resolvers"><spanclass="std std-ref">later</span></a> in this article,
first we have to setup the favicons cache.</p>
<sectionid="infrastructure">
<h2><aclass="toc-backref"href="#id3"role="doc-backlink">Infrastructure</a><aclass="headerlink"href="#infrastructure"title="Link to this heading">¶</a></h2>
<p>The infrastructure for providing the favicons essentially consists of three
<p>To protect the privacy of users, the favicons are provided via a <em>proxy</em>. This
<em>proxy</em> is automatically activated with the above activation of a <em>resolver</em>.
Additional requests are required to provide the favicons: firstly, the <em>proxy</em>
must process the incoming requests and secondly, the <em>resolver</em> must make
outgoing requests to obtain the favicons from external sources.</p>
<p>A <em>cache</em> has been developed to massively reduce both, incoming and outgoing
requests. This <em>cache</em> is also activated automatically with the above
activation of a <em>resolver</em>. In its defaults, however, the <em>cache</em> is minimal
and not well suitable for a production environment!</p>
</section>
<sectionid="setting-up-the-cache">
<spanid="favicon-cache-setup"></span><h2><aclass="toc-backref"href="#id4"role="doc-backlink">Setting up the cache</a><aclass="headerlink"href="#setting-up-the-cache"title="Link to this heading">¶</a></h2>
<p>To parameterize the <em>cache</em> and more settings of the favicons infrastructure, a
<aclass="reference external"href="https://toml.io/en/">TOML</a> configuration is created in the file <codeclass="docutils literal notranslate"><spanclass="pre">/etc/searxng/favicons.toml</span></code>.</p>
<spanclass="n">cfg_schema</span><spanclass="w"></span><spanclass="o">=</span><spanclass="w"></span><spanclass="mi">1</span><spanclass="w"></span><spanclass="c1"># config's schema version no.</span>
<dt><aclass="reference internal"href="../src/searx.favicons.html#searx.favicons.config.FaviconConfig.cfg_schema"title="searx.favicons.config.FaviconConfig.cfg_schema"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">cfg_schema</span></code></a>:</dt><dd><p>Is required to trigger any processes required for future upgrades / don’t
change it.</p>
</dd>
<dt><aclass="reference internal"href="../src/searx.favicons.html#searx.favicons.cache.FaviconCacheConfig.db_url"title="searx.favicons.cache.FaviconCacheConfig.db_url"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">cache.db_url</span></code></a>:</dt><dd><p>The path to the (<aclass="reference external"href="https://www.sqlite.org/">SQLite</a>) database file. The default path is in the <aclass="reference external"href="https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch03s18.html">/tmp</a>
folder, which is deleted on every reboot and is therefore unsuitable for a
production environment. The <aclass="reference external"href="https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html">FHS</a> provides the folder for the
application cache</p>
<p>The <aclass="reference external"href="https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html">FHS</a> provides the folder <aclass="reference external"href="https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch05s05.html">/var/cache</a> for the cache of applications, so a
suitable storage location of SearXNG’s caches is folder <codeclass="docutils literal notranslate"><spanclass="pre">/var/cache/searxng</span></code>.
In container systems, a volume should be mounted for this folder and in a
standard installation (compare <aclass="reference internal"href="installation-searxng.html#create-searxng-user"><spanclass="std std-ref">Create user</span></a>), the folder must be
created and the user under which the SearXNG process is running must be given
<dt><aclass="reference internal"href="../src/searx.favicons.html#searx.favicons.cache.FaviconCacheConfig.LIMIT_TOTAL_BYTES"title="searx.favicons.cache.FaviconCacheConfig.LIMIT_TOTAL_BYTES"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">cache.LIMIT_TOTAL_BYTES</span></code></a>:</dt><dd><p>Maximum of bytes stored in the cache of all blobs. The limit is only reached
at each maintenance interval after which the oldest BLOBs are deleted; the
limit is exceeded during the maintenance period.</p>
<divclass="admonition attention">
<pclass="admonition-title">Attention</p>
<p>If the maintenance period is too long or maintenance is switched
off completely, the cache grows uncontrollably.</p>
</div>
</dd>
</dl>
<p>SearXNG hosters can change other parameters of the cache as required:</p>
<h3><aclass="toc-backref"href="#id5"role="doc-backlink">Maintenance of the cache</a><aclass="headerlink"href="#maintenance-of-the-cache"title="Link to this heading">¶</a></h3>
<p>Regular maintenance of the cache is required! By default, regular maintenance
is triggered automatically as part of the client requests:</p>
<spanid="favicon-proxy-setup"></span><h2><aclass="toc-backref"href="#id6"role="doc-backlink">Proxy configuration</a><aclass="headerlink"href="#proxy-configuration"title="Link to this heading">¶</a></h2>
<p>Most of the options of the <aclass="reference internal"href="../src/searx.favicons.html#module-searx.favicons.proxy"title="searx.favicons.proxy"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Favicons-Proxy</span></code></a> are
already set sensibly with settings from the <aclass="reference internal"href="settings/index.html#searxng-settings-yml"><spanclass="std std-ref">settings.yml</span></a> and should not normally be adjusted.</p>
<spanclass="n">max_age</span><spanclass="w"></span><spanclass="o">=</span><spanclass="w"></span><spanclass="mi">5184000</span><spanclass="w"></span><spanclass="c1"># 60 days / default: 7 days (604800 sec)</span>
</pre></div>
</div>
<dlclass="simple">
<dt><aclass="reference internal"href="../src/searx.favicons.html#searx.favicons.proxy.FaviconProxyConfig.max_age"title="searx.favicons.proxy.FaviconProxyConfig.max_age"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">max_age</span></code></a>:</dt><dd><p>The <aclass="reference external"href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#response_directives">HTTP Cache-Control max-age</a> response directive indicates that the
response remains fresh until N seconds after the response is generated. This
setting therefore determines how long a favicon remains in the client’s cache.
As a rule, in the favicons infrastructure of SearXNG’s this setting only
affects favicons whose byte size exceeds <aclass="reference internal"href="#favicon-cache-setup"><spanclass="std std-ref">BLOB_MAX_BYTES</span></a> (the other favicons that are already in the cache are embedded as
<aclass="reference external"href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs">data URL</a> in the <aclass="reference internal"href="../src/searx.favicons.html#searx.favicons.proxy.favicon_url"title="searx.favicons.proxy.favicon_url"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">generated</span><spanclass="pre">HTML</span></code></a>,
which can greatly reduce the number of additional requests).</p>
</dd>
</dl>
<sectionid="register-resolvers">
<spanid="id2"></span><h3><aclass="toc-backref"href="#id7"role="doc-backlink">Register resolvers</a><aclass="headerlink"href="#register-resolvers"title="Link to this heading">¶</a></h3>
<p>A <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">resolver</span></code> is a function that obtains the favicon
from an external source. The resolver functions available to the user are
registered with their fully qualified name (<aclass="reference external"href="https://en.wikipedia.org/wiki/Fully_qualified_name">FQN</a>) in a <codeclass="docutils literal notranslate"><spanclass="pre">resolver_map</span></code>.</p>
<p>If no <codeclass="docutils literal notranslate"><spanclass="pre">resolver_map</span></code> is defined in the <codeclass="docutils literal notranslate"><spanclass="pre">favicon.toml</span></code>, the favicon
infrastructure of SearXNG generates this <codeclass="docutils literal notranslate"><spanclass="pre">resolver_map</span></code> automatically
depending on the <codeclass="docutils literal notranslate"><spanclass="pre">settings.yml</span></code>. SearXNG would automatically generate the
following TOML configuration from the following YAML configuration:</p>
<p>With each resolver, the resource requirement increases significantly.</p>
</div>
<p>The number of resolvers increases:</p>
<ulclass="simple">
<li><p>the number of incoming/outgoing requests and</p></li>
<li><p>the number of favicons to be stored in the cache.</p></li>
</ul>
<p>In the following we list the resolvers available in the core of SearXNG, but via
the <aclass="reference external"href="https://en.wikipedia.org/wiki/Fully_qualified_name">FQN</a> it is also possible to implement your own resolvers and integrate them