Agent Installation Guide › Installing an Agent on Solaris Systems

Installing an Agent on Solaris Systems

This section contains the following topics:

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

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

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:

1. 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.
2. 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.
3. Install the first agent interactively.
4. 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

1. Click the Administration tab and then click the Log Collection subtab.

   The Log Collection Explorer displays in the left pane.

2. Select the Agent Explorer folder.

   A toolbar appears in the main pane.

3. Click Agent Authentication Key.
4. 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.

5. 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

1. Log on to CA User Activity Reporting Module as an Administrator.
2. Click the Administration tab.

   The Log Collection subtab displays the Log Collection Explorer in the left pane.

3. Select the Agent Explorer folder.

   A toolbar displays in the main pane.

4. Click Download Agent binaries.

   Links for the available agent binaries appear in the main pane.

5. Click the link for the desired operating environment and version.
6. 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.

7. 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

1. Log into the target agent host as root and access a command prompt.
2. Create a group in /etc/group.
3. Give the primary group full permissions to support subsequent changes to this low privileged user.
4. Add the name of the planned low privileged user to the group you created.

   Consider an easily recognized username, such as elmagentusr.

5. 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 a Solaris Host

Installing a CA User Activity Reporting Module agent on a Solaris system is done from the command line.

To install a Solaris agent

1. Log on to the target host as root.
2. From the command prompt, navigate to the directory where you saved the agent tar file and extract the contents of the agent tar file.
3. Navigate to the install directory with the agent package file, ca-elmagent.pkg.
4. Run the following command.

   pkgadd -d <elmagent_solaris.pkg>
   

   A message asking you to select the package to process appears.

5. Press Enter to select the default, all.

   The license agreement appears.

6. Read the end-user license agreement. To accept, type Yes.
7. If you selected a custom install, either accept the installation path or change it and click Next.
8. 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.

9. Enter the authentication key defined in the CA User Activity Reporting Module server.
10. Enter the agent username or, if root, press Enter.
11. 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.
12. Enter the full path to the ca-elmagent root directory, or press Enter to accept the default, /opt/CA/ELMAgent.

    A message designed to determine the availability of the Connectors.xml file appears.

13. Do one of the following:
    • If you did not export the connector configuration file to this host, type No.

      Note: No is the typical response for the first installation.

    • If you did export Connector.xml, type Yes.

      A prompt that requests the default connectors configuration file path appears.

      1. Type the path.
14. Type Y to create the ca-elmagent root directory.
15. Type Y to continue with the agent installation.

    The following message appears: Installation of <ca-elmagent> was successful. If you specified a low privileged user as the agent username, the installation process assigned required permissions.

Note: Technically, the agent service starts when the caelmwatchdog process successfully binds with the caelmagent process. To verify that a successful bind occurred or to troubleshoot a bind failure, see Troubleshooting Agent Installation.

More information:

Troubleshooting Agent Installation

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 Solaris host.

To verify locally that the agent service is running

1. Change directories to the agent root directory, /opt/CA/ELMAgent.
2. Enter the following:

   ps -eaf|grep caelm
   

3. 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
   

4. 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

1. Browse to the CA User Activity Reporting Module server that is managing the agent that you installed.
2. Click the Queries and Reports tab.
3. Type self in the Search field under Query List.
4. Select the query, System Self Monitoring Events Detail.
5. 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.
6. Examine the self-monitoring event for System Status:

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

7. Examine the self-monitoring events for System Startup. Example events follow:

   Registered with ELMServers successfully.
   Agent's HTTP Listener started on port 25275.
   Agent started successfully.
   

   After the Agent started successfully message appears, view the agent status details.

8. 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

1. Log on to the CA User Activity Reporting Module interface with Administrator credentials.
2. Click the Administration tab.

   The Log Collection subtab displays the Agent Explorer.

3. Expand Agent Explorer and then expand the Default Agent Group.

   The name of the computer on which you installed the agent appears.

4. 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:

1. From the first agent, create and export connectors as Connectors.xml.
2. 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:

1. Identify the subscription integrations for this operating environment.
2. For each desired integration:
   1. Configure event sources.
   2. Configure one connector.
   3. Examine results of event collection.
3. Refine the connectors
4. 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:

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

Create the Response File

On the Solaris host you are using for testing, create a response file. A response file provides the specifications for all agents installed silently with this file.

To create a response file for silent agent installation

1. Log on to the host you are using for testing.
2. Navigate to the <install directory> where the ca-elmagent.pkg and Connectors.xml files reside.
3. Begin creating the response file, ca-elmagent.rsp.

   sh install_ca-elmagent.sh -g ca-elmagent.rsp  
   

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

   Select package(s) you wish to process (or 'all' to process all packages). (default: all) [?,??,q]:
   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 or No] (Yes): 
   Enter default connectors configuration file path : 
   

   A confirmation message appears.

5. (Optional) View the response file contents. An example follows:

   EULA=Y
   ELM_SERVER=172.24.36.107
   AGENT_AUTHKEY=my_authentication_key
   AGENT_USER=elmagentusr
   FIPSMODE=OFF
   INSTALL_DIR=/opt/CA/ELMAgent
   DEFAULT_CONNECTORS=/usr/mydir/connectors.xml
   

Install an Agent Silently

You can invoke a silent installation of an agent on a Solaris server. Use the response file composed of values for this agent installation. You must be logged in as a root user to run a silent installation. The <install directory> must contain the ca-elmagent.pkg and the ca-elmagent.rsp files.

Before you invoke a silent install, review the response file settings. If the response file contains a value other than root for AGENT_USER, verify that a low privileged user with this name has been defined on this host. If the response file includes a path for DEFAULT_CONNECTORS, verify the Connectors.xml resides in that path.

To invoke a silent install

1. Navigate to the directory where you saved the binary (ca-elmagent.pkg) and response file (ca‑elmagent.rsp).
2. Run the following command to install an agent silently, where ca-elmagent.rsp is the name of the response file.

   pkgadd -d ca-elmagent.pkg -n -a admin -r ca-elmagent.rsp ca-elmagent
   

   The agent is installed using the settings you provided when you recorded in the response file.

3. Verify that the following message appears:

   Installation of <ca-elmagent> was successful.
   

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.

1. Create a directory for loading the agent installation file, response file, and connectors file. This directory is the <install directory.>
2. Copy the tar file to target host, and extract the contents into the <install directory>.
3. Copy the response file to the <install directory>.
4. Copy the Connectors.xml file to the <install directory>.
5. (Optional) Edit the response file.

   This step is not needed if you elected to use common elements where possible.

6. Create the planned group and low privileged user.
7. Invoke the silent installation.
8. 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 a Solaris system, 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

1. Log on to the host where you plan to invoke the silent installation.
2. Navigate to the <install directory> where the ca-elmagent.rsp resides.
3. Use an editor of your choice to modify any of the values shown on the following table, then save the ca-elmagent.rsp file.

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:

1. Apply subscription updates to new agents and connectors.
2. 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.

3. Examine query results and reports to determine whether the data is being collected and refined as expected.
4. Tailor the connector configurations to meet local requirements.
5. (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 and correct a bind failure

1. Log on to the Solaris host as root.
2. Change directories to the agent root directory, /opt/CA/ELMAgent.
3. Type the following command:

   ps - eaf|grep caelm
   

4. Examine the displayed results.
   • A successful bind results in a display similar to the following example. Here, the caelmwatchdog process ID 27773 successfully binds with the caelmagent process ID 27771. A successful bind starts the agent service.

     root 27773 27771   0 18:11:12 ?           0:00 ./caelmwatchdog
     root 27771     1   0 18:11:07 ?           0:02 ./caelmagent -b
     root 27793 26155   0 18:14:22 pts/1       0:00 grep caelm
     root 27772 27771   0 18:11:07 ?           0:00 ./caelmdispatcher
     

   • An unsuccessful bind results in a display similar to the following example. Here, the caelmwatchdog and caelmagent process IDs are not displayed and the agent service is not started.

     root 28386 26155   0 18:56:18 pts/1       0:00 grep caelm
     root 28300     1   0 18:51:39 ?           0:01 ./caelmdispatcher
     

     Note: If the caelmwatchdog binding to the caelmagent did not take place, kill the caelmdispatcher and start the agent service manually.

5. If you determine that the agent start was unsuccessful, do the following:
   1. To kill the caelmdispatcher, enter kill -9 <caelmdispatcher process ID>, for example:

      kill -9 28300
      

   2. Change directories to /opt/CA/ELMAgent/bin.
   3. Start the CA User Activity Reporting Module agent service.

      ./S99elmagent start
      

      The message "CA ELM Agent Started Successfully" appears.

Note: View the agent status details again and verify that the agent is Running.

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

1. Make the replacement user part of the primary group.
2. Set a password for the replacement user and confirm the new password.
3. (Optional) Remove the <original_username> from the group.
4. (Optional) Delete the <original_username> from the host.
5. 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 Interactively Installed Agent

You can uninstall an agent on a Solaris computer using this procedure.

To uninstall an agent that was interactively installed on a Solaris system

1. Access the target Solaris system locally or remotely.
2. Log in as a root user.
3. Access a Unix shell.
4. Change directories to /opt/CA/ELMAgent.
5. Type the following commands to initiate the uninstall process.

   pkgrm ca-elmagent
   

6. When the following prompts appear, type y for yes:

   Do you want to remove this package [y, n, ?, q]
   Do you want to continue with the removal of this package [y, n, ?, q]
   

   The uninstall process runs. Detailed information is saved in /tmp/uninstall_ca‑elmagent.<timestamp>.log.

7. Verify that the following confirmation message appears:

   Removal of <ca-elmagent> was successful.
   

   The agent is uninstalled.

Important! Log on to the CA User Activity Reporting Module server that managed the agent you uninstalled. If the agent is still displayed in an agent group under the Log Collection, Agent Explorer folder, delete the agent. Click Select in the Agent Status Details, click Delete, and respond Yes to the confirmation prompt.

Uninstall a Silently Installed Agent

The command to uninstall a silently installed agent is different from the command to uninstall a manually installed agent. The difference is due to the existence of the admin file that is used only for silent installations.

To uninstall an agent that was silently installed on a Solaris host

1. Log on as root to the Solaris host where the agent is installed.
2. Access a command prompt.
3. Change directories to the <install directory>.
4. Type the following command:

   pkgrm -a admin -n ca-elmagent
   

5. Verify that the final message indicates removal of the agent. For example:

   Removal of <ca-elmagent> was successful.