Welcome to CTL Dispatch

CTL is distributed control dispatching framework and toolset. CTL provides the missing development framework for people who need to automate the management of software services or automate any other IT task that spans multiple machines. It helps you avoid the drudgery and complexity of scripting distributed and coordinated actions, letting you focus on your administrative "business logic".

You can use CTL in several "modes":

• The ctl-exec command lets you use the dispatch functionality on the fly. Use ctl-exec whenever you want to perform a distributed execution of an arbitrary shell script or set of system commands. You can also call ctl-exec from any existing scripts you may have.
• The ctl command enables you to break management processes into reusable control modules and execute them in distributed fashion over the network (managed by the underlying control dispatching framework). You can also create workflows (with error handling) that span multiple commands and execute across multiple machines. Ctl comes with sets of pre-built automation utilities that you can call from your own scripts, use individually, or leverage to create your own automation modules.
• JobCenter provides a web-based alternative to CTL's command line interface. It also has a built-in job scheduler and full access control. CTL is great for handing off commands to lesser trained staff or other groups, enabling them to serve themselves in a safe manner. CTL is also great for allowing multiple people to simultaneously follow the execution of important processes.

ctl-exec	ctl

CTL is free, open source software licensed under the Apache 2.0 License and grew out of work from ControlTier Software's automation solutions. While CTL is a new project, all of the bits and pieces that come together to make CTL are in production use in large online operations somewhere today.

A control dispatcher is a handy tool to have in your toolbox. CTL can help you quickly and more reliably perform administration tasks in any multi-node environment. CTL also helps you leverage and optimize your current scripting methods and existing tooling for distributed environments.

• Execute sophisticated procedures across distributed environments - Aren't you tired of writing and then endlessly modifying scripts that loop over nodes and invoke remote actions? CTL dispatches actions to all hosts with network abstraction (over SSH), parallelism, and error handling already built in.
• Comes with pre-built utilities - CTL comes with pre-built utilities so you don't have to script actions like file distribution or process and port checking.
• Define your own automation using the tools/languages you already know - New controller modules are defined in XML and your scripting can be done in multiple scripting languages (Perl, Python, etc.), *nix shell, Windows batch, and/or Ant.
• Cross platform administration - CTL is Java-based, works on *nix and Windows.
• Standard framework - In almost every case, a modern software developer wouldn't dream of writing an application without relying on an application framework. The same principle is true of writing automation. Having a standard framework to leverage not only saves you time and many headaches, but it makes it easy to work in a group and share reusable (and self-documenting) automation modules.

CTL is simple to install either via the CTL-only distribution or the ControlTier Installer.

If you are new to CTL, use the installer!

After the CTL software installation, you register the nodes you want to manage. After that, you are ready to start using CTL.

The first examples show the use of the ctl-exec utility. Ctl-exec allows you to dispatch any command you would normally type into a shell:

1. Get the uptime on all unix servers:

ctl-exec -I os-family=unix -K -- uptime

The "-K" flag means to keep going if an error is encountered along the way. The "-I" flag filters which nodes to include in the distributed execution.

2. Check if the Linux web servers are listening on port 80:

ctl-exec -X tags=QA -I os-name=Linux -K -- netstat -an |grep 80

The "-X" flag specifies what nodes to exclude, in this case exclude those tagged as QA. The "-I" (include) and "-X" (exclude) flags can be combined to define very fine grained filtering for which nodes to target.

3. Silly example showing dispatched arbitrary unix script:

ctl-exec -C 1 -I os-family=unix -- "if test -f /etc/motd; then cat /etc/motd; fi"

The "-C" flag specifies threadcount. This example specifies one thread (the default) but you can choose more to control parallelism.

4. Run the local zombies.sh script across all the machines using 10 threads. The zombies.sh script will first be distributed to all targets before execution:

ctl-exec -C 10 -s zombies.sh

5. Execute the following commands via stdin input (aka a here doc):

Sometimes you want to run more than one command statement as one logical block of script across more than one machine. For the shells that support it (eg bash), the here document format is a convenient way to input multi-statement procedures via stdin.

This example executes several script statements, presumably to distribute and restart the Apache httpd processes.

ctl-exec -K -I tags=apache --stdin <<END
  curl http://repo:8080/webdav/default/httpd.conf -o /etc/httpd/conf/httpd.conf;
  /usr/sbin/apachectl configtest;
  sudo /usr/sbin/apachectl restart;
  ctl -m netutil -c listening -- -port 80;
END

One thing to note about this example, is how a looping FOR-EACH control structure is implicitly provided to you via ctl-exec. This greatly reduces the scripting complexity that many administrative shell scripts often must employ. ctl-exec does the dispatching, letting you concentrate on just the task-specific procedures.

The second group of examples show how to execute defined commands via ctl. This allows you to dispatch actions to controller modules. These examples show off the commands available in the bundled modules called coreutils. To run the commands defined in modules, you will need to also install CTL on the remote hosts. This ensures the needed modules are present on the remote machines.

6. Check if the web servers are listening on port 80:

ctl -I "web.*" -m netutil -c listening -- -port 80

This example shows the defined command called "listening" from the netutil module.

You can also see the ctl command also supports the node filtering, threadcount and keepgoing flags.

7. Distribute a file from a repository to all the myapp hosts:

ctl -I tags=myapp -X localhost -m fileutil -c copy -- \
      -file http://repo/myapp/file1.txt -dest /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.

8. Run the available command across all the machines in dev using 10 threads:

ctl -C 10 -I tags=dev -m fileutil -c available -- -file /myapp/file1.txt

This checks to see if the file "/myapp/file1.txt" is present.