From f0e6678aac19e19d16a51d33d761d7ac603e913d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= <sitbackandwait@gmail.com>
Date: Mon, 28 Sep 2020 22:02:41 +0200
Subject: [PATCH] Add blogpost about `command` engine

---
 docs/blog/command-line-engines.rst | 65 ++++++++++++++++++++++++++++++
 docs/blog/index.rst                |  1 +
 2 files changed, 66 insertions(+)
 create mode 100644 docs/blog/command-line-engines.rst

diff --git a/docs/blog/command-line-engines.rst b/docs/blog/command-line-engines.rst
new file mode 100644
index 00000000..746c9e4a
--- /dev/null
+++ b/docs/blog/command-line-engines.rst
@@ -0,0 +1,65 @@
+========================================
+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:`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 04d95350..689739a5 100644
--- a/docs/blog/index.rst
+++ b/docs/blog/index.rst
@@ -11,3 +11,4 @@ Blog
    admin
    intro-offline
    private-engines
+   command-line-engines