Run shell commands from your instance¶
Command line engines are custom engines that run commands in the shell of the host. In this article you can learn how to create a command engine and how to customize the result display.
The command¶
When specifyng commands, you must make sure the commands are available on the
searx host. Searx will not install anything for you. Also, make sure that the
searx
user on your host is allowed to run the selected command and has
access to the required files.
Access control¶
Be careful when creating command engines if you are running a public
instance. Do not expose any sensitive information. You can restrict access by
configuring a list of access tokens under tokens in your settings.yml
.
Available settings¶
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}}']
query_type
: The expected type of user search terms. Possible values:path
andenum
.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.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_enum
: A list containing allowed search terms ifquery_type
is set toenum
.working_dir
: The directory where the command has to be executed. Default:.
result_separator
: The character that separates results. Default:\n
Customize the result template¶
There is a default result template for displaying key-value pairs coming from command engines. If you want something more tailored to your result types, you can design your own template.
Searx relies on Jinja2 for
templating. If you are familiar with Jinja, you will not have any issues
creating templates. You can access the result attributes with {{
result.attribute_name }}
.
In the example below the result has two attributes: header
and content
.
To customize their diplay, you need the following template (you must define
these classes yourself):
<div class="result">
<div class="result-header">
{{ result.header }}
</div>
<div class="result-content">
{{ result.content }}
</div>
</div>
Then put your template under searx/templates/{theme-name}/result_templates
named your-template-name.html
. You can select your custom template with the
option result_template
.
- name: your engine name
engine: command
result_template: your-template-name.html
Examples¶
Find files by name¶
The first example is to find files on your searx host. It uses the command
find available on most Linux distributions. It expects a path type query. The
path in the search request must be inside the working_dir
.
The results are displayed with the default key-value.html template. A result is displayed in a single row table with the key “line”.
- name : find
engine : command
command : ['find', '.', '-name', '{{QUERY}}']
query_type : path
shortcut : fnd
tokens : []
disabled : True
delimiter :
chars : ' '
keys : ['line']
Find files by contents¶
In the second example, we define an engine that searches in the contents of the
files under the working_dir
. The search type is not defined, so the user can
input any string they want. To restrict the input, you can set the query_type
to enum
and only allow a set of search terms to protect
yourself. Alternatively, make the engine private, so no one malevolent accesses
the engine.
- name : regex search in files
engine : command
command : ['grep', '{{QUERY}}']
shortcut : gr
tokens : []
disabled : True
delimiter :
chars : ' '
keys : ['line']