@@ -0,0 +1,65 @@
1+========================================
2+Running shell commands to fetch results
3+========================================
4+
5+Previously, with searx you could search over the Internet on other people's
6+computers. Now it is possible to fetch results from your local machine without
7+connecting to any networks from the same graphical user interface.
8+
9+
10+Command line engines
11+====================
12+
13+In :pull:`2128` a new type of engine has been introduced called ``command``.
14+This engine lets administrators add engines which run arbitrary shell commands
15+and show its output on the web UI of searx.
16+
17+When creating and enabling a ``command`` engine on a public searx instance,
18+you must be careful to avoid leaking private data. The easiest solution
19+is to add tokens to the engine. Thus, only those who have the appropriate token
20+can retrieve results from the it.
21+
22+The engine base is flexible. Only your imagination can limit the power of this engine. (And
23+maybe security concerns.) The following options are available:
24+
25+* ``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}}']``
26+* ``delimiter``: A dict containing a delimiter char and the "titles" of each element in keys.
27+* ``parse_regex``: A dict containing the regular expressions for each result key.
28+* ``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.
29+* ``query_enum``: A list containing allowed search terms if ``query_type`` is set to ``enum``.
30+* ``working_dir``: The directory where the command has to be executed. Default: ``.``
31+* ``result_separator``: The character that separates results. Default: ``\n``
32+
33+
34+The example engine below can be used to find files with a specific name in the configured
35+working directory.
36+
37+.. code:: yaml
38+
39+ - name: find
40+ engine: command
41+ command: ['find', '.', '-name', '{{QUERY}}']
42+ query_type: path
43+ shortcut: fnd
44+ delimiter:
45+ chars: ' '
46+ keys: ['line']
47+
48+
49+Next steps
50+==========
51+
52+In the next milestone, support for local search engines and indexers (e.g. Elasticsearch)
53+are going to be added. This way, you will be able to query your own databases/indexers.
54+
55+Acknowledgement
56+===============
57+
58+This development was sponsored by `Search and Discovery Fund`_ of `NLnet Foundation`_ .
59+
60+.. _Search and Discovery Fund: https://nlnet.nl/discovery
61+.. _NLnet Foundation: https://nlnet.nl/
62+
63+
64+| Happy hacking.
65+| kvch // 2020.09.28 21:26