Project home

Home

Project page

Download

Documentation

License

Project description at initialization time

The ctl tool is a generic application control script which can be used to start/stop or query the status of virtually any application running on a host. It is not a script to start desktop applications but to maintain server applications usually called 'daemons'. I initally wrote this tool for the company I am working for and now I am already done with my negotioations to make it Open Source.

The easiest way to describe most of its features will be an example. The following example shows how to control JBoss using ctl.

CTL usage (usage screen):
Usage: ctl <action> <handler>

Where:
<action> The action to apply to the listed handlers.
Supported actions:
start, stop, restart, status,
maint, nomaint, critical, notcritical,
list

<handler> A space-separated list of handlers to apply the action on.
jboss, all, haprocs
While 'haprocs' referst to daemons only and
'all' is a synonym for listing all handlers.

Examples:
ctl start all
ctl stop all
ctl maint handler1
ctl restart handler1
ctl nomaint handler1

As you can see the tool supports start, stop, restart, status, maint, nomaint, critical, notcritical, list actions which are pretty much self-descriptive.

The tool comes along with an application framework. The framework structure looks like this:
/opt/<app>/home [home directory of application user]
/opt/<app>/envsetup [called from users profile to setup environment variables]
/opt/<app>/x.y [application installation directory where x.y is the application version number]
/opt/<app>/current [symbolic link pointing to the version number]
/opt/<app>/current/bin [binaries]
/opt/<app>/current/lib [libraries]
[...]

Additionally envsetup sets a bunch of variables like $RUN, $LIB, $CONF $TOOLS pointing to the appropriate application directories.
Since almost all applications are using a similar structure (or can be installed into such a structure) ctl can handle them quite easily.
Everything needed to set up the application to be controlled by ctl is to install it into the 'x.y' directory in the structure shown above. The tool relies on an application user having /opt/<app>/home as its home directory but for applications like tomcat, apache, jboss etc. it is anyway a good idea to create a run-time user for them.
To integrate the application there is a configuration file called $RUN/ctlenv where all handlers (processes) can be entered either as a DAEMON or NONDAEMON. This sepparation is necessary for clustered use. NONDAEMON processes are assumed to exit and there is no reason for a cluster to failover if such an application fails. If a DAEMON fails it can be restarted or a failover might be necessary (this decision is up to the cluster agent then).

Each handler can have its own 'env' file. In my example there is a 'jbossenv' file. This file is sourced before JBoss is started to set up handler-specific environment. It might also contain environment variables used to configure ctl to re-direct the stdout specifically for this handler for example.

If a startup procedure is too complicated or very application specific it is possible to write a handler-specific start() and shutdown() shell function (to be simply defined in the env file). Alternatively it is possible to write a <handler>start or <handler>stop script which will be run instead of the internal startup routines in case they are present. This still allows using 'ctl start <handler>' to run the handler.

This framework dramatically increases application handling unification. A supporter can simply log on to a system and use 'ctl status all' to see the status of all handlers for this application. He/she even does not have to know the handler names or how they are started/stopped since a simple 'ctl list all', 'ctl start <handler|all>', 'ctl stop <handler|all>' will work everywhere.

Additionally it is extremely simple to write startup scripts at /etc/init.d/ which are completely generic (the script does not even have to know the appliction path or name).

In clustered environments you would have to buy very expensive application-agent scripts specific for each application since each application is handled uniquely. Using ctl a simple ctl-agent can be used for all applications. This dramatically decreases clustering costs and simplifies the environment. I even wrote a script which can simulate a monitoring cluster. It runs in the background and restarts crashed applications automatically. Since it uses ctl there is not even a configuration needed for this tool to work in different environments.

My plans:
I plan to distribute a generic ctl/environment framework and additional application-specific packages. The app-specific packages would contain in case of JBoss only the ctlenv (ctl configuration file having 'jboss' pre-configured in the DAEMON list) and a jbossenv file used to prepare the JBoss running environment.

Technical details:
The complete environment is tested on Sun Solaris (2.6, 8, 9 and 10) and is based on the common 'ksh'. However the script already contains compatibiliy code for Linux/Bash and is supposed to work there as well. However this is not yet fully tested but will be for sure in the near future.
It does NOT make any use of 3rd party programming languages and just relies on a set of basic Unix tools like sed, ps, grep and cat.