Control with existing scripts

After your packages are installed, it is often necessary to perform one or more management procedures. These management procedures might control the runtime state of a server application, invoke an administrative function, check some condition, or retrieve some data (performance or application data).

You probably have some of these procedures formalized into locally written scripts. If not, they might be documented in a Wiki. Of course, the procedures might not be formalized yet, typed in by hand, whenever they need to be performed.

This document describes several methods to use your existing procedures to control applications.

Tags allow you to create a simple classification scheme for your nodes. You can categorize your nodes any way you find appropriate but here are two possibilities:

Tagging by role

You might define a tag to describe a role your nodes play. For example, you might define a tag named "tomcats" to represent the set of nodes where you run your tomcat servers. You might have a another tag called "qa" to represent the set of QA nodes. Nodes often play multiple roles and therefore you can you define multiple tags for each node.

Tagging by procedure

Besides using tags to define a role your nodes play, you can also define tags to reflect local operational conventions. For example, you might have an accepted file system layout across nodes and maintain several sets of standardized scripts for managing your software control operations. These scripts might be related to controlling a particular application tier (eg, the "app" or "web" tier) or they might be used for controlling a particular phase of a software release (eg, "start-maintenance" or "end-maintenance").

Depending on preference, you can define tags either via text file or via Workbench's GUI.

Defining tags via text file

CTL is actually driven by a configuration file called nodes.properties that contains metadata about your nodes. Each project depot has its own nodes configuration file: $CTL_BASE/depots/<project>/etc/nodes.properties

Below is an example entry for a node named "centos". The bolded text is the entry for the tags:

# centos
node.centos.description=a development sandbox host
node.centos.type=Node
node.centos.name=centos
node.centos.hostname=centos
node.centos.os-arch=i386
node.centos.os-family=unix
node.centos.os-name=Linux
node.centos.os-version=9.2.0
node.centos.tags=sandbox,dev,admin

You can define any tag name you require.

Defining tags via Workbench

To tag nodes via Workbench, first go to the "Node Manager" and locate the node to which you want to add a tag. Hover over the node name and the Edit button will appear. Click the edit button.

The edit form will contain a section for tags. You can select previously defined tags or add a new one.

After you save the change you will see the new tag name appear when viewing that object.

CTL allows you to execute commands based on tag names. This lets you target adminstrative actions logically, without having to think about specific nodes. Via the ctl-exec command, you can execute actions in a number of manners:

• Single remote command. The first method lets you execute a remote command. Use the "--" (double dash) to separate the ctl-exec options from the command you want to run: ctl-exec -- <your command>.

  ctl-exec assumes the command does exist on the remote end.

• Multi-line remote script. In cases you need to run a multi-step procedure use the "-S" option ctl-exec will read your scripts from stdin:

  ctl-exec -S <EOS
  command statement 1;
  command statement 2;
  ...
  command statement N;
  EOS
  	

  As in the single-command case above, ctl-exec assumes the command statements can be executed on the remote end.

• Local script copied then executed. In cases, where you can't assume the remote command or script exists, you can specify a local script. The ctl-exec command will first copy it to the remote node and then execute it: ctl-exec -s /path/to/localscript

See the running ctl-exec documentation for user documentation or the reference page for ctl-exec more information.

Running commands via CLI

The general ctl-exec syntax is as follows:

ctl-exec [dispatching-options] [execution-options]

To execute a single remote script on all nodes tagged "tomcats" run:

ctl-exec -I tags=tomcats -- /usr/local/tomcat/shutdown.sh

You might prefer to maintain a set of scripts on an administrative node and then copy those scripts and execute them remotely. For example, imagine that a set of standard administrative scripts are kept in a directory named /adm/bin on the central admin host:

ls /adm/bin
tomcat-finish.sh*  tomcat-prepare.sh*  tomcat-restart.sh tomcat-start.sh  tomcat-stop.sh
      

You can use the "-s <local-script>" option to have a local script copied and then executed. The following example shows the tomcat-restart.sh script being copied and executed to all nodes matching tag "tomcats":

ctl-exec -I tags=tomcats -s /adm/bin/tomcat-restart.sh
      

Running commands via JobCenter

You can run any ctl-exec command via JobCenter as a job. JobCenter is useful when you want to delegate a formalized procedure to someone else.

You can define new jobs via an XML file. The following example defines a script executed on all nodes tagged "tomcats":

<joblist>
  <job>
    <name>apache-tomcat-5.5.26 startup.sh</name>
    <description>Calls existing Tomcat startup script on all tomcat nodes</description>
    <additional><![CDATA[
<p>Demonstrates ad-hoc script execution via <code>ctl-exec</code>
      to call existing Tomcat <code>startup.sh</code> procedure. 
Calls the command on all nodes tagged <i>tomcats</i> </p>
    ]]></additional>
    <context>
      <depot>default</depot>
    </context>
    <script><![CDATA[
#!/bin/bash
export CATALINA_HOME=/demo/apache-tomcat-5.5.26;
export CATALINA_BASE=$CATALINA_HOME;
$CATALINA_HOME/bin/startup.sh;
    ]]></script>
    <nodefilters excludeprecedence="false">
      <include>
        <tags>tomcats</tags>
      </include>
    </nodefilters>
  </job>
</joblist>
	

Inside the <script></script> tags, is a multi-line bash script to run the Tomcat startup.sh command.

Store this xml in a file named /tmp/jobs.xml, and then to upload this job definition to JobCenter using the ProjectBuilder load-jobs command, execute the following:

ctl -p default -M ProjectBuilder -c load-jobs -- -file /tmp/jobs.xml

Of course, you can define the same job via the JobCenter UI. Push the "Create a new job" button, and type in the command or script you wish to execute: