From a5610835377470b0ce19d8e40f91e48ce4aae4cc Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Thu, 3 Jun 2021 09:48:50 +0200 Subject: [docs] move blog article "Command line engines" to admin/engines/ The article "Command line engines" should be in admin's engine documentation (like the recoll engine). Signed-off-by: Markus Heiser --- docs/admin/engines.rst | 3 +- docs/admin/engines/command-line-engines.rst | 64 ++++++++++++++++++++++++++++ docs/blog/command-line-engines.rst | 65 ----------------------------- docs/blog/index.rst | 1 - 4 files changed, 66 insertions(+), 67 deletions(-) create mode 100644 docs/admin/engines/command-line-engines.rst delete mode 100644 docs/blog/command-line-engines.rst (limited to 'docs') diff --git a/docs/admin/engines.rst b/docs/admin/engines.rst index 3ad206303..520fda35c 100644 --- a/docs/admin/engines.rst +++ b/docs/admin/engines.rst @@ -13,7 +13,8 @@ Special Engine Settings .. toctree:: :maxdepth: 1 - engines/recoll.rst + engines/recoll + engines/command-line-engines .. _engines generic: diff --git a/docs/admin/engines/command-line-engines.rst b/docs/admin/engines/command-line-engines.rst new file mode 100644 index 000000000..b4568f7d5 --- /dev/null +++ b/docs/admin/engines/command-line-engines.rst @@ -0,0 +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 +==================== + +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. + +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. + +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 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`` + + +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'] + + +Next steps +========== + +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/ diff --git a/docs/blog/command-line-engines.rst b/docs/blog/command-line-engines.rst deleted file mode 100644 index 09eb84fb4..000000000 --- a/docs/blog/command-line-engines.rst +++ /dev/null @@ -1,65 +0,0 @@ -======================================== -Running shell commands to fetch results -======================================== - -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 -==================== - -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. - -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. - -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 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`` - - -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'] - - -Next steps -========== - -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/ - - -| Happy hacking. -| kvch // 2020.09.28 21:26 diff --git a/docs/blog/index.rst b/docs/blog/index.rst index 8e0294498..2817f3b2b 100644 --- a/docs/blog/index.rst +++ b/docs/blog/index.rst @@ -10,6 +10,5 @@ Blog python3 intro-offline private-engines - command-line-engines search-indexer-engines sql-engines -- cgit v1.2.3