Agent Installation Guide › Installing an Agent on HP-UX Systems

Installing an Agent on HP-UX Systems

This section contains the following topics:

Prerequisite

Least-Privileged User Requirements

Agent Deployment Flowchart for UNIX Platforms

Planning Agent Deployment

Deploying the First Agent

Preparing Files and Testing Silent Installation

Deploying All Other Planned Agents

Preparing New Agents for Use

Maintaining Agents

Prerequisite

Before you install the CA User Activity Reporting Module agent on an HP-UX system, you must install the patches PHNE_41060 and PHNE_41004 on the HP-UX system.

Least-Privileged User Requirements

The agent installation for CA User Activity Reporting Module agents does not offer automatic user or user group creation. Use a root account to install the agent.

While you can run the agent as a root user, it is a better security practice to create a least-privileged account for the agent to use. You can give this user any account name you like, such as elmagentusr.

The agent installation adjusts the permissions on the existing user account you specify during installation. The folder permissions include the following:

Permission 775 (rwxrwxr-x) over the CA User Activity Reporting Module Agent installation folder, its sub-directories, and files.
As owner, the account has full permissions for all of the files and directories in the agent install directory.
Other accounts have read and execute permissions.
The caelmupdatehandler executable has the setuid bit set.

Agent Deployment Flowchart for UNIX Platforms

Flowchart for deploying agents on UNIX platforms including planning, installing agent interactively on first host, creating files and testing silent installation on test host, and then deploying remaining agents with tested files.

This section is based on the following agent deployment workflow. See online help for tasks related to monitoring and maintaining agents.

Planning Agent Deployment

Before you begin agent deployments, it is a good practice to identify elements that all agent installations can share and elements unique to each installation. The more elements that agents have in common, the easier agent installations become. Elements unique to each installation are the computers on which agents are installed and computers from which the agents collect events. Elements all agents can share include the collection server that manages the agents, the credentials of the low-privileged user under which the agent service runs, and the authentication key.

Common planning tasks include the following:

Identify event sources from which to collect events.
Identify computers that meet system requirements for agent installation.
Note: See the CA User Activity Reporting Module Agent Hardware and Software Certification Matrix.
Determine the IP addresses and host names of the computers that require agents.
Identify the CA User Activity Reporting Module collection server that each agent is to register with.
Decide on a common name and group for the low privileged user for agents.
Set the authentication key to use for all agent installations. If already set, record the current setting for use during installation.
Identify the host to target for the first agent installation. This agent can be used for creating connectors and exporting Connectors.xml to be referenced in the response file.
Identify a second host to target for creating a response file and testing silent installation.
Plan a common path for saving the exported Connectors.xml, the response file, and the installation program. You specify the path for the Connectors.xml file when you create a response file. It is convenient to copy all three files to the same location when preparing for mass deployment.
Accept the default directory for agent installation, /opt/CA/ELMAgent, or determine another directory to use for all agent installations.

Deploying the First Agent

Efficient agent deployment takes planning. After determining common and unique elements for planned agents, you are ready to deploy the first agent. The recommended process follows:

Get the authentication key and installation software from the collection server.
1. View and remember the agent authentication key or set a new value.
2. Download agent binaries.
Prepare to install the first agent on a new operating environment.
1. Copy the binaries to the target host.
2. Create an <install directory> and extract binaries.
3. Create a low privileged user for the agent.
Install the first agent interactively.
Verify successful installation or troubleshoot and then verify successful installation.
1. Monitor agent installation self-monitoring events.
2. Examine agent status detail.
3. Troubleshoot the installation.

View or Set the Agent Authentication Key

If you are a CA User Activity Reporting Module Administrator, you can set the agent authentication key or view the current setting.

To view or set the agent authentication key

Click the Administration tab and then click the Log Collection subtab.
The Log Collection Explorer displays in the left pane.
Select the Agent Explorer folder.
A toolbar appears in the main pane.
Click Agent Authentication Key.
Take one of the following actions:
- Record the configured name so you have it ready to enter during agent installation.
- Set or reset it by entering and confirming the agent authentication key to be used for the agent installation.
Note: The default value is: This_is_default_authentication_key.
Click Save.

Download Agent Binaries

Download agent binaries from the collection server that is to manage the agent. Download the binaries to the computer from which you browsed to the CA User Activity Reporting Module.

To download the agent binaries

Log on to CA User Activity Reporting Module as an Administrator.
Click the Administration tab.
The Log Collection subtab displays the Log Collection Explorer in the left pane.
Select the Agent Explorer folder.
A toolbar displays in the main pane.
Click Download Agent binaries.
Links for the available agent binaries appear in the main pane.
Click the link for the desired operating environment and version.
Select a directory to download the installation file and click Save.
The CA User Activity Reporting Module server downloads the file. A message showing the download progress of the selected agent binary appears, followed by a confirmation message.
Click OK.

Note: Unless you downloaded the agent binaries to the target host, export the downloaded tar file to the target host. Then, log on to this host and extract the tar file. The directory containing the installation file is referred to in this guide as the <install directory>.

Create a Low Privileged User for a Planned Agent

While you can run the agent as a root user, it is a better security practice to create a low privileged account for the agent to use. We recommend that you create a low privileged user and group before installing the agent. Assign required permissions to the group and user.

Determine whether your site policies permit identical account on all agent hosts with passwords that never expire. If so, you can create a response file where the same agent user name can be used for all silent installations.

Note: The following procedures assume that the directory, /usr/sbin is in the system path.

To add a group and a user account for use by an agent that is not yet installed

Log into the target agent host as root and access a command prompt.
Create a group in /etc/group.
Give the primary group full permissions to support subsequent changes to this low privileged user.
Add the name of the planned low privileged user to the group you created.
Consider an easily recognized username, such as elmagentusr.
Set a password for the new user and re-enter to confirm it.

Installing an Agent Interactively

The prerequisites for installing a CA User Activity Reporting Module agent interactively are the same on any UNIX system.

Prerequisites include:

The following information for entry during the installation process
- Host name or IP address of the CA User Activity Reporting Module server to which the agent is to return events.
- Agent authentication key configured in the CA User Activity Reporting Module server.
- Name of the low-privileged user defined on the target host.
The target host location of the agent installation tar file.

When you download the agent binaries from CA User Activity Reporting Module, you save the tar file to the host from which you opened the browser to access CA User Activity Reporting Module. Copy this file to the host where you plan to install the agent. Consider creating a directory on the target host under /usr and copying the tar file to /usr/<mydirectory>.

Important! In this guide, we refer to the directory containing the file you invoke to install the agent as the <install directory>.

The installation program installs the agent and creates the agent root directory, /opt/CA/ELMAgent. The installation program refers to /opt/CA/ELMAgent as the install path.

Install the Agent on an HP-UX Host

Installing a CA User Activity Reporting Module agent on an HP-UX system is done from the command line.

To install a CA User Activity Reporting Module agent on an HP-UX host

Log on to the target host as root.
From the command prompt, navigate to the directory with the agent tar file.
Extract the contents of the HP-caelmagent.tar file.
```
tar -xvf HP-caelmagent.tar
```
The tar command creates a subdirectory named hpux_parisc_32 under the current directory.
Navigate to the hpux_parisc_32 directory.
Run the script file, install_ca-elmagent.sh, to begin the agent installation process.
```
sh install_ca-elmagent.sh
```
The license agreement appears.
Read the end-user license agreement.
A message asking if you agree to the license terms appears.
To accept the license terms, type Yes.
Enter the IP address or host name for the CA User Activity Reporting Module to which this agent forwards the logs it collects.
Important! Enter the host name if the CA User Activity Reporting Module is assigned its IP address dynamically.
Enter the authentication key defined in the CA User Activity Reporting Module server.
Enter the agent username or, if root, press Enter.
Do one of the following:
- If you want to run the Agent in FIPS mode, type YES and press Enter.
- If you want to run the Agent in non-FIPS mode, type NO and press Enter.
Enter the full path to the ca-elmagent root directory, or press Enter to accept the default, /opt/CA/ELMAgent.
Do one of the following:
- If you did not export the connector configuration file to this host, type No.
- If you did export Connector.xml, type Yes.
  A prompt that requests the default connectors configuration file path appears.
  1. Type the path.
    A message designed to determine the availability of the Connectors.xml file appears.
The following message appears: Installation of <ca-elmagent> was successful.

If you specified a low privileged user as the agent username, the installation process assigns required permissions to this user.

Agent installation on HP-UX systems creates subdirectories under the agent root directory, /opt/CA/ELMAgent. The /opt/CA/ELMAgent/install directory contains the script for uninstalling the agent.

Verify Locally that the Agent is Running

Successful agent installation typically starts the agent service. Technically, the agent service starts when the caelmwatchdog process successfully binds with the caelmagent process.

You can determine whether the agent you installed is running while still logged on to the HP-UX host.

To verify locally that the agent service is running

Change directories to the agent root directory, /opt/CA/ELMAgent.
Enter the following:
```
ps -ef|grep caelm
```
Verify that the agent, caelmagent, is running. If two lines similar to the following example appear in the command results, the agent is running.
```
root 16843 16809  0 17:58:11 ?         0:00 ./caelmwatchdog
root 16809     1  0 17:57:57 ?         0:57 ./caelmagent -b
```
If the agent service is not running, see Troubleshooting Agent Installation for remedial action.

More information:

Troubleshooting Agent Installation

Examine Self-Monitoring Events for Agent Startup

Examine self-monitoring events to determine whether the agent service of the installed agent started successfully. You can monitor the agent installation process, whether installing manually or silently.

To monitor agent registration and startup processing

Browse to the CA User Activity Reporting Module server that is managing the agent that you installed.
Click the Queries and Reports tab.
Type self in the Search field under Query List.
Select the query, System Self Monitoring Events Detail.
Create a filter that displays only events from the server where you installed the agent:
1. Click Show/Edit Local Filters
2. Click Add Filter.
3. For the column entry agent_address, type as the value the IP address of the server where you installed the agent.
4. Click Save.

Examine the self-monitoring event for System Status:

Current Reporting ELM Server set to <IP address specified as host server>

Examine the self-monitoring events for System Startup. Example events follow:
```
Registered with ELMServers successfully.
Agent's HTTP Listener started on port 6789.
Agent started successfully.
```
After the Agent started successfully message appears, view the agent status details.
If the "Agent started successfully" message does not appear, start the agent service manually as described in "Troubleshooting the Installation."

View the Agent Status Details

The Agent Explorer lists new agents as they are installed. The Agent Status Details for a selected agent displays whether the agent service is Running.

To view the agent status details

Log on to the CA User Activity Reporting Module interface with Administrator credentials.
Click the Administration tab.
The Log Collection subtab displays the Agent Explorer.
Expand Agent Explorer and then expand the Default Agent Group.
The name of the computer on which you installed the agent appears.
Click the agent name and verify on Agent Status Details that the Status is displayed as Running.
Note: The status of Not Responding indicates that the agent, watchdog, or dispatcher process is not running. Take remedial action specific to the operating environment.

Preparing Files and Testing Silent Installation

The most efficient way to deploy agents on additional hosts for a given operating environment is to configure sample connectors on the first agent, and then leverage this effort. After you create and test connectors on the first agent, you export those definitions. Then, you deploy a test agent by creating a response file that references Connectors.xml and performing a silent installation. If all goes well with this test deployment, you can confidently deploy all other planned agents with this same response file and same Connectors.xml.

The recommended process follows:

From the first agent, create and export connectors as Connectors.xml.
From a second test host, do the following:
1. Load the Connectors.xml.
2. Load the tar file and extract the contents, which includes the installation file.
3. Create a response file.
4. Perform a silent install.
5. Verify that the results are what you want for widespread deployment. If they are not, refine the files as needed.

Create and Export Connectors

Create connectors for a given operating environment on the first agent you install is a good practice. You can then export these connector configurations for use in all subsequent agent installations. Connectors are exported as a Connectors.xml file. When you specify Connectors.xml in the response file for silent installations, the agents are deployed with all connectors in place. After the silent installation with connectors, you configure the event sources that each agent targets.

Alternatively, you can skip this step and deploy each connector in bulk after installing all agents for this operating environment. With the bulk connector deployment wizard, you can create a connector for a specific integration and deploy that connector to multiple agents. With this method, you would use bulk deployment for each desired integration.

The process of creating connectors to use as templates involves the following procedures:

Identify the subscription integrations for this operating environment.
For each desired integration:
1. Configure event sources.
2. Configure one connector.
3. Examine results of event collection.
Refine the connectors
Export the connectors as Connectors.xml.

Prepare a Host for Testing Silent Installation

Before running the script to create the response file for silent installation, perform the following tasks:

Download the agent binaries, copy the tar file to this host and extract the file.
Create a low-privileged user with the planned name.
Copy the exported Connectors.xml to this host. Copy it to the directory with the installation file you extracted.

Create the Response File

On HP-UX systems, you can create a response file for installing an agent silently. This response file provides the specifications for all agents installed silently with this file.

To create a response file for silent agent installation

Log on to the host you are using for testing.
Navigate to the <install directory> where install_ca-elmagent.sh resides. For example, navigate to /usr/mydir/hpux_parisc_32.
If referencing connector configurations in the response file, verify the location of Connectors.xml.
The <install directory> is the preferred location.
Begin creating the response file, where <response_file> is the name of your choosing.
```
sh install_ca-elmagent.sh -g <response_file>
```

Respond to the following prompts exactly as if you were installing the agent locally.

Do you agree to the above license terms? [Yes or No] (No):
Enter the hostname/IP of the ELM server : 
Enter ELM server authentication code :
Enter the ELM Agent username (root):
Enter the full path to the ca-elmagent root directory (/opt/CA/ELMAgent):
Do you want to configure default connectors? (Yes):
Enter default connectors configuration file path :

A confirmation message appears.

(Optional) View the response file contents.

cat <response_file>

An example response file follows:

EULA=Y
ELM_SERVER=172.24.36.107
AGENT_AUTHKEY=my_authentication_key
AGENT_USER=elmagentusr
INSTALL_DIR=/opt/CA/ELMAgent
DEFAULT_CONNECTORS=/usr/mydir/hpux

Install an Agent Silently

You can install a CA User Activity Reporting Module agent on an HP-UX host silently with the responses stored in the specified response file.

To install a CA User Activity Reporting Module agent silently on an HP-UX host

Log on as root to the HP-UX host where you want to install the agent.
Navigate to the <install directory>, for example, /usr/<mydirectory>/hpux.
Verify that the following files reside in this directory:
- install_ca-elmagent.sh
- <response_file>
- Connectors.xml.

Run the agent installation script.

sh install_ca-elmagent.sh -s <response_file>

The following messages appear:

Running Silent installation process !
Source Depot location: /usr/<mydir>/hpux/ca-elmagent.depot
Software depot registration is done successfully
Proceeding with the Depot Installation...
Installation of 'ca-elmagent' product succeeds!

Validate Results of the Silent Installation

Before widespread deployment to multiple hosts through silent installation, validate the results of the initial silent installation of the test host.

Deploying All Other Planned Agents

Deploying the first agent and testing a response file that includes connector configurations comprises most of the work in agent deployment. By leveraging that work, you can roll out the remaining agents with much less effort.

Preparing additional hosts and installing the agents requires that you repeat some of the procedures you performed when installing the first two agents. Consider these tasks when deploying each remaining agent that is based on the first agent.

Create a directory for loading the agent installation file, response file, and connectors file. This directory is the <install directory.>
Copy the tar file to target host, and extract the contents into the <install directory>.
Copy the response file to the <install directory>.
Copy the Connectors.xml file to the <install directory>.
(Optional) Edit the response file.
This step is not needed if you elected to use common elements where possible.
Create the planned group and low privileged user.
Invoke the silent installation.
Verify successful installation.
1. Monitor self-monitoring events for agent startup
2. View the agent status details.

Edit the Response File

When you install an agent or create a response file on an HP-UX host, you specify values for the five parameters listed on the following table. If you copy this file for reuse on other systems, you can edit the original values as needed, or if appropriate, use the original values.

To edit the response file

Log on to the host where you plan to invoke the silent installation.
Navigate to the <install directory> where install_ca-elmagent.sh and the response file reside.
Use an editor of your choice to modify any of the values shown on the following table, then save the response file to the original name.

Field	Description
ELM_SERVER	The Host name or IP address of the CA User Activity Reporting Module server. Enter the host name if the CA User Activity Reporting Module server gets its IP address dynamically through DHCP.
INSTALL_DIR	The full path to the agent root directory. Default: /opt/CA/ELMAgent.
AGENT_AUTHKEY	The Agent Authentication Key. Select the Agent Authentication Key button in the Agent Explorer under Administration to view or set this key. Note: If the key value you enter during installation does not match the entry in the UI, the agent service will not start after installation.
AGENT_USER	The user name for running the CA User Activity Reporting Module agent. We recommend that you create a lower-privilege user account to run the agent before starting the agent installation. Default: root
FIPSMODE	Indicates if the Agent runs in FIPS mode. Default: OFF
DEFAULT_CONNECTORS	The exported file containing connector configurations, including the path. Leave this field blank if the Connectors.xml file is not available. Default: <blank>

More information:

How to Protect Agents from Impact of Server IP Address Changes

Preparing New Agents for Use

Use the following procedures to prepare each agent for use:

Apply subscription updates to new agents and connectors.
Complete connector configurations, including configuring the event sources.
Note: The Connectors.xml file derived from the first installed agent provides templates you can use as a basis for event-source specific connectors.
Examine query results and reports to determine whether the data is being collected and refined as expected.
Tailor the connector configurations to meet local requirements.
(Optional) Create agent groups and move the agent to the desired agent group.

Maintaining Agents

Maintenance tasks for CA User Activity Reporting Module agents include the following:

Changing the agent user, if corporate policy mandates a change.
Troubleshooting when agent installation is successful but the agent service is not started successfully
Uninstalling an agent, where the procedures can differ depending on whether installation was interactive or silent

Note: For maintenance tasks such as applying subscription updates to agents and connectors, creating agent groups, and starting or stopping agents, see online help.

Troubleshooting Agent Installation

Occasionally, process binding does not take place as expected. Use the following procedure to diagnose this error and take corrective action.

To diagnose whether the agent has started on HP-UX and start it manually if needed

Log on to the HP-UX host as root.
Change directories to the <install directory>, for example, /usr/<mydirectory>/hpux.
Display details of caelm processes.
```
ps -ef|grep caelm
```

Examine the displayed results.

A successful agent start has results similar to the following:

root 16843 16809  0 17:58:11 ?         0:00 ./caelmwatchdog
root 16809     1  0 17:57:57 ?         0:57 ./caelmagent -b
root 16811 16809  0 17:57:58 ?         0:20 ./caelmdispatcher

An unsuccessful agent start has results similar to the following:
```
root 25285     1  0 01:15:32 ?         0:01 ./caelmagent -b
```

If you determine that the agent start was unsuccessful, do the following:
1. Change directories to the location of the stopped agent, /opt/CA/ELMAgent/bin.
2. Start the agent manually
```
./S99elmagent start
```

Determine Whether an Agent Exists on a Specified Host

You can determine whether an agent is installed on a given HP-UX host.

To determine whether an agent is installed and if so what version

Log on to the host where you want to determine agent status.
Run the following command:
```
swlist -| product ca-elmagent
```
Review the last line of the system response.
- If the CA User Activity Reporting Module agent is installed, the following message is displayed, where details include the package name, version number, and description:
```
ca-elmagent 12.1.70.1 CA ELM AGENT Software Distributor
```
- If the agent is not installed on the local host, the following message is displayed.
```
Software "ca-elmagent" was not found on host <HOST>:/"
```

Change the Low Privileged User for an Agent

You can change <original_username> to <replacement_username> for the low privileged user on the agent host. When you change the user name under which the agent runs, update the CA User Activity Reporting Module UI with the new user name.

To change the low privileged user for an agent that is running as a low privileged user

Make the replacement user part of the primary group.
Set a password for the replacement user and confirm the new password.
(Optional) Remove the <original_username> from the group.
(Optional) Delete the <original_username> from the host.
Update the CA User Activity Reporting Module UI with the <replacement_username> for the agent:
1. Click the Administration tab.
2. Expand the Agent Explorer.
3. Expand the Default Agent Group or the user-defined agent group to which the agent belongs, and select the agent.
4. Click Edit Agent Details.
5. Enter the new user name.
6. Click Save.

Uninstall an Agent

You can uninstall a CA User Activity Reporting Module agent on an HP-UX host.

To uninstall an agent on HP-UX

Log on to the target HP-UX system.
Navigate to /opt/CA/ELMAgent/install.
This directory contains the script to uninstall the agent.
Run the unininstall_ca-elmagent.sh script.
```
sh uninstall_ca-elmagent.sh
```
The following message appears, followed by the location of the resulting log file:
```
Uninstallation of 'ca-elmagent' is completed! 
```