[doc] rearranges Settings & Engines docs for better readability

   If you have any contribution send us your :pull:`PR <../pulls>`, see

   :ref:`how to contribute`.

.. contents:: Contents

.. contents::

   :depth: 2

   :local:

   :backlinks: entry

.. _engine command:

====================

Command Line Engines

====================

.. sidebar:: info

   - :origin:`command.py <searx/engines/command.py>`

   - :ref:`offline engines`

With *command engines* administrators can run engines to integrate arbitrary

shell commands.

When creating and enabling a ``command`` engine on a public instance, you must

be careful to avoid leaking private data.  The easiest solution is to limit the

access by setting ``tokens`` as described in section :ref:`private engines`.

The engine base is flexible.  Only your imagination can limit the power of this

engine (and maybe security concerns).  The following options are available:

``command``:

  A comma separated list of the elements of the command.  A special token

  ``{{QUERY}}`` tells where to put the search terms of the user. Example:

  .. code:: yaml

     ['ls', '-l', '-h', '{{QUERY}}']

``delimiter``:

  A mapping containing a delimiter ``char`` and the *titles* of each element in

  ``keys``.

``parse_regex``:

  A dict containing the regular expressions for each result key.

``query_type``:

  The expected type of user search terms.  Possible values: ``path`` and

  ``enum``.

  ``path``:

    Checks if the user provided path is inside the working directory.  If not,

    the query is not executed.

  ``enum``:

    Is a list of allowed search terms.  If the user submits something which is

    not included in the list, the query returns an error.

``query_enum``:

  A list containing allowed search terms if ``query_type`` is set to ``enum``.

``working_dir``:

  The directory where the command has to be executed.  Default: ``./``

``result_separator``:

  The character that separates results. Default: ``\n``

The example engine below can be used to find files with a specific name in the

configured working directory:

.. code:: yaml

  - name: find

    engine: command

    command: ['find', '.', '-name', '{{QUERY}}']

    query_type: path

    shortcut: fnd

    delimiter:

        chars: ' '

        keys: ['line']

Acknowledgment

==============

This development was sponsored by `Search and Discovery Fund

<https://nlnet.nl/discovery>`_ of `NLnet Foundation <https://nlnet.nl/>`_.

.. _engines and settings:

==================

Engines & Settings

==================

.. sidebar:: Further reading ..

   - :ref:`settings engine`

   - :ref:`engine settings` & :ref:`engine file`

.. toctree::

   :maxdepth: 3

   settings

.. toctree::

   :maxdepth: 1

   private-engines

   recoll

   sql-engines

   nosql-engines

   search-indexer-engines

   command-line-engines

   searx.engines.xpath

.. _private engines:

============================

Private Engines (``tokens``)

============================

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 :ref:`offline engines`.  Or they would

rather share engines only with their trusted friends or colleagues.

To solve this issue the concept of *private engines* exists.

A new option was added to engines named `tokens`. 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.

Example configuration to restrict access to the Arch Linux Wiki engine:

.. code:: yaml

  - name: arch linux wiki

    engine: archlinux

    shortcut: al

    tokens: [ 'my-secret-token' ]

Unless a user has configured the right token, the engine is going

to be hidden from him/her. It is not going to be included in the

list of engines on the Preferences page and in the output of

`/config` REST API call.

Tokens can be added to one's configuration on the Preferences page

under "Engine tokens". The input expects a comma separated list of

strings.

The distribution of the tokens from the administrator to the users

is not carved in stone. As providing access to such engines

implies that the admin knows and trusts the user, we do not see

necessary to come up with a strict process. Instead,

we would like to add guidelines to the documentation of the feature.

Acknowledgment

==============

This development was sponsored by `Search and Discovery Fund

<https://nlnet.nl/discovery>`_ of `NLnet Foundation <https://nlnet.nl/>`_.

.. _engine recoll:

=============

Recoll Engine

=============

.. sidebar:: info

   - `Recoll <https://www.lesbonscomptes.com/recoll/>`_

   - `recoll-webui <https://framagit.org/medoc92/recollwebui.git>`_

   - :origin:`searx/engines/recoll.py`

Recoll_ is a desktop full-text search tool based on Xapian.  By itself Recoll_

does not offer WEB or API access, this can be achieved using recoll-webui_

Configuration

=============

You must configure the following settings:

``base_url``:

  Location where recoll-webui can be reached.

``mount_prefix``:

  Location where the file hierarchy is mounted on your *local* filesystem.

``dl_prefix``:

  Location where the file hierarchy as indexed by recoll can be reached.

``search_dir``:

  Part of the indexed file hierarchy to be search, if empty the full domain is

  searched.

Example

=======

Scenario:

#. Recoll indexes a local filesystem mounted in ``/export/documents/reference``,

#. the Recoll search interface can be reached at https://recoll.example.org/ and

#. the contents of this filesystem can be reached though https://download.example.org/reference

.. code:: yaml

   base_url: https://recoll.example.org/

   mount_prefix: /export/documents

   dl_prefix: https://download.example.org

   search_dir: ''