CTL-RUN Command Reference
From ControlTier
Requires Version: 3.5.2
Contents |
Synopsis
ctl-run [-h] [-v] [-l level] <nodefilters> [-i id] [-j group/name] [-- arguments]
Since CTL 3.5
Overview
The ctl-run command is used to start the execution of a Job defined in CTL Center. The Job is executed on the server, and the ID for the execution is displayed. This is equivalent to logging in to CTL Center and starting a Job within the web application GUI.
The Job can either be specified by ID (-i), or by name and optional group (-j). The Node filters used for the execution of the job can also be specified on the commandline, and will be used instead of any already defined for the Job. Arguments to the Execution can be specfied after (--).
Related Tools
- ctl-jobs lists the available Jobs and can download their definitions.
- ctl-queue lists the running job executions, and can kill executions.
- ctl and ctl-exec can use the
-Qflag to submit "transient" executions to the Central Dispatcher
General Options
| Option | alternate | argument | description |
|---|---|---|---|
| -h | --help | false | Displays help and usage information |
| -v | --verbose | false | Enable verbose output |
| -l | --loglevel | true | verbose|info|warning|error) |
Nodefilter Options
[-I <include>] [-X <exclude>] [-C threads] [-K|-N]
These are a subset of the common Nodefilter Options used by Ctl and ctl-exec as well.
| option | description |
|---|---|
| -I filter | Included node filters, see Node filtering options |
| -X filter | Excluded node filters, see Node filtering options |
| -C count | Threadcount, defaults to 1 |
| -K | Keepgoing on node failure (no arguments) |
| -N | Do not keepgoing on node failure (no arguments) (overrides stored Job definition) |
If Node filter options are specified, the Execution will adopt these filters and options instead of those in the stored Job definition. The -N option allows you to override the "keepgoing" option if set to true for a stored Job.
Run Options
| Option | alternate | argument | description |
|---|---|---|---|
| -j | --job | true | Job identifier (group and name). Run a Job specified by Job name and optional group, e.g: 'Group Name/Job Name'. |
| -i | --id | true | Job ID. Run the Job with this ID |
Execution
This tool requires a unique Job to be identified for execution. This is done either by using -i id, or -j group/name. The group is optional if only one Job with the name exists.
Examples:
ctl-run -i 12
Runs Job with ID 12.
ctl-run -j 'QA/test/Full Test Suite'
Runs the job named "Full Test Suite" in the "QA/test" group.
ctl-run -g QA/test -n 'Full Test Suite'
Also runs the job named "Full Test Suite" in the "QA/test" group.
ctl-run -j 'Full Test Suite'
Also runs the job named "Full Test Suite" if it is the only Job with that name.
If you try to run a job by name only, but it is not unique, you will get an error message like this:
Venkman:~ greg$ ctl-run -j testJob Error: Failed request to run a job: Server reported an error: No unique job matched the input: testJob, null. found (2)
Running a Job and specifying Node filters:
ctl-run -I tags=dev -X os-family=windows -C 2 -K -j 'test/Job 1'
| ||||||||||||||
