Agent Tools

Agent Tools is a suite of shell scripts, batch files, and Python scripts specifically designed to retrieve and modify information about Managed Servers. The information is retrieved from and modified in the SA database.

Using the scripts, you can retrieve and modify such data as custom fields, customer assignments, custom attributes, and more. Given this ability, you can automate many procedures that in the past had to be accomplished on a server-by-server basis.

In addition, you can incorporate the information the scripts retrieve into customized scripts of your own design. Since information such as customer assignment and custom attributes varies from managed server to managed server, the ability to retrieve and use this information on-the-fly in customized scripts can be very useful.

For example:

• You may have a script that handles post-installation configuration for a certain application that must be able to discover the Facility name in which the server is registered. Agent Tools provides a script to get the Facility name and insert it into your post-installation script without manual intervention.
• When installing a monitoring agent, a post-installation script must modify a configuration file to include the IP address of the monitoring server in that particular facility. Agent Tools provides a script to discover the monitoring server’s IP address by reading a custom attribute on the Core so that it can be inserted into the configuration file.
• A DSE can be written to retrieve the EEPROM version from many servers and store that information as a custom attribute or custom field.

Some other uses of Agent Tools scripts include:

• Gathering information from an SA Core during software installation for use in configuration.
• Storing metadata from managed servers in the SA database while executing a DSE, Global Shell script, or software installation.
• Retrieving custom attribute information for Managed Servers.

Following topics are discussed in this section:

• Installation requirements
• Installation
• Upgrading Agent Tools
• Agent Tools scripts
• Sample Agent Tool scripts

Installation requirements

The Agent Tools suite has the following requirements:

Operating System support

Agent Tools supports the operating systems supported by the SA Managed Servers. For a list of supported operating systems, See the Server Automation Install section.

Security, access control, and authentication

Agent Tools must be run as the root user on UNIX/Linux systems or as the Administrator on Windows systems. Agent Tools use the Server Agent's certificate to connect to the Web Services Data Access Engine (twist) which is pyTwist’s default behavior, and is granted the privileges that the Web Services Data Access Engine gives to the Agent. This typically applies to read/write privileges on the server from which Agent Tools is run, therefore, no user authentication is required.

An exception is the set_customer script. You must have read access to a customer to be able to associate a server with that customer. Agent certificates do not have read access to other customers, therefore the user must authenticate when running this script.

Running Agent Tools scripts on Windows is not supported when UAC (User Access Control) is enabled.

Other requirements

• Access privileges to pyTwist
• Access privileges to the SA API

• Installed Python 2.4 (shipped with the Server Agent)

Installation

Agent Tools is installed in the Core during the normal HPE SA Installer Core installation process. However, you must also install Agent Tools on your Managed Servers to make it available on those servers. This section describes that process.

Agent Tools is installed on Managed Servers as a set of executable scripts. Depending on your operating system, these will be shell or batch scripts and Python scripts which are called by the shell and batch scripts. You can run these scripts from a managed server to retrieve and modify information in the SA Core. These scripts can be run manually or called from package installation scripts, DSEs, Global Shell scripts, and so on.

Agent Tools is included as part of the Python SA API Access (pyTwist) software policy. This policy is located in the directory:

/Opsware/Tools/Python Opsware API Access

Manually installing Agent Tools

To install Agent Tools on a Managed Server:

1. Launch the SA Client.
2. Go to the Managed Servers list and select the Managed Server(s) on which you want to install Agent Tools.
3. Right click and select Install Software.
4. Select the Python Opsware API Access software Policy.
5. The Software Policy installation wizard will guide you through the rest of the process.

Installing Agent Tools when installing an Agent

Alternatively, you can specify the Python SA API Access software Policy ID and specify that it be remediated during Agent installation. For information about Agent installation, see Administer.

Upgrading Agent Tools

Since Agent Tools is provided as a software policy (part of the pyTwist software policy), you can upgrade to newer versions of Agent Tools by performing a remediation after upgrading the core.

When the SA core is upgraded, the Python SA API Access software policy is also updated; any old versions of Agent Tools are removed and new versions are attached to the policy. After the SA Core upgrade (during which Agent Tools will be automatically upgraded as part of the core upgrade), you can then upgrade Agent Tools on the Managed Servers by performing the following tasks:

1. Select the managed servers that have had Agent Tools installed. You can see a list of the servers and groups attached to the Python SA API Access software policy by opening the policy itself.
2. Right click on the selected servers and choose Remediate.
3. Select the Python Opsware API Access software policy.
4. The old versions of the pyTwist and Agent Tools packages are removed, and the new versions are installed.

Data migration

Since Agent Tools keeps no persistent data on the managed server, there's no requirement for data migration or preservation.

Agent Tools scripts

Usage

<scriptname>.py|bat|sh --arguments

Agent Tool scripts

Script	Function
get_all_cust_attr	Retrieves all custom attributes for a server record. Usage: get_all_cust_attr.py [--localonly] [--mode=python|shell|pretty] The mode determines the format for the output (such as Python dictionary, shell statements, etc.). Pretty is the default. Note Shell mode does not work when there are multi-line custom attributes.
get_cust_attr	Retrieves the value of a single custom attribute. Usage: get_cust_attr.py [--localonly] <custom attribute name>
set_cust_attr	Sets the value of a single custom attribute on the server. Usage: set_cust_attr.py <custom attribute name> <custom attribute value>|--valuefile <path to file with value in it>
del_cust_attr	Deletes a custom attribute from the server's record in the database. Usage: del_cust_attr.py <custom attribute name>
get_cust_field	Retrieves the value of a single custom field. Usage: get_cust_field.py <custom field name>
set_cust_field	Sets the value of a single custom field on the server. Usage: set_cust_field.py <custom field name> <custom field value>|--valuefile <path to file with value in it>
get_customer	Retrieves the customer name that the server is associated with. Usage: ./get_customer.py
set_customer	Sets the customer name that the server is associated with. Usage: set_customer.py <customer name>
get_facility	Retrieves the name of the Facility that the server is associated with. Usage: ./get_facility.py
get_info	Prints out all fields for a server (in a format similar to the server's info file in OGSH). Usage: get_info.py
get_history	Prints out server specific events. Usage: get_history.py --startdate <start date in seconds since epoch> [--enddate <end date in seconds since epoch>] [--username <SAS user name>] [--password <SAS password>]
sub_text_file	Reads in a text file, looks in the file for tokens/parameters, replaces them with the value of custom attributes, and prints the amended file to stdout. See below for more info on the expected file format. Usage: sub_text_file.py [--localonly] <path to file with tokens in it>

Formatting for the sub_text_file script

Text files passed to the sub_text_file script can have any content, however, the script looks for any lines with two @ characters and will treat the string between and including the @ character pairs as a token. You can have a single @ character on a line, it will be ignored, however a second @ character on the same line will cause any text between the two @ characters to be treated as a token.

The tokens are replaced with the value of the custom attribute specified between the @ signs. For example, the string @dns_server@, is replaced with the value of the custom attribute dns_server. If this custom attribute does not exist or its value is empty, the token is replaced with an empty string.

Take a text file that contains the entry:

IP: @monitoring_server_ip@

The script will output will look similar to the following:

IP: 82.159.202.117

Where IP is the value retrieved by monitoring_server_ip.

Output

The sub_text_file script outputs to stdout. You can redirect the output to a file if needed. You can also use a .template file stored in your zip file to format the output. For example:

$AGENTTOOLSPATH/sub_text_file.sh petstore_config.template > petstore_config.cfg

Sample Agent Tool scripts

The following are simple examples of using Agent Tools scripts.

UNIX/Linux

This example puts a message containing the name of the facility in the Message of the Day (MOTD) that users see when they log into the UNIX server.

. /etc/opt/opsware/pytwist/pytwist.conf
facility_name=`$AGENTTOOLSPATH/get_facility.sh`
echo "You have connected to a server in the $facility_name facility. For hardware information on this server as stored in Opsware, run $AGENTTOOLSPATH/get_info.sh." > /etc/motd

Windows

This Windows example puts a text file on all users' desktops with information about the server.

call "C:\Program Files\Common Files\Opsware\etc\pytwist\
pytwist_conf.bat"

call"%AGENTTOOLSPATH%\get_info.bat" > "%SYSTEMDRIVE%\Documents and Settings\All Users\Desktop\server_info_from_Opsware.txt"

1. Do not hard code the path to Agent Tools Instead you must do the following:
   
   Source the PyTwist configuration file:
   
   UNIX:
   ./etc/opt/opsware/pytwist/pytwist.conf
   
   Windows:
   call
C:\Program Files\Common Files\Opsware\etc\pytwist
\pytwist_conf.bat
2. Use the environment variable:
   
   UNIX:
   $AGENTTOOLSPATH

   Windows:
   %AGENTTOOLSPATH%
   
   Using this method will prevent errors in your scripts should the path to Agent Tools change in future.