command-line-engines.rst 2.7 KB

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