CTL-EXEC Command Reference

ctl-exec [-h] [-v] [-V] [-q]
[-threadcount <1>] [-K] [-I filter] [-X filter] [--filter-exclude-precedence true/false]
[-p project] 
[[-s scriptfile] | -stdin | [-- command-string]]

The CTL-EXEC command is used to remotely execute ad-hoc shell commands on a set of nodes which are specified by the filter options.

ctl-exec invocations are composed of four sections:

ctl-exec [general options] [node dispatch options] <project> [command option]

If either one or both of -I and -X are specified, then the command is executed on the set of nodes matching the filters. Otherwise, it is executed on all nodes found.

See Concepts > Node Dispatch, and Node Filtering Options for more information.

The set of nodes used as the basis for filtering is read from the nodes.properties file for the specific Project that is specified using the -p option:

The project name argument -p is optional only when there is a single project. Otherwise it is required.

The CTL-EXEC command executes in two modes, depending on whether required arguments are specified or not: Command Mode, and Listing Mode.

Command Mode

Command mode occurs when the -p option is present (or there is only one Project), ando one (and only one) of the following options are specified.

Command Mode: Run specified commands after "--"

The remote (or locally) shell command that is invoked is specified after the -- on the command-line.

This string should begin with the command name and be followed by any arguments you want to pass to it.

Examples:

ctl-exec -I tags=web -- apachectl restart

Executes the "apachectl restart" command across all nodes tagged as "web".

ctl-exec -p MyProject -- whoami

This executes the shell command "whoami" on all nodes in the project "MyProject".

ctl-exec -- apachectl stop

If there is only one project, then the -p option can be left off. This executes "apachectl stop" on all nodes in the one available project.

ctl-exec -p MyProject -X os-family=windows -- ps -u 

This executes "ps -u" on all non-Windows nodes in project MyProject.

ctl-exec -p MyProject -I hostname=web.* -K -- apachectl status

This executes "apachectl status" on all nodes matching hostname "web.*", and uses -K to keep going if any node causes an error.

ctl-exec -p MyProject -I tags=dev -K -C 3 -- sh -c update.sh 

This executes "sh -c update.sh" on all nodes with the tag dev, using -K, and specifies -C 3 so that the executions happen concurrently on 3 threads.

Command Mode: run specified script "-s script"

Sometimes it is preferable to save a sequence of command statements into a file on the admin host and then execute that file across a number of target hosts. The script specified via the -s option is a script local to where the ctl-exec command is executed but that script file is copied to the remote target machines and then executed.

Examples:

ctl-exec -s myscript.sh

Executes the script, "myscript.sh", across all nodes.

ctl-exec --script myscript.sh

Same as above.

Note: The script file is copied to a temporary directory on the target machines (on unix it is /tmp and on Windows c:\windows\temp)

Command Mode: executed input read from STDIN "--stdin"

As an alternative to specifying the commands either as deferred arguments after the double hyphen ("--") or as a saved script ("-s script"), ctl-exec can also read command input from stdin.

Examples

echo "uname -a" | ctl-exec --stdin 

Execute the "uname -a" command across all nodes. Uses a command pipeline to print commands that are read via stdin.

ctl-exec --stdin <<END
  statement 1;
  statement 2;
  statement 3;
END

Use a here document to input several command statements via stdin.

Note: The input read from stdin is saved to a temporary file and then ctl-exec uses the -s script mode described above to transfer and invoke the script.

Listing Mode

CTL-EXEC will enter Listing Mode when no Command String is specified on the command line.

In this mode, CTL-EXEC will output the list of available nodes.

Example:

$ ctl-exec
Daffy porky

When the -v (verbose) option is specified, the node listing will include the details about the nodes that can be used for filtering:

• Hostname
• OS Architecture
• OS Family
• OS Name
• OS Version
• Tags

With -v:

$ ctl-exec -v
Daffy:
   hostname: Daffy.local
   os-arch: i386
   os-family: unix
   os-name: Mac OS X
   os-version: 10.5.2
   tags: [development]
porky:
   hostname: porky
   os-arch: x86
   os-family: windows
   os-name: Windows XP
   os-version: 5.1
   tags: [testing]

When combined with the -I/-X Node Filtering options, you can easily determine which nodes will be the target of any remotely executed command prior to invoking it:

$ ctl-exec -v -X os-family=unix
porky:
   hostname: porky
   os-arch: x86
   os-family: windows
   os-name: Windows XP
   os-version: 5.1
   tags: [testing]