Use the tacmd executecommand command to execute the system command provided in the given command.

The hub monitoring server, the targeted monitoring agents, and any remote monitoring servers to which the targeted agents are connected must be at IBM Tivoli Monitoring v6.2.2 Fix Pack 2 or later. If the Tivoli Enterprise Monitoring Agent component is at the IBM Tivoli Monitoring v6.2.2 Fix Pack 2 or later level, all the agents installed in the same CANDLEHOME directory at the endpoint are capable of handing this command. For this command, the specified system cannot be an i5/OS or z/OS monitoring agent.

File names

When either the results file name or the directory location that can be specified by using the -d|--destination, -s|--remotedestination, and -w|--workingdir options contain spaces, you must include double quotation marks around the results file name and directory location. For example, run the following command from a Windows system to list the files in the C:\Program Files directory on a Windows system, and copy the resulting result file to C:\Documents and Settings\response.out on the local computer where the command was issued:

tacmd executecommand -m Primary:WINDOWS:NT -c dir -w "c:\\Program Files" -o -l  
-d "C:\\Documents and Settings\\response.out" 

When working with file and directory names that have nonalphanumeric characters (for example, ! @ #, etc), the path and file references for the -s|--source, -d|--destination, and -w|--workingdir options must be surrounded by double quotation marks. However, paths that include an asterisk (@) sign must be escaped with an asterisk (@) sign. The path user@home@directory is escaped as follows:

user@@home@@directory

Variable substitution

Run this command using an environment variable for the result file name and directory location that can be specified by using the -d|--destination, -s|--remotedestination, and -w|--workingdir options. If used for the -s|--remotedestination or -w|--workingdir options, it is for the specified monitoring agent’s managed system rather than the local environment where the command is issued. If used for the -d|--destination option, it is for the local environment where the command is issued.

The environment variable format is @NAME@. The following characters are valid as the first character of any name, or any subsequent character:

• _ (underscore)
• Lower case alphabetic letters
• Upper case alphabetic letters

The following characters are valid as any character in any name except the first:

• - (dash)
• The following numbers, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9

The following example runs the command from a UNIX system to list the files in the C:\IBM\ITM\tmaitm6\logs directory on a Windows systems. In this example, CANDLE_HOME is c:\IBM\ITM:

./tacmd executecommand -m Primary:WINDOWS:NT 

-c "dir @CANDLE_HOME@\\tmaitm6\\logs" 

-e -o -r -l -v

To use this command, the KT1_TEMS_SECURE configuration parameter must be set in the hub monitoring server's configuration file to specify that the hub monitoring server supports this command. After setting the environment variable, you must recycle the hub monitoring server. The default value is no. Specify Y or YES or y or yes if you want to use this command.

Monitoring Agent's PATH environment variable

The monitoring agent's PATH environment variable might not have the same list of directories as the endpoint system PATH environment variable. As a result, specifying a system command for the -c|--commandstring option not located in the directories defined for the agent's PATH environment variable results in the command failing to execute. In this case, identify the full location of the system command, and then specify it along with the system command for the -c|--commandstring option.

For example, on AIX systems, the ping command is located in the /etc directory. However, a monitoring agent might not have the /etc directory in its PATH environment variable. Issuing the following ping command as shown fails:

./tacmd executecommand -m AIX:KUX -c "ping AIX" -o -e -r -l -v

  KUIEXC001I: Content of the response file 
TACMD_EXC_AIX_KUX_ping_AIX_20100420093037_60245434.log is:
  ------Command-------
  ping AIX
  ------Command Result------
  127
  ------Standard Error-------
	/usr/bin/ksh: ping:  not found.
  -------Standard Output-------

  KUIEXC000I: Executecommand request was performed successfully. 
The return value of the command run on the remote systems is 127

However, if the fully qualified path for the ping command binary is specified, the command completes successfully as shown:

./tacmd executecommand -m AIX:KUX -c "/etc/ping -c 1 AIX" -o -e -r -l -v

KUIEXC001I: Content of the response file 
TACMD_EXC_AIX_KUX__etc_ping_-c_1_AIX_20100420093428_07551048.log is:
------Command-------
/etc/ping -c 1 AIX
------Command Result-------
0
------Standard Error-------
------Standard Output-------
PING AIX.tivlab.raleigh.ibm.com: (9.42.11.174): 56 data bytes
64 bytes from 9.42.11.174: icmp_seq=0 ttl=255 time=0 ms

----AIX.tivlab.raleigh.ibm.com PING Statistics----
1 packets transmitted, 1 packets received, 0% packet loss
round-trip min/avg/max = 0/0/0 ms

KUIEXC000I: Executecommand request was performed successfully. 
The return value of the command run on the remote systems is 0

For information on identifying the PATH environment variable for the monitoring agent,, see the IBM Tivoli Monitoring Administrator's Guide, and the section on the Agent Service Interface. Also, examine the ENVFILE section to locate the PATH value.

Escaping backslashes, spaces, and double quotation marks

When defining directories or filenames, backslashes, spaces and double quotation marks must be escaped. For example, on a Windows system, if you attempt to list the files in directory C:\Documents and Settings, you must double-quote this directory. Because parameters defined for the -c|--commandstring option must be in double quotation marks, you must escape the double quotation marks used for specifying the directory with a space:

./tacmd executecommand -m Primary:WINDOWS:NT -c 
"dir \"c:\\Documents and Settings\" " -o -l -v

where:

-m|--system

Specifies on which managed system to execute the command. The specified managed system must be a monitoring agent. Use the tacmd listsystems command to view a list available systems.

-c|--commandstring

Specifies the command to run. Use double quotation marks for commands with parameters. You must escape backslashes when defining a Windows directory path. See the "Escaping backslashes, spaces, and double quotation marks" section in the preceding command description.

-w|--workingdir

Specifies the working directory that is switched to before executing the command. Environment variables are supported.

When running this command between a UNIX or Linux system and targeting a Windows monitoring agent, you must replace the backslashes with forward slashes in the path definitions for the source parameter. It is best to use forward slashes for tolerance with Windows systems.

If the -w|--workingdir option is not specified, a default directory is used. To determine the default working directory for targeted Windows systems, you can issue a ./tacmd executecommand -m ManagedSystem -c chdir -o -v command. For targeted UNIX and Linux systems, issue a ./tacmd executecommand -m ManagedSystem -c pwd -o -v command.

-o|--stdout

Requests the standard output from the command to be captured. For section separators, use the -l|--layout option.

-e|--stderr

Requests the standard error from the command to be captured. For section separators, use the -l|--layout option.

-r|--returncode

Requests the return code to be captured. For section separators, use the -l|--layout option.

-l|--layout

Requests the command string executed at the monitoring agent to be captured and adds section separators to the result file.

-t|--timeout TIMEOUT

Specifies the timeout of the command request. The TIMEOUT value is the number of seconds allowed for the specified command to complete. The range is 1 to 32400 seconds. The default is 600 seconds. The command is not stopped if the timeout limit is reached, but the output is not captured.

-d|--destination

Specifies the name of the local file on the system where the command was issued, to which the results file on the endpoint is copied. If the -d|--destination option is not specified, a default filename is given. The default filename has the following format:

TACMD_EXC_ManagedSystemName_Command_Timestamp_RND8Char.log

Where:

ManagedSystemName

Specifies the managed system name, and is filtered removing special characters like ‘:' and substituting them with ‘_'.

Command

Specifies the name of the command to be executed, is filtered by removing special characters such as colons (:) and substituting them with an underscore (_), and is truncated to 64 characters.

Timestamp

Specifies the timestamp, and is given in the format YYYYMMDDHHMMSS.

RND8Char

A random string composed of eight random numbers.

If you use the -d|--destination option, you must use one or more of the following options: -o|--stdout, -e|--stderr, or -r|--returncode. Supports environment variables, absolute paths, and relative paths. When specifying the destination directory, it must be an existing path.

-s|--remotedestination

Specifies the name of the results file at the endpoint. If the -s|--remotedestination option is not specified, the remote results file is not saved. If you specify a name without a fully qualified path, the CANDLEHOME/kt1v3depot/pc directory is used as the destination. If you use the -s|--remotedestination option, you must use one or more of the following options: -o|--stdout, -e|--stderr, -r|--returncode. Supports environment variables, absolute paths, but not relative paths.

When specifying the remote destination, it must be an existing path. When specifying the -c|--commandstring option and if you redirect the command output to a file, do not specify that same filename for this option. You can specify forward slashes instead of backslashes when targeting a Windows endpoint.

-f|--force

Overwrites the local and remote results files if they already exist. FORCE_MODE can have one of the following values: LOCAL, REMOTE, ALL. Specifying LOCAL overwrites the file defined with the -d|--destination option if the file already exists at the local computer where the command was issued. Specifying REMOTE overwrites the file defined with the -s|--remotedestination option on the target endpoint. Specifying ALL overwrites the file defined with the -d|--destination option and the file defined with the -s|--remotedestination option, if either file already exists.

-v|--view

Prints to the screen the contents of the results file. If you use the -v option, you must use one or more of the following options: -o|--stdout, -e|--stderr, -r|--returncode.

See the example in the description of this command.

See Table 6.

Return to Table 1.