The CLI invokes web services exposed by the Administrator server. You specify the Administrator server location and user credentials in a property file.
Sample Build, Data, and Property Files
Sample build and data files for many of the objects supported by the command-line interface are provided in CONFIG_HOME/admin/enterpriseName/samples. A sample property file is provided in
CONFIG_HOME/admin/enterpriseName/samples/remote_props.properties, where enterpriseName is the name specified for the Administrator enterprise when you created the Administrator server. Before using this sample file, replace the host portion of the adminURL property with the address of your TIBCO ActiveMatrix Administrator server and the username and password properties with the credentials of a user that has been granted the permissions required to execute the actions in the script.
Invoking the Command-Line Interface
Before you begin
1. Download Ant from http://ant.apache.org, install as directed in the Ant documentation.
2. Increase the JVM permgen size:
– Windows - Add set ANT_OPTS=-Xmx1024m -XX:MaxPermSize=256m -XX:PermSize=128m to
%USERPROFILE%\antrc_pre.bat
– UNIX - Add export ANT_OPTS="-Xmx1024m -XX:MaxPermSize=256m -XX:PermSize=128m to
~/.antrc
3. Confirm the value of ANT_OPTS before executing CLI scripts from the command prompt.
About this task
To invoke the command-line interface:
Procedure
1. Add the Ant executable to your path.
2. Run ant -f build.xml, where build is the name of the build configuration file.
Results
The output states the results of each action specified in the default target in the build file.
Build Files
The Ant build file for the command-line interface must contain the following elements: import, project,
target, and AMXAdminTask.
import Element
The import element identifies the task definition file, which defines the path to the libraries required by AMXAdminTask.
Set the file attribute to CONFIG_HOME/admin/amxadmin/samples/admin-scripts-base.xml. For example:
<import file="C:/Documents and
Settings/AMX-User/ApplicationData/amx-3/data/admin/amxadmin/samples/admin-scripts-base.xml"/>
project Element
The project element declares the default build target for the build.xml file. taskdef and target are subelements of the project. The optional default attribute allows you to specify a default target. You can choose any target from the build file to be the default target.
<project default="target">
<taskdef ... />
<target name="target" ... />
</project>
target Element
The target element specifies the actions performed for an execution of the command line interface via the AMXAdminTask subelement. In a target you can provide a depends attribute containing a list of targets.
Each target will be run in order until one fails or the list completes.
<target name="target">
<AMXAdminTask ... />
</target>
Example Build File
The following build file defines targets to upload a distributed application archive, create an application, map an application to a node, create a resource template, create a resource instance and install it in a node, and deploy an application.
<project default="all">
<!-- TIBCO ActiveMatrix installation location-->
<property name="TIBCO-HOME" value="C:\bs"/>
<property name="ADMIN-VERSION" value="3.1"/>
<property name="remote-properties.file" value="${basedir}/Server.properties"/>
<!-- Import TIBCO Administrator CLI tasks and classes -->
<import file="${TIBCO-HOME}/administrator/${ADMIN-VERSION}/scripts/basic_cli.xml" />
<!-- Default task for this build file -->
<target name="all"
depends="upload.daa, create.app, edit.properties, wire.application, distribute.app, deploy.app, start.app"
description="Default target group, execute following targets: upload.daa, create.app, edit.properties, wire.application, distribute.app, deploy.app, start.app"/>
<!-- Upload DAA specified in the data file -->
<target name="upload.daa" description="Uploading Application">
<AMXAdminTask action="add"
objectSelector="DAA"
remote="true"
propsFile="${remote-properties.file}"
dataFile="${basedir}/jv.phonebook.soa.deployment-config.xml"
overwrite="false" merge="true" createIfNotExists="true"
force="false" failOnError="false" />
</target>
<!-- create the application -->
<target name="create.app" description="Creating Application">
<AMXAdminTask remote="true" propsFile="${remote-properties.file}"
action="add" dataFile="${basedir}/jv.phonebook.soa.deployment-config.xml"
objectSelector="Environment//Application"
overwrite="false" merge="true"
createIfNotExists="true" force="false" failOnError="true" />
</target>
<!-- configure properties of the application, and create resource instances if needed
-->
<target name="edit.properties" description="Editing Properties">
<!-- create resource template -->
<AMXAdminTask remote="true" propsFile="${remote-properties.file}"
action="add" dataFile="${basedir}/jv.phonebook.soa.deployment-config.xml"
objectSelector="ResourceTemplate" overwrite="false" merge="true"
createIfNotExists="true" force="false" failOnError="true" />
<!-- add all require resource instances -->
<AMXAdminTask remote="true" propsFile="${remote-properties.file}"
action="add" dataFile="${basedir}/jv.phonebook.soa.deployment-config.xml"
objectSelector="Environment/Node/ResourceInstance"
overwrite="false" merge="true"
createIfNotExists="true" force="false" failOnError="true" />
<!-- install instances added above -->
<AMXAdminTask remote="true" propsFile="${remote-properties.file}"
action="install" dataFile="${basedir}/jv.phonebook.soa.deployment-config.xml"
objectSelector="Environment/Node/ResourceInstance"
overwrite="false" merge="true"
createIfNotExists="true" force="false" failOnError="true" />
<!-- override values for properties -->
<AMXAdminTask remote="true" propsFile="${remote-properties.file}"
action="edit" dataFile="${basedir}/jv.phonebook.soa.deployment-config.xml"
objectSelector="Environment//Application/Property |
Environment//Application//PromotedService//Binding/Property | Environment//Application//PromotedReference//Binding/Property"
overwrite="false" merge="true"
createIfNotExists="true" force="false" failOnError="true" />
</target>
<!-- create wires to other applications -->
<target name="wire.application" description="Wiring Application">
<AMXAdminTask remote="true" propsFile="${remote-properties.file}"
action="set" dataFile="${basedir}/jv.phonebook.soa.deployment-config.xml"
objectSelector="//PromotedReference/Wire"
overwrite="false" merge="true"
createIfNotExists="true" force="false" failOnError="true" />
</target>
<target name="distribute.app" description="Distributing Application">
<AMXAdminTask action="set"
objectSelector="Environment//Application//Component/Node | Environment//Application//PromotedService//Binding/Node | Environment//Application//PromotedReference//Binding/Node"
remote="true"
propsFile="${remote-properties.file}"
dataFile="${basedir}/jv.phonebook.soa.deployment-config.xml"
overwrite="false"
merge="true"
createIfNotExists="true"
force="false"
failOnError="false"/>
</target>
<!-- deploy the application -->
<target name="deploy.app" description="Deploying Application">
<AMXAdminTask remote="true" propsFile="${remote-properties.file}"
action="deploy" dataFile="${basedir}/jv.phonebook.soa.deployment-config.xml"
objectSelector="Environment//Application"
overwrite="false" merge="true"
createIfNotExists="true" force="false" failOnError="true"
/>
</target>
<target name="start.app" description="Starting Application">
<AMXAdminTask remote="true" propsFile="${remote-properties.file}"
action="start" dataFile="${basedir}/jv.phonebook.soa.deployment-config.xml"
objectSelector="Environment//Application"
overwrite="false" merge="true"
createIfNotExists="true" force="false" failOnError="true" />
</target>
</project>
<project default="all">
<import file="C:/Documents and
Settings/AMX-User/ApplicationData/amx-3/data/admin/amxadmin/samples/admin-scripts-base.xml"/>
<target name="all" depends="upload.daa, create.app, map.app.to.node, create.rt, create.ri, install.ri, deploy.app"/>
<target name="upload.daa">
<AMXAdminTask
propsFile="C:/amx-3data/admin/amxadmin/samples/remote_props.properties"
action="add"
dataFile="dateMgr_data.xml"
objectSelector="DAA"
failOnError="true"/>
</target>
<target name="create.app">
<AMXAdminTask remote="true"
propsFile="C:/amx-3data/admin/amxadmin/samples/remote_props.properties"
action="add"
dataFile="dateMgr_data.xml"
objectSelector="Environment//Application"
failOnError="true"/>
</target>
<target name="map.app.to.node">
<AMXAdminTask remote="true"
propsFile="C:/amx-3data/admin/amxadmin/samples/remote_props.properties"
action="set"
dataFile="dateMgr_data.xml"
objectSelector="Environment//Application/Node"
failOnError="true"/>
</target>
<target name="create.rt">
<AMXAdminTask remote="true"
propsFile="C:/amx-3data/admin/amxadmin/samples/remote_props.properties"
action="add"
dataFile="dateMgr_data.xml"
objectSelector="ResourceTemplate"
failOnError="true"/>
</target>
<target name="create.ri">
<AMXAdminTask remote="true"
propsFile="C:/amx-3data/admin/amxadmin/samples/remote_props.properties"
action="add"
dataFile="dateMgr_data.xml"
objectSelector="Environment/Node/ResourceInstance"
failOnError="true"/>
</target>
<target name="install.ri">
<AMXAdminTask remote="true"
propsFile="C:/amx-3data/admin/amxadmin/samples/remote_props.properties"
action="install"
dataFile="dateMgr_data.xml"
objectSelector="Environment/Node/ResourceInstance"
failOnError="true"/>
</target>
<target name="deploy.app">
<AMXAdminTask remote="true"
propsFile="C:/amx-3data/admin/amxadmin/samples/remote_props.properties"
action="deploy"
dataFile="dateMgr_data.xml"
objectSelector="Environment//Application"
failOnError="true"/>
</target>
</project>
AMXAdminTask
AMXAdminTask specifies an action, data and property files, the objects on which the action is performed, and various behavioral attributes.
<AMXAdminTask action="action"
dataFile="path to data file"
propsFile="path to properties file"
[createIfNotExists = "{true|false}"]
[failOnError="{true|false}"]
[force="{true|false}"]
[merge="{true|false}"]
[objectSelector="XPath expression"]
[options="nostart|immediate|terminate|resolve|auto-resolve|stable|handle-dependencies"]
[overwrite="{true|false}"]
[timeout="timeout value"/>
Parameters
Description Req?
Type Attribute
The action to be performed on the objects in the data file. The action is case insensitive.
Yes String
action
• Unless objectSelector is specified, the action is applied to every object in the data file.
• The order in which the action is applied to the objects is either breadth first or depth first. The method used is determined by the action.
– Breadth first - add, edit, install, start, stop – Depth first - delete, uninstall
• Some actions are not performed against certain object formats.
– For the most part, add and edit are applied only to objects specified in full format. Objects not in this format are skipped.
Applicable to the edit action.
If an object is to be edited but doesn’t yet exist and this flag is true, then the object is added.
No Boolean
createIfNotExists
If this flag is false and the object to be edited doesn't exist, an error is reported.
Default: true.
The path to the XML file containing the object data.
Yes String
dataFile
Causes the Ant task to fail when an unrecoverable error is reported. The option stops processing of targets in the depends list or specified on the command line.
No Boolean
failOnError
Forces an action even if the object has dependent objects or is not in the appropriate state. Applies to the following actions and objects:
No Boolean
force
• delete - Node, Application, Environment, ResourceTemplate, ResourceInstance
• undeploy - Application
• stop - Application, Component, Binding
• uninstall - Node, ResourceInstance For example:
Description Req?
Type Attribute
• A node must be in the uninstalled state before it can be deleted and it must be stopped before it can be uninstalled. If any problems occur moving the node to one of these states, and force is true, the node is deleted even if it is not in the uninstalled state or uninstalled even if it is not stopped.
• An application must be in the undeployed state before it can be deleted and it must be stopped before it can be undeployed. If any problems occur moving the application to one of these states, and force is true, the application is deleted even if it is not in the undeployed state.
You should exercise extreme caution when using this option as it may leave your system in a non-working state.
Default: false.
Applicable to the add action, and only if the overwrite flag was used and is true.
If an object to be added already exists and No
Boolean
merge
• If merge is true and overwrite is true, then the existing object is overwritten by merging with the new object. That is, the old object's data is updated with the new object's data.
• If merge is false but overwrite is true, then the existing object is deleted and replaced by the new object. The old object's children and access control lists, if any, are lost in the process.
Default: true.
Specifies the set of objects to be processed by an XPath expression. For information on the XPath language, see http://www.w3.org/TR/xpath.
If this attribute is not specified:
No String
objectSelector
• All of the objects in the data file are processed.
• The heuristic used to determine the order in which the objects are processed depends on the action option.
The following actions have additional options:
No String
options
• deploy - nostart prevents applications from being started after deployment.
• stop - immediate allows applications, components, bindings, and nodes to perform a quick cleanup and then stop. terminate applies only to nodes and causes the node process to be killed without any cleanup.
• install, add, remove, deploy, undeploy - resolve causes nodes to be restarted when a node is installed, a feature is added or removed from a node, or an application is deployed or undeployed from a node.
auto-resolve applies to the resource instance. It causes the node to be re-started only if needed.
stable is an option available when installing resource instances.
handle-dependenciesre-installs all dependant resource instances and restart applications that use these resource instances.
Description Req?
Type Attribute
Applicable to the add action. If an object to be added already exists and the overwrite is true, then the existing object is overwritten.
There are two ways in which an object can be overwritten: it can be merged, or created from scratch. The strategy used is determined by the
merge option.
No.
Boolean
overwrite
Default: true.
The path to the properties file containing the Administrator server location and user-specific information data.
Yes String
propsFile
Used when deleting an object.
When set to true, no attempt is made to delete the object if it does not exist.
No Boolean
skipIfNotExists
When set to false, an error is reported if the object to be deleted does not exist.
Default: false.
Length of time in seconds that a target will wait for an action to complete before reporting an error. If a timeout occurs and failOnError is true, No
Integer
timeout
the Ant task will fail. If a timeout occurs and failOnError is false, the script will report an error but the script will continue to process targets.
This option applies only to the following asynchronous actions and objects:
• deploy, undeploy - Application, Plug-in
• install and uninstall - Node, ResourceInstance
• start - Node
Default: 0, which means the task will never time out. You should not change the default unless you are creating large amounts of data and leaving the script run unattended or have a requirement that node startup satisfies a timing constraint.
create
Assume you have an environment env1 in the database. Your data file has environment env1 and a node node1. If you specify the edit action and
• createIfNotExists = false. env1 already exists, so its data is edited to match env1 in the data file. node1 doesn’t exist, so is not updated.
• createIfNotExists = true. env1 already exists, so its data is edited to match env1 in the data file. node1doesn’t exist, so it is added to env1.
force
Assume you have an environment env1 and node node1 in both the database and the data file. node1 is in the Started state. If you do a delete and
• force = false. node1 is in the Started state. There are two possible outcomes:
– The stop and uninstall are successful. node1 and env1 are deleted.
– The stop or uninstall fails. node1 is not in the uninstalled state so it cannot be deleted. The delete does not complete.
• force = true. node1 is in the Started state. There are two possible outcomes:
– The stop and uninstall are successful. node1 is deleted. env1 is deleted.
– The stop or uninstall fails. node1 is not in the uninstalled state but is forcefully deleted. env1 is deleted.
objectSelector
• objectSelector="//*"
Process all objects.
• objectSelector="//Node"
Process all nodes.
• objectSelector=”/Environment[@name=’env1’]/Node[@name=’node1’]"
Process node1 in environment env1.
overwrite and merge
Assume you have environment env1 and node2 in the database. If you specify the add action with a data file that contains env1 and node1:
• overwrite = false (merge is then ignored). Nothing happens to env1. node1 is added.
• overwrite = true and merge = false. env1 is deleted and replaced with the env1 in the data file and node2 is deleted. node1 doesn’t exist yet and is added.
• overwrite = true and merge = true. The existing env1 is updated with data from the env1 in the data file.
Nothing happens to node2 and node1 is added.
Actions
The actions that can be performed with the command-line interface affect either the objects contained in the database or the objects executing in the TIBCO ActiveMatrix runtime.
Database Actions
Database actions modify the objects contained in the Administrator database:
• add - Add an object or an association between objects, such as between an application and a node.
• edit - Edit an object.
• delete - Delete an object or an association between objects. When you delete an object, the entire tree rooted at the object is deleted starting at the leaves.
• set - Set the value of a substitution variable, map an application, component or binding to a node, set a property of a binding. This action deletes any existing entries that aren't present in the new set and adds any entries in the new set that weren't in the database.
• upgrade - Upgrade an existing application.
• promote - Make a service or reference available at the environment level for cross-environmental wiring.
• demote - Make a service or reference unavailable at the environment.
• resetPassword - Reset a user password.
Runtime Actions
Runtime actions modify the state of the objects contained in the TIBCO ActiveMatrix runtime:
• install - Install node on a host or a resource instance on a node.
• uninstall - Uninstall a node from a host or a resource instance from a node.
• deploy - Deploy a component or binding to a node, a logging configuration for a host, node, application, or component, a plug-in to the Administrator server. Also undeploys components and bindings from nodes they are no longer mapped to.
• undeploy - Undeploy an application or plug-in.
• start - Start a node, application, component, or binding.
• stop - Stop a node, application, component, or binding.