Running defined commands
From ControlTier
Defined commands are procedures formally defined in a ControlTier type and provide a standard calling interface to the command dispatcher. These defined commands encapsulate your routine procedures and form the basis of your own automation toolkit. Commands can be combined into workflows that represent multi-step processes.
ControlTier includes a variety of types containing standalone commands and workflows that you can use to automate your processes.
Defined commands can be executed either via a command line utility via ctl or as a Job via a graphical console called Jobcenter.
Contents |
Command line usage
CTL has a variety of options that can be displayed via -help. Typing ctl -help shows a complete listing of all the ctl options.
usage: ctl [-h] [-v] [-V] [-z] [-p project -t type -r resource -c command] [-p
project -m module -c command] [--threadcount <1>] [-I filter] [-X filter]
[--filter-exclude-precedence true/false][-l level] [-- command-options]
-R,--report-category The reporting category name
-P,--process-instance The process instance identifier
-Z,--filter-exclude-precedence true/false. if true, exclusion filters have
precedence over inclusion filters
-C,--threadcount number of threads
-F,--failednodes Filepath to store failed nodes (Since 3.4.7)
-I,--nodes include node parameter list
-K,--keepgoing continue node dispatch when execution on one
node fails
-V run verbose and with loglevel "debug"
-X,--xnodes exclude node parameter list
-c command
-h display this help
-l,--level log level. debug|verbose|info|warning|error
-m module name
-r resource resource name
-p project name name
-t resource type name
-v run verbose
-z,--terse leave log messages unadorned
The general option pattern follows this form:
ctl [ctl-options] [-- [command-options]]
Node Dispatch
The ctl command includes a feature called node dispatch that allows you to call commands across a set of hosts without having to specify specific host names. Internally, CTL looks up the nodes that have the command, and then dispatches that command to those matching nodes. Options provide a way to filter the lookup results.
These options control nodedispatch:
- -I,--nodes: Run the command on all nodes matching the regular expression.
- -X,--xnodes: Do not run the command on any node matching the regular expression. If no -I flag is specified, all nodes are looked up and then those matching the -X expression are filtered out.
Note:
- Please note that the "-I" and/or "-X" option must be specified to enable node dispatch.
Use these options with nodedispatch:
- -K,--keepgoing: continue execution on nodes even if one node fails
- -F, --failednodes: specify a file to store the list of any nodes that failed. Specify again on retry to read the nodes list and execute only on the failed nodes.
See the document Use node filtering options for further discussion of node filtering.
Listing
The ctl command provides a listing capability that will let you see which modules, commands and objects are available in a specified CTL project project.
The listing is controlled by specifying the "-p", "-m", "-t", "-o" options.
When no arguments are specified, all modules, commands and objects are listed.
Note:
- If you are a bash user be sure to source the $CTL_HOME/etc/bash_completion.sh file. It provides listing via the tab key
Examples
To list all the modules in project "demo" run: ctl -p demo. You will see each module and the commands defined for that type listed:
. . . zip: A zip package commands: [Get-Process-View, Get-Properties, Get-Supers, Install, Install-Module, Properties, Set-Properties, assertPackageIsInstalled, assertPackageIsUnInstalled, assertPackageIsVerified, create, extract, finish, get, installDependencies, installPackage, object-deployment-uninstall, prepare, purge, register, remove, upload] objects: [j2eetutorial14.zip, demo-pkgs-1.2.zip]
If objects exist for that type, you will see an additional line saying: objects:[ obj1,obj2...]
You can list the options for a command like so: ctl -p project -m type -- -?:
$ ctl -p demo -m zip -- -?
zip: A zip package
[commands]
.
.
.
upload: Upload the file to the repository.
[options]
[-url <>]: repository url
[-filename <>]: file to upload
[-xml <>]: package metadata xml file
[-register]: register the package based on filename and module info
You can also list commands of an object similarly; ctl -p project -t type -r object:
$ctl -p demo -t zip -r demo-pkgs-1.2.zip
.
.
.
upload: Upload the file to the repository.
[options]
[-url <>]: repository url
[-filename <>]: file to upload
[-xml <>]: package metadata xml file
[-register]: register the package based on filename and module info
Command line execution
Commands can be executed in one of two contexts:
- Static context: Static context refers to the executing of a command directly from the software module.
- Eg:
-m type -c command)
- Eg:
- Object context: Via an object specified by name and type
- Eg:
-t type -r object -c command)
- Eg:
The commands defined in the coreutils library are all defined as static.
Here are some examples of static command execution:
- On the localhost, check if something is listening on port 80:
ctl -m netutil -c listening -- -port 80
- Do the same check but this time across all registered hosts:
ctl -I '.*' -m netutil -c listening -- -port 80
This example shows the defined command called "listening" from the netutil module.
- Copy a file from a repository:
ctl -m fileutil -c copy -- \
-file http://repo/myapp/file1.txt -target /myapp/file1.txt -backup
The fileutil "copy" command can copy a local file or one from a web repository, as this example shows off. The "-backup" flag says to create a backup if that file will be overwritten.
- Run the available command:
ctl -m fileutil -c available -- -file /myapp/file1.txt
This checks to see if the file "/myapp/file1.txt" is present.
- Run the available command across all hosts
ctl -I '.*' -m fileutil -c available -- -file /myapp/file1.txt
This checks to see if the file "/myapp/file1.txt" is present
Here are some examples showing object-context commands:
- Run the "Install" command for a ProjectBuilder object:
ctl -p ProjectBuilder -r default -c Install
You can also see the ctl command also supports the node filtering, threadcount and keepgoing flags. See: options.
- Run the "Status" command across all web Nodes with host names beginning with "web":
ctl -I 'web.*' -t Service -r tomcat1 -c Status
- Run the Status command across all the hosts tagged "tomcats" using 10 threads:
ctl -C 10 -I tags=tomcats -t Service -r tomcat1 -c Status
Job execution
Defined commands can also be executed via the GUI as a job. The job definition sample below shows the use of the type and command tags to specify the netutil type name and the listening command, and one of its options:
<job> <name>Run netutil</name> <description/> <additional/> <context> <depot>demo</depot> <type>netutil</type> <command>listening</command> <options> <option name="port" value="8080"/> </options> </context> </job>
[Job.xml]] files can be loaded using ProjectBuilder's load-jobs command which will read the job definitions and store them on the server:
ctl -m ProjectBuilder -c load-jobs -- -file job.xml Succeeded creating/updating 2 Jobs: 1: Run netutil [1] </jobcenter/scheduledExecution/show/1>
With a browser you can view the defined jobs and execute them by accessing the GUI's home page where they are listed or go directly to a job URL. To access the "Run netutil" job, reference it by its ID, "1": http://strongbad:8080/jobcenter/scheduledExecution/show/1
| ||||||||||||||
