From 6f7b0d72c084845ea073a82a357c5e99cd41a85f Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Fri, 4 Jun 2021 15:02:47 +0200 Subject: [PATCH] [docs] revision of the section 'Command Line Engines' Signed-off-by: Markus Heiser --- docs/admin/engines/command-line-engines.rst | 99 ++++++++++++--------- docs/dev/offline_engines.rst | 2 +- 2 files changed, 58 insertions(+), 43 deletions(-) diff --git a/docs/admin/engines/command-line-engines.rst b/docs/admin/engines/command-line-engines.rst index b4568f7d5..e9535e74f 100644 --- a/docs/admin/engines/command-line-engines.rst +++ b/docs/admin/engines/command-line-engines.rst @@ -1,41 +1,64 @@ .. _engine command: -============================== -Fetch results from commandline -============================== - -Previously, with searx you could search over the Internet on other people's -computers. Now it is possible to fetch results from your local machine without -connecting to any networks from the same graphical user interface. - -.. _command line engines: - -Command line engines +==================== +Command Line Engines ==================== -In :pull-searx:`2128` a new type of engine has been introduced called ``command``. -This engine lets administrators add engines which run arbitrary shell commands -and show its output on the web UI of searx. +.. sidebar:: info -When creating and enabling a ``command`` engine on a public searx instance, -you must be careful to avoid leaking private data. The easiest solution -is to add tokens to the engine. Thus, only those who have the appropriate token -can retrieve results from the it. + - :origin:`command.py ` + - :ref:`offline 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: +With *command engines* administrators can run engines to integrate arbitrary +shell commands. -* ``command``: A comma separated list of the elements of the command. A special token {{QUERY}} tells searx where to put the search terms of the user. Example: ``['ls', '-l', '-h', '{{QUERY}}']`` -* ``delimiter``: A dict 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 uesr 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`` - +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 example engine below can be used to find files with a specific name in the configured -working directory. +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 @@ -49,16 +72,8 @@ working directory. keys: ['line'] -Next steps -========== +Acknowledgment +============== -In the next milestone, support for local search engines and indexers (e.g. Elasticsearch) -are going to be added. This way, you will be able to query your own databases/indexers. - -Acknowledgement -=============== - -This development was sponsored by `Search and Discovery Fund`_ of `NLnet Foundation`_ . - -.. _Search and Discovery Fund: https://nlnet.nl/discovery -.. _NLnet Foundation: https://nlnet.nl/ +This development was sponsored by `Search and Discovery Fund +`_ of `NLnet Foundation `_. diff --git a/docs/dev/offline_engines.rst b/docs/dev/offline_engines.rst index 5b93685e6..ce6924542 100644 --- a/docs/dev/offline_engines.rst +++ b/docs/dev/offline_engines.rst @@ -8,7 +8,7 @@ Offline Engines - :ref:`demo offline engine` - :ref:`sql engines` - - :ref:`command line engines` + - :ref:`engine command` - :origin:`Redis ` To extend the functionality of SearxNG, offline engines are going to be