Steps for monitoring output from a script

Configure your agent to receive data from a script data source.

1. On the Agent Initial Data Source page or the Data Source Location page, select the option Command or script in the Monitoring Data Categories area.
2. In the Data Sources area, click Output from a script.
3. Click Next.
4. On the Command List page , click Add to display a Command Information window.
   Note: Selecting the Enable data collection using SSH check box enables SSH for this attribute group. If this check box is not selected, the attribute group runs locally.

   Note: If a command exists that can be run on the operating system on which the Agent Builder is running, the Test option is enabled. You can use Test to test a command that you defined.
5. In the Command Information area in the Command Information window, type a command name with the necessary arguments in the Command field, and a separator in the Separator field.
   Note:

   1. Scripts in Windows are frequently started without specifying the .bat or .cmd extension on the command line. For remote execution, a shell environment must be installed and you must specify the .bat or .cmd in the script data source command for the script to run. Cygwin is an example of a shell environment that is available for Windows. Linux®, Red Hat, and AIX®. To verify that a shell environment exists, SSH or log on to the remote host and enter the command:

      PATH=$PATH:. <command>

      If the command runs, then a shell environment exists.
   2. Use quotation marks around the name so that it is not parsed by the command interpreter. For example, this is a test.bat argument becomes:

      "this is a test.bat" argument

   3. Environment variables and configuration variables can be used in the user-provided script, but cannot be part of the command line that starts the script. The following variables are exceptions to this rule:

      AGENT_BIN_DIR

      The directory where the agent places binary files or scripts

      AGENT_ETC_DIR

      The directory where the agent places configuration files

      AGENT_LIB_DIR

      The directory where the agent places shared libraries or dynamic-link libraries

      CANDLEHOME

      The Linux or UNIX Tivoli® Monitoring installation directory

      CANDLE_HOME

      The Windows Tivoli Monitoring installation directory

   4. If the SSH data collection option is being used, the command line is run relative to the user's home directory on the remote system. If you are uploading scripts or executables to the remote system, they are copied to the location specified in the agent's environment variable CDP_SSH_TEMP_DIRECTORY. The location defaults to the user's home directory on the remote system. On some systems, you might need to define the command line with a relative path, such as ./Script.sh.
6. In the Operating Systems area, select one or more operating systems. When you collect data from a remote system by using SSH, Operating Systems is a property of the system on which the agent is installed. It is not the Operating System of the remote system. It is advised that you select the All operating systems check box when you use the SSH data collection features.
7. Optional: If one or more user-defined files are necessary to run the command, click Add in the Command files area to specify the files from your system.
   The files are copied into the project folder of the agent under scripts/operating system, where operating system is a variable that depends on what you selected in the Command Information window. These files are also packaged and distributed with the agent. If you want to edit the definition of a command file you already added, or changed the contents of, select the file and click Edit. See Editing a command file definition.
8. Click OK. The Command List page is displayed.
9. To test the command, use the following steps:
   1. Click Test to open the command information and display the Test Command window. To test the script on a remote system, select a system from the Connection name list or click Add to add the host name of a system.
   2. Use the Test Command window to change the command, default separator, and attribute separators, and to view how these changes affect the data that is returned.
      1. Type the command and separator in the fields if they are not already entered.
         Note: You can specify other separators by using the Attribute Information window at attribute creation time or by using the Agent Editor to modify an existing attribute. For more information about the Agent Editor, see Using the Agent Editor to modify the agent and for more information about manipulating data source and attributes, see Editing data source and attribute properties
      2. Before you start testing, you can set environment variables and configuration properties. For more information, see (Attribute group testing).
      3. Click OK to return to the Test Settings window.
      4. Click Start Agent. A window indicates that the Agent is starting.
      5. To simulate a request from Tivoli Enterprise Portal or SOAP for agent data, click Collect Data. The Agent Builder runs your command. If you specified a remote system, provide a user ID and password. Even if the return code is not 0, the Agent Builder parses the results of the command in the same way the agent does.
      6. The Test Settings window collects and displays any data in the agent's cache since it was last started. The initial names of the attributes are Attribute_1, Attribute_2, and so on; however, you can modify the properties of the attributes by clicking the appropriate column heading.
      7. Click Check Results to view the return code from the command, the unparsed data, and any error messages that were returned.
      8. The agent can be stopped by clicking Stop Agent.
      9. Click OK to return to the Command Information window.

         If you change the command or the separator, the appropriate command is updated to reflect those changes.

         If this window was opened when you created the script data source, the attributes were added to the new script data source.

         If this window was opened from an existing script data source, then any changes to the attributes are made to the script data source. Any additional attributes are added, but any extra attributes are not removed. These options affect only the attributes that are parsed from the script output. Any derived attributes are not affected. If any of these attributes become invalid based on the attributes they reference, you can update or remove derived attributes manually. The derived attribute formula is displayed and not the actual result value.

   Note: If the attribute group exists, to start a test, complete the following procedure

   1. Select the attribute group on the Agent Editor Data Sources Definition page.
   2. Select the script to be tested from the Command List
   3. Click Test and follow the procedure at step 9
10. If you skipped testing the command in step (9), use the following steps:
    1. On the Command List page with the completed command information, click Next.
    2. On the Attribute Information page, complete the attribute name and type information by using (Table 1). Select Add additional attributes to add further attributes
    3. On the Attribute Information page, use the Script Attribute Information tab to choose a specific data separator for this attribute.
       The standard separator ; is selected by default. You can choose a number of other separators such as a string, a number of characters, a tab, or a space. You can also choose to use a different string separator for the beginning and end of the data. Finally, you can also choose Remainder of record to assign the remainder of the record to the attribute. For more information about script parsing and separators, see Script parsing and separators.
11. Do one of the following steps:
    • If you are using the Agent wizard, click Next.
    • Click Finish to save the data source and open the Agent Editor.
12. You can add attributes and supply the information for them. For more information, see Creating attributes.
    In addition to the fields applicable to all data sources (described in Fields and options for defining attributes), the Data Sources Definition page for the Script data source has the following options:

    Command List

    Provides access to the commands and scripts to start during data collection.

    Add

    Allows the user to add a command to be started by this attribute group.

    Edit

    Allows the user to edit an existing command entry.

    Remove

    Allows the user to delete an existing command entry.

    Test

    Allows the user to access the test environment for this attribute group.

    Enable data collection using SSH

    Selecting this check box enables SSH for this attribute group. If this check box is not selected, the attribute group runs locally.

    For information about SSH remote connection configuration for script data sources, see Configuring a Secure Shell (SSH) remote connection.