The configuration of a tool is accomplished through a series of files provided to, and vetted by, the active resources team. The tool developer creates these files.
These include the following two required files:
bin.tar.gz
config.yml
You may optionally also have .tar.gz files named after a form input containing default files for that input for the user to choose from.
bin.tar.gz contains a folder named 'bin' in which there are several control scripts. This is part of the working folder structure that will be created on the tool server.
Required:
ip.sh - the VO will append the IP address of the server into this file as a variable named 'ip'. Include this script if you need it elsewhere.
start.sh - the script that starts up the actual resource
stop.sh - the script that stops the resource and cleans up (don't clean up output here!)
Optional:
{various}.sh - run before start.sh, these provide options to run scripts on inputs. The order these are run in can be configured.
batch.sh - Overrideable name. Mode can be either interactive or batch. This script is run after start.sh to launch any secondary processes needed.
interactive.sh - Overrideable name. Mode can be either interactive or batch. This script is run after start.sh to launch any secondary processes needed.
command.sh - Overrideable name. Commands may be defined for interactive mode. This is the script that accepts commands from the VO and acts on them.
postscript.sh - Overrideable name. Script run after resource is stopped, i.e. for postprocessing.
config.yml is the main configuration file that defines the inputs and behaviors of the resource. The CPS-VO uses this to generate the user form for launching the tool. This file is in the YAML format.
There are five main groups in this file:
- inputs
- runtime
- output
- access
- version
inputs
Inputs are named arrays in the YAML file - the name is used as the form field name. With the implementation of version 2, the Drupal Form API has been fully exposed for use. Drupal's Form API (FAPI) documentation can be found here, and covers most common form fields. However, because we implement some custom form fields, we supplement the FAPI with some additional parameters.
| Name | Type | Options | Types | Required | Description |
|---|---|---|---|---|---|
| #custom_type | text | File.VO, Remote.Options | checkboxes, radios, select | No |
VO Custom parameter that populates #options automatically |
| #seedfile | text | .tar.gz file | File.VO | No | Extracted to populate input choices when empty and autocreate is enabled |
| #autocreate | boolean | true, false | File.VO | No | Whether to create missing folders and files |
| #setupscript | text | All | No | Shell script to run after input transfer but before start | |
| #setupweight | signed int | All | No | Weight when multiple input scripts are run. Default is 0. Lower values run earlier. | |
| #url | text | Remote.Options | Yes | Remote URL to retrieve select options from, and possibly default setting. (Experimental) {user} in the URL will be replaced with the VO username | |
| #datatype | text | JSON | Remote.Options | Yes | Format of data retrieved from remote URL |
The File.VO input type will search the group taxonomy looking for a vocabulary named 'Active Resources', with a substructure of
{toolname}->inputs->{inputname}
Inside this folder should exist the files used to populate the select form field. The autocreate option is highly recommended as it will create this structure for you in combination with a tar.gz seedfile of files that should be in the folder.
runtime
Runtime has three sections:
- maxrun
- modes
- controloptions
- showiconname
Maxrun has the following settings:
- enable - Turns on a time limit per active resource session (real granularity affected by cron running every 10 minutes)
- max - The maximum time limit a user can choose for a session
- default - The default time limit for a session
- optional - Whether the user has the option to set this. If you enable maxrun and make optional false, the default will be used and the user cannot change it.
- action - which command to run if maxrun has been exceeded (stop, suspend)
Modes contains named arrays for the mode options the user can choose between, as well as a default setting. Two are generally possible:
- batch
- interactive
Each has a required label field for user selection of mode and an optional setupscript that can be run after start.
Interactive mode is done by iframing a window to the server, and has several other options:
- commandscript - overrides the default name of command.sh for the script that handles interactive commands
- header - HTML content you want displayed above the iframe containing the interactive window
- viewer - an array containing configuration for the iframe:
-- mode - currently 'iframe' or 'shadowbox' (which is a much nicer way to provide an iframe)
-- server - defaults to the ip address of the server, but may be overridden here
-- secure - boolean - whether to use https or http for the iframe URL
-- port - some visualizers run on ports other than 80, so you can specify this here
- commands - in this named array you specify commands the user can forward to the server while the resource is running, in addition to anything already inside the iframe window
-- type - currently the options are button or form. Form is used for passing text field arguments
-- value - what is sent to the server when the command is executed
-- label - displayed label for command
-- script - overrides command script on a field basis
- delay - an integer value in seconds representing a delay to allow the server to intialize before forwarding the user to the tool
- controloptions - [optional] an array of values representing the supported control commands a user will have buttons for during interactive mode. Possible values include reset, stop, and suspend. Defaults to reset and stop.
The 'form' type has the following additional fields:
- format - defines how the form fields are forwarded to the command script - currently the only option is 'value_args'
- fields - named array of fields for the command to forward together
-- type - currently only 'text' is accepted
-- label - visible label on the field
controloptions [optional] is used for setting what options a user with permission to control the resource are shown on the status page. This is an array with possible options of 'stop' and 'suspend'. Defaults to stop.
showiconname [optional, TRUE] overlays the name of the tool over the launch graphic. If your graphic already contains the name of the tool to differentiate from other tools that may be available, you may wish to set this to FALSE.
output
Output is where you configure allowable output settings:
- enable - whether output data should be collected from the server by the VO
- optional - whether the user has the choice about whether data is retrieved or not
- delay - number of seconds after the resource is stopped before data retrieval should be attempted (granularity affected by cron runs 10 minutes apart)
- postscript - if a script is desired after the resource is stopped, this will be run immediately after stop.
- optionlabel - defaults to "Output Destination"
- options - default provides four options: 0 (don't save), VO_filebrowser (Posted in Group), VO_unpublished (private to user unless they publish it), VO_privatefile (permanently private to the user). By populating this setting you can restrict the options.
- compressionlabel - defaults to "Output Compression". All output results are compressed into an archive before the VO retrieves them. The user can choose between tar.gz, tgz, and zip. These options are currently not configurable.
access
Access defines who has rights to use the resource. Currently the only field is 'allowedgroups', which is a comma separated sequence of group node id's, or * for all groups.
version
Version allows us to update the way the VO processes a config file while maintaining backwards compatibility. The value is an integer. All tools are currently running version 2.
Example Files
example_bin.tar.gz - this is for the PX4Gazebo tool, which is fairly complex
example_config.yml - this is a generic sample file showing some of the options available (obsolete, needs to be updated to version 2)