-
-
Notifications
You must be signed in to change notification settings - Fork 249
Script config
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.
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:
- name
- script_path
- description
- working_directory
- allowed_users
- output_files
- requires_terminal
- bash_formatting
- include
- hidden
- parameters
Parameter types:
User-friendly script name. Will be displayed to user
Required: no
Type: string
Default: the filename without extension
Example: "name": "My example script"
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"
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 for the script
Required: no
Type: string
Default: script-server directory
List of users, who can access the script
Required: no
Type: json array
Default: any user
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}
- 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"
](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
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
Allows to load configuration from another file.
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.
Usually included files should be hidden
If a field exist in main and an included configuration, the main configuration takes precedence.
Include can be dynamic, depending on parameter values (what user specifies). In this case the include path should contain ${parameter_name} templates.
At the moment dynamic include affects only parameter configuration section (new parameters can be added on the fly)
Required: no
Type: string (path)
Hides the script from users
Can be used to disable a script or for included configurations
Required: no
Type: boolean
Default: false
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"
}
]
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
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
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
User-friendly description of the parameter, shown to the user
Required: no
Type: string
Marks parameter as required for the user
Required: no
Type: boolean
Default: false
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 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)
Required: no (for constants yes)
Type: depends on the parameter 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, text, file_upload, multiselect, server_file, ip, ip4, ip6
Required: no
Type: string
Default: "text"
Don't show value on server anywhere, replace it with a mask
Required: no
Type: boolean
Default: false
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}"
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
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:
Mininal allowed value
Required: no
Type: int, string
Maximal allowed value
Required: no
Type: int, string
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
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:
List of allowed values for the parameter. Can be either predefined values or a result from another script invocation
If values are read from a script, other parameter values can be injected with ${parameter name} syntax
Required: yes
Type: array or object
Example1: "values": [ "Apple", "Orange", "Banana" ]
Example2: "values": { "script": "ls /home/me/projects" }
Example3: "values": { "script": "ls /${param 1}/${param 2}" }
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:
See list.values
Defines values separator if they are passed as a single argument (e.g. comma-separated)
Required: no
Default: ","
Type: string
Defines, if each value should be passed as a separate argument.
In this case separator property is ignored
Required: no
Default: false
Type: boolean
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
secure flag has no effect for this type
Default value type: unsupported
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:
Defines the server directory, where files are located
Can be relative path to working_directory
Required: yes
Type: string
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
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)
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
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 address is not checked for being accessible.