runner 0.3.2
Install from the command line:
Learn more about npm packages
$ npm install @into-cps-association/runner@0.3.2
Install via package.json:
"@into-cps-association/runner": "0.3.2"
About this version
A utility service to manage safe execution of remote scripts / commands. User launches this from commandline and let the utility manage the commands to be executed.
The runner utility runs as a service and provides REST API interface to safely execute remote commands. Multiple runners can be active simultaneously on one computer. The commands are sent via the REST API and are executed on the computer with active runner.
The package is available on npmjs.
Install the package with the following command:
sudo npm install -g @into-cps-association/runner
The package is available in Github packages registry.
Set the registry and install the package with the following commands
sudo npm config set @into-cps-association:registry https://npm.pkg.github.com
sudo npm install -g @into-cps-association/runner
The npm install command asks for username and password. The username is your Github username and the password is your Github personal access token. In order for the npm to download the package, your personal access token needs to have read:packages scope.
The utility requires config specified in YAML format. The template configuration file is:
port: 5000
location: 'script' #directory location of scripts
commands: #list of permitted scripts
- create
- execute
It is suggested that the configuration file be named as runner.yaml and placed in the directory in which the runner microservice is run.
The location
refers to the relative location of the scripts directory
with respect to the location of runner.yaml file.
However, there is no limitation on either the configuration filename or
the location
. The path to runner.yaml can either be relative or
absolute path. However, the location
path is always relative path
with respect to the path of runner.yaml file.
The runner requires commands / scripts to be run.
These need to be placed in the location
specified in
runner.yaml file.
For example, the location
directory might contain
the two scripts: create and execute. These two become
valid command names that consumers of REST API can invoke.
All other command execution requests result in invalid status.
Display help.
$runner -h
Usage: runner [options]
Remote code execution for humans
Options:
-v --version package version
-c --config <string> runner config file specified in yaml format (default: "runner.yaml")
-h --help display help
The config option is not mandatory. If it is not used, runner looks for runner.yaml in the directory from which it is being run. Once launched, the utility runs at the port specified in runner.yaml file.
runner #use runner.yaml of the present working directory
runner -c FILE-PATH #absolute or relative path to config file
runner --config FILE-PATH #absolute or relative path to config file
If launched on one computer,
you can access the same at http://localhost:<port>
.
Access to the service on network is available at http://<ip or hostname>:<port>/
.
Three REST API methods are active. The route paths and the responses given for these two sources are:
REST API Route | HTTP Method | Return Value | Comment |
---|---|---|---|
localhost:port | POST | Returns the execution status of command | Executes the command provided. All the commands sent in the right JSON format gets stored in history. |
localhost:port | GET | Returns the execution status of the last command sent via POST request. | |
localhost:port/history | GET | Returns the array of valid POST requests received so far. |
Executes a command. The command name given here must exist in location directory.
{
"name": "<command name>"
}
If the command is in the permitted list of commands specified in runner.yaml and the matching command / script exists in location, a successful execution takes place. The API response will be
{
"status": "success"
}
If the command is neither permitted nor available, the response will be
{
"status": "invalid command"
}
Shows the status of the command last executed. If the execution was successful, the status will be
{
"name": "<command-name>",
"status": "valid",
"logs": {
"stdout": "<output log of command>",
"stderr": "<error log of command>"
}
}
If the execution is unsuccessful, the status will be
{
"name": "<command-name>",
"status": "invalid",
"logs": {
"stdout": "",
"stderr": ""
}
}
If an incorrectly formatted JSON is sent via POST request, a validation error is returned.
{
"message": "Validation Failed",
"error": "Bad Request",
"statusCode": 400
}
Returns the array of POST requests received so far. Both valid and invalid commands are recorded in the history.
[
{
"name": "valid command"
},
{
"name": "invalid command"
},
{
"name": "valid command"
}
]
This software is owned by The INTO-CPS Association and is available under the INTO-CPS License.