Skip to content

Script config

Jump to bottom
Iaroslav Shepilov edited this page Oct 15, 2023 · 42 revisions

Each script should be configured in conf/runners/conf-name.json file, where conf-name is a unique name for each script. Each configuration file should contain only one script. Configuration should be a valid JSON file.
Since (v1.18) you can use YAML files instead of JSON. Configuration options have the same types and nested levels.
Since (v1.18) you can use subfolders inside conf/runners folder for organizing your configurations. Since (v1.19) subfolders define script groups on UI, see group_by_folders for more details.

Also, you can configure scripts using /admin.html page on your server.

Examples of configuration files can be found in stable/testing/configs.

Configurable properties:

Parameter types:

Additional options:

name

User-friendly script name. Will be displayed to user

Required: no
Type: string
Default: the filename without extension
Example: "name": "My example script"

script_path

Path to the script (relative to working directory) OR just a command.

Required: yes
Type: string
Windows important: any non-batch scripts should be run as a command, e.g. 'python my_script.py'
Example: "script_path": "/some/path/to/script.sh"
Example2: "script_path": "python my_script.py"

description

User-friendly script description, which will be shown to a user
Markdown with GitHub flavour can be used

Required: no
Type: string
Example: "description": "This script shuts down the server"

working_directory

Working directory for the script

Required: no
Type: string
Default: script-server directory

group

Allows to aggregate multiple scripts under the same collapsible header on the UI. Just specify the same group for those scripts
Since ( v1.19) If a script config is located inside a subdirectory, then this subdirectory will be define a default group. If you want to overwrite it or remove, specify a group explicitly.

Required: no
Type: string
Default: (since v1.19) subdirectory name or null

allowed_users

List of users, who can access the script

Required: no
Type: json array
Default: any user

output_files

List of files, which will be downloadable by user after a script execution. This option supports the following features:

  • * and ** wildcard
  • substitution of script parameters with ${parameter_name}
  • substitution of auth variables: ${auth.username} (authenticated username) or ${auth.audit_name} (user info, when auth is disabled)
  • use regex pattern for searching file path in a script output:
    • should be surrounded with #
    • matching group number can be specified with number# (e.g. #2#)
    • #any_path can be used as an alternative to ** wildcard

If a path cannot be found, it will be ignored Secure parameter values are protected with a mask during the search

All the matching files are copied locally and stored for at least 24 hours. Only the same user can access the files.

Required: no
Type: array
Example:

"output_files": [
	/* Returns the file under the path */
	"/var/log/server.log",
	
	/* Resolves param1 'value' and recursively searches for 'value'.dat in /tmp/results */
	"/tmp/results/**/${param1}.dat",
	
	/* Searches for any paths in in the script output, and then substitutes each occurence in the path */
	"~/##any_path#/file.txt",
	
	/* Searches for any 8 digits in the script output and builds /var/log/my_8digits.log paths */
	"/var/log/my_#[0-9]{8}#.log",
	
	/* Searches for username='value' in the script output and builds /home/'value'/file.txt paths */
	"/home/#1#username=(\w+)#/file.txt"
]

requires_terminal

(Linux only)
Specifies, if the script should be run in pseudo terminal mode. This is useful because some programs behave differently in terminal and non-interactive modes.

Required: no
Type: boolean
Default: true

bash_formatting

(up to v 1.16, inclusive. Replaced by output_format)
Enables ANSI escape command parsing and showing formatted output on the user interface. E.g. \033[01;31m is a bold red text
Supported escape sequences: 16 text colors and 16 background colors, 4 text styles

Required: no
Type: boolean
Default: true for linux and mac, false otherwise

output_format

(v 1.17)
Specifies how Script server should parse script output. At the moment 4 formats are supported:

  • terminal (default): enables ANSI escape command parsing and showing formatted output on the user interface. E.g. \033[01;31m is a bold red text. Additionally this format supports hyperlinks highlighting and inline images
  • text: no processing is done, script output is displayed as it is
  • html: script output is treated as HTML elements and is rendered correspondingly. Scripts/css are not supported, for those please use html_iframe. Also, the HTML content is sanitized, to protect against XSS attacks
  • html_iframe: script output is treated as a complete HTML page (including linked CSS and script files). In this case, Script server has no control over output styling (font family, size, color, etc.). To make CSS/scripts work, no HTML sanitizing is done (including user input), so such logs are vulnerable to XSS Attacks. Please avoid using html_iframe if your server can be accessed by untrusted users.

Required: no
Type: string
Allowed values: [terminal, text, html, html_iframe]
Default: terminal

include

Allows to load configuration from another file(s).
Can be useful when multiple scripts are using the same configuration section, then the common part could be extracted to a separate config and then included.
Since (v1.18) you can define multiple included files as an array.
If a field exists in a main and an included configuration, the main configuration takes precedence. In the case of conflicts in multiple included files, the first defined included file takes precedence.
Usually included files should be hidden.

Include can be dynamic, depending on parameter values (what a user specifies). In this case, the include path should contain ${parameter_name} templates.
At the moment dynamic include affects only the parameter configuration section (new parameters can be added on the fly)

Required: no
Type: string (path) Since (v1.18): array

hidden

Hides the script from users
Can be used to disable a script or for included configurations

Required: no
Type: boolean Default: false

admin_users

List of admin users, who have admin access to this particular script. Be default any admin can modify any script. But there are cases, when some admins shouldn't modify some scripts.

Required: no
Type: json array
Default: any admin
Example: [ "user1", "user2", "@someGroup" ]

scheduling

Scheduling configuration section for a script. Use this section if you would like to allow users to schedule script execution (once in the future, or repeatedly). See Wiki for details

   - enabled

Enables scheduling for a script. So that users would be able to schedule executions

Required: no
Type: boolean
Default: false

   - auto_cleanup

(v1.18)
Cleans up executions after they are finished, i.e. removes them from UI and don't show them to a user as active.

Required: no
Type: boolean
Default: true (except the cases, when output_files are configured)

access

(v1.18)
This option allows fine-tuning of access to this script.

   - shared_access

     - type

(v1.18)
Specifies the type of shared access. Possible values:

  • ALL_USERS: all users can access script executions of others, including logs, history, and stopping

By default, only a user has access to his own script executions. Execution history can be seen by admins too.

Required: no
Type: string

   - logging

(v1.18)
Allows to override server logging configuration. For syntax please check the linked page.

preload_script

(v1.18)
This option allows defining a separate script/command, which will be executed on a script page load and its results will be displayed to a user. This could be helpful to show some information to a user, which will affect the parameters, he will select. Another codename for this feature is a "splash" screen.
See #218 for a use case description.

   - script

(v1.18)
Defines a path to a script (or command) that should be executed.

Required: yes
Type: string

   - output_format

(v1.18)
Defines an output format for the preload script. For usage, see output_format.

Required: no
Type: string
Default: terminal

parameters

List of script parameters. Parameters are shown on the GUI and passed to a script exactly in the same order. Below are the all allowed parameter properties

Required: no
Type: array of dicts
Example:

"parameters": [
	{
		"name": "param1",
		"param": "-a"
	},
	{
		"name": "param2",
		"param": "-b"
	}
]

   - name

The name of the parameter, which will be shown to the user.
Required for non-constant parameters

Required: yes (for non-constant parameters)
Type: string

   - param

Can be used for specifying flag for the parameter (e.g. -p in script.sh -p myval). If omitted, parameter will be position based

Required: no
Type: string

   - same_arg_param

If true, param and a user value will be sent as a single argument (without a whitespace). For example, if param='--name=' and value=abc, the script argument will be --name=abc.

Required: no
Type: boolean
Default: false

   - no_value

Allows to pass only a flag to the script, without any value (e.g. my_script.sh --verbose)
param property is required in this case.
This infers parameter type as boolean (the type property should be ommitted)

Required: no
Type: boolean
Default: false

   - description

User-friendly description of the parameter, shown to the user

Required: no
Type: string

   - required

Marks parameter as required for the user

Required: no
Type: boolean
Default: false

   - constant

Don't show the parameter to a user, but pass it to a script with the value of default field

Required: no
Type: boolean
Default: false

   - default

Default value shown to a user
Environment variables can be specified with $$ (e.g. "default": "$$HOME")
User credentials can be used with the following templates ${auth.username} (authenticated username) or ${auth.audit_name} (user info, when auth is disabled).
A value can be defined by a script, for details see the script section (parameters injection is supported starting v1.18).

Required: no (for constants yes)
Type: depends on the parameter type

   - type

Parameter type, which affects how a parameter is shown to a user (checkbox, text field, select box, etc.) and how it's passed to a script (for example as a single argument or as multiple arguments)
If no_value is set to true, then the type is ignored and always is boolean
For detail description of each type and its supported properties see the section after properties description.

Allowed values: int, list, editable_list, text, file_upload, multiselect, server_file, ip, ip4, ip6
Required: no
Type: string
Default: "text"

   - secure

Don't show value on server anywhere, replace it with a mask

Required: no
Type: boolean
Default: false

   - pass_as

(v 1.18)
Specifies how to pass a parameter to a script, one of the:

  • argument: a parameter is passed to a script as an argument, e.g. my_script.sh parameter
  • env_variable: a parameter is passed to a script as an environment variable. See env_var for details
  • stdin: a parameter is sent to stdin (as a user would enter a text during runtime). By default, a parameter is sent on a script start. But can be sent later, by using stdin_expected_text

By default, every parameter is passed as an argument and env_variable (configuring 2 options manually is not possible).

Required: no
Type: string
Default: argument and env_variable

   - stdin_expected_text

(v 1.18)
Usable only when pass_as: stdin.
When stdin_expected_text is specified, a parameter will be sent only after the expected text was printed by a script. Can be helpful, when a script requests smth like "Enter your username: ".
List parameters will be sent as comma-separated-values, e.g. [1, 3, 7] list will be passed as 1,3,7.
no_value parameters are sent as true or false.
If a script prints the expected text multiple times, only the first occurrence will be considered.

Required: no
Type: string
Default: no

   - env_var

Pass parameter as specified environment variable. So it would be accessible from your script.
For example, if "env_var": "MY_PARAM", you can use echo "$MY_PARAM" in your bash script
Please note, that all parameters are additionally passed as environment variables anyway, and env_var property allows to override the default name. For details, please check the ticket

Required: no
Type: string
Default: "PARAM_{capitalized parameter name with underscores}"

   - ui

(v 1.18)
UI configuration section for a script. These options only affect UI representation of parameters and do not affect script execution

   - width_weight

Allows to make parameter fields larger by specifying a ratio to other fields. E.g. weight=1 means normal size, weight=2 means double size. Weight should be an integer, if a value is too big, the full width will be used.

Required: no
Type: int
Default: 1

   - separator_before

Adds a separator before a parameter on UI.

   - type

Separator type can be one of the:

  • new_line for starting a parameter on a new line
  • line for a solid horizontal line

Required: yes
Type: string

   - title

Optional title for a separator. This text will be shown as a header before the parameter. If type is line, a solid line will be added with the header

Required: no
Type: string

Parameter types

text

Simple text field. The value is passed to a script as it is.
If parameter is secure, text field on UI will be masked.
Default value type: string

Specific text fields:

max_length

(v 1.17)
Max allowed length (in characters) of the text field.

Required: no
Default: unlimited

regex

(v 1.18)
Allows to specify regex validation for the parameter.
Important! This is a complex option, i.e. it requires nested options, instead of specifying the regex directly. For example: "regex": {"pattern": "\\d+", "description": "Should be a number"}.

Required: no
Type: object

pattern

(v 1.18)
Defines regex pattern for validation. Please note, that double slash \\ is required for escape syntax, e.g. a number pattern is \\d.

Required: yes
Type: string

description

(v 1.18)
An optional description, which will be shown to a user, when regex is not matching. Even though it's optional, it's highly recommended to always specify it, so that users can better understand what is the reason for an error.

Required: no
Type: string

multiline_text

(v1.18)
Same as text type, but allows mutlilines. The value is passed to a script as it is.
Also, this parameter takes full width on the UI. So it's better to make multiline_text parameters to be the first or the last.
If parameter is secure, text field on UI will NOT be masked on UI, only on the server side.
Default value type: string

Specific multiline_text fields:

max_length

(v 1.17)
Max allowed length (in characters) of the text field.

Required: no
Default: unlimited

int

The same as text, but performs number validation.
Can be constrained with min and max properties
Default value type: string or integer

Specific int fields:

min

Mininal allowed value

Required: no
Type: int, string

max

Maximal allowed value

Required: no
Type: int, string

boolean (no_value)

Parameter is shown to a user as a checkbox. Since this is supported only for no_value parameters (flags only), value is not passed to a script
Default value type: boolean

list

Provides to user a list with allowed values (as a combobox).
Allowed values should be specified with values property
Default value type: string

Specific list fields:

values

List of allowed values for the parameter. Can be either predefined values or a result from another script invocation (see details in script section)

Required: yes
Type: array or object
Example1: "values": [ "Apple", "Orange", "Banana" ]
Example2: "values": { "script": "ls /home/me/projects" }
Example3: "values": { "script": "ls /home/${auth.username}/${param 1}/${param 2} | grep abc ", "shell": true }

values_ui_mapping

(v1.18)
Defines optional mapping between allowed values and how these values are displayed on UI. It's always a key-value mapping, where a key is a script value, and a value is how this value is displayed on UI.
Important! These mappings are completely optional. If there is no mapping for a value, then this value will be displayed to a user as it is.
This feature can be useful when a script accepts some cryptic values, which are not very clear to users.
In case, when values are defined by a script, this mapping could still be used, but should define all required combinations in advance.

Required: no
Type: object (key-value mapping, both key and value should be strings)
Example: "values_ui_mapping": { "Apple": "A sweet juicy Apple" }

multiselect

Provides to user a list with allowed values (as a combobox), where he can select multiple options
Depending on the configuration, these values will be passed as a single argument or multiple arguments
Allowed values should be specified with values property
Default value type: string

Specific multiselect fields:

values

See list.values

values_ui_mapping

(v1.18)
See list.values_ui_mapping

separator

Defines values separator if they are passed as a single argument (e.g. comma-separated)

Required: no
Default: ","
Type: string

multiple_arguments

(<= v1.16, replaced by multiselect_argument_type)
Defines, if each value should be passed as a separate argument.
In this case separator property is ignored

Required: no
Default: false
Type: boolean

multiselect_argument_type

(v1.17)
Defines, how param and each single value should be passed to a script. Should be one of:

  • single_argument (default): sends all the values as a single argument, separated by separator (-param value1,value2,value3)
  • argument_per_value: sends every value as a separate argument (-param value1 value2 value3)
  • repeat_param_value: sends every value as a separate argument and repeat param for each value (-param value1 -param value2 -param value3)

Required: no
Default: single_argument
Type: string

editable_list

(v 1.17)
The same as list, but allows a user to type a custom value
Allowed values should be specified with values property
Default value type: string

Specific editable_list fields:

values

See list.values

file_upload

Allows user to upload a file to the server as a parameter.
The file is uploaded to the server and stored in a temp folder. Then the file is passed to a script as an absolute path
Currently only a single file can be uploaded. If you need to upload multiple files you can work around this by uploading an archive (e.g. zip) and unpack the archive in your script.

secure flag has no effect for this type
Default value type: unsupported

server_file

Allows user to select a file on server. It can be recursive (user can navigate in folders) or non-recursive (plain list of files). The value passed to a script as a full path, including file_dir parameter.
Default value type: string (non-resursive) or array (recursive path)

Specific server_file fields:

file_dir

Defines the server directory, where files are located
Can be relative path to working_directory

Required: yes
Type: string

file_recursive

Defines if a user will be able to navigate between folders and select any path
If true, file chooser dialog is shown to a user with file structure of the server.
User will be able to navigate only within file_dir directory. Any other locations will be hidden.
If this setting is true, then parameter default value should be specified as an array

Required: no
Default: false
Type: boolean

file_extensions

If set, then only files with the specified extensions will be shown to a user.
Multiple extensions could be specified.
If the option is set, then folder selection is not possible (i.e. file_type option is set to file)
Format: just extension name, without a dot. Case insensitive

Required: no
Default: any extension
Type: array (or a string for a single extension)

file_type

Specifies, what type of files the user will be able to select: file or dir.

Required: no
Allowed values: "file" and "dir"
Default: any type
Type: string

excluded_files

(v 1.17)
List of files/folders/patterns which should be excluded and not shown to a user.
If the specified pattern is a folder, all descendant children will be excluded recursively (see examples below).
Supports pattern matching: * for a single-level matching (e.g. /user/*/.ssh or path/*.log) and ** for recursive matching (any number of levels).

Some examples:

  • /var/log: exclude all the files in /var/log folder and any descendants (e.g. /var/log/abc/some.log)
  • /user/home/*.txt: exclude any .txt files located directly in /user/home non-recursive. (e.g. /user/home/auth.txt - excluded, /user/home/documents/cv.txt - included)
  • **/auth/** - exclude any files, located in auth folder (e.g. /var/auth/passwords, /user/home/.secrets/auth/secret.key)

Required: no
Type: array

ip

Requires user to specify a valid IP address as a parameter. Accepts either IPv4 or IPv6.
If only only version should be accepted, there are corresponding parameter types ip4 and ip6
Only IP lexical validation is performed and the address is not checked for being accessible.

Additional options

script

For default and values options, you can load data from script execution. Here is an example:

"values": {
  "script": "some_script.sh ${another param}",
  "shell": false
}

The script option supports auth variables and injection of other parameter values, for example:

"script": "ls ${auth.username}/${file_param}"

Auth variables are:

  • ${auth.username} (authenticated username)
  • ${auth.audit_name} (user info, when auth is disabled)

(v1.17)
The shell option allows you to use bash operators (e.g. | pipe operator) in scripts.
By default, this option is enabled only for scripts without any variables.
When script contains variables, it can be a subject to Shell injection, that's why shell is disabled by default. If you trust your users (and no one else can access the server), you can explicitly enable it be using "shell": true

Clone this wiki locally