2 Installing the Connector

The Oracle Enterprise Manager Connector Framework requires a web service interface for forwarding event information with HP Operations Manager (OMU). Since OMU does not provide a web services interface, you must install a third-party OMU web service front-end, which is included in the Oracle Enterprise Manager HP OMU installation package.

You can install the web service on a UNIX or Windows system that has connectivity with the OMU server. In addition to the OMU web service front-end, you must also install a back-end Oracle OMU Agent on the same physical system as the OMU server. The Oracle OMU Agent is preconfigured and is also included in the Oracle Enterprise Manager HP OMU installation package.

Figure 2–1 shows the communication between the various components of the OMU Connector.

Figure 2-1 Connector Communication Between Components

Shows flow chart of communication from EM to OVOU.

The following sections in this chapter discuss these topics:

Installation Platforms
Prerequisites
Installing the Connector in Enterprise Manager
Installing and Running the Oracle Agent for HP Operations Manager
Installing the Oracle Web Service for HP Operations Manager

Installation Platforms

You can install the Oracle web service for HP Operations Manager on the following platforms that support Java JRE 1.6:

Microsoft Windows
Sun Solaris
HP-UX
Linux

You can install the Oracle Agent for HP Operations Manager on the following platforms:

HP-UX on Itanium architecture with OS version 8 and above
Solaris on SPARC architecture with OS version 10 and above
Linux with Red Hat Enterprise versions 5.2 and above

Prerequisites

Ensure that the following prerequisites have been met before proceeding to the next section.

My Oracle Support Preferred Credentials must be set.

To set the credentials:
1. From Setup menu of the Enterprise Manager menu, select My Oracle Support, then select Set Credentials.
2. Enter the user name and password information, then click Apply.
3. From the Enterprise Manager console Setup menu, select Extensibilty, then Self Update.
4. From the Self Update page, click Check Updates to schedule a job to collect the metadata for the connector.
See Also:
"Using Self Update to Download Oracle Products" section of the Enterprise Manager Cloud Administration Guide for more details.
The gunzip utility must be available on the system hosting HP Operations Manager.
An HP Operations Manager user account must be set up that the Oracle OMU Agent can use.

To forward events to HP OMU, you need to make some configuration changes in HP OMU as described in the following high-level steps.

See Also:
Appendix B, "Integrating OMU with Enterprise Manager" for detailed instructions on setting up HP OMU.
1. Create a message group named OracleEnterpriseManager at the HP Operations Manager server.
  
  The HP Operations Manager account mentioned above must have access to this message group, and must be able to create and update messages in this message group.
2. Create a node named OracleEnterpriseManager at the HP Operations Manager server.
  
  This node must be a Message Allowed type and must not have an associated IP address. Messages inserted by Enterprise Manager are assigned to this node.
3. Create a template/policy that generates a message whenever an event is received for the OracleEnterpriseManager message group.

Installing the Connector in Enterprise Manager

The OMU connector is not included out-of-box, so you need to download it from the Oracle Enterprise Manager store. All connectors in the Enterprise Manager store are available on the Self Update page for downloading.

Note:

There are no special privileges needed to download a connector. However, you need the Super Administrator privilege to apply a connector.

To download and install (apply) the connector:

From the Enterprise Manager console Setup menu, select Extensibility, then select Self Update.
Click on the Management Connector link in the Type column.

The OMU connectors appear in the list with a status of Available.
Click on the appropriate OMU connector to select it, and then click Download.

The Schedule Download window appears, where you can determine when the download should be performed.
Click Select to download immediately.

If you want to schedule the download for a later time, specify the date and time when the download should occur, and click Select. You will need to return and finish the remainder of this procedure after the scheduled download date and time.
If necessary, refresh the screen until the status of the connector changes to Downloaded.
Click on the OMU connector to select it, and then click Apply.

After you respond to the prompt to confirm the operation, a page appears that indicates the request has been submitted.
Refresh the screen until the status of the connector changes from Apply Scheduled to Applied.

Installing and Running the Oracle Agent for HP Operations Manager

The following sections provide procedures to install the Agent, then subsequently run it.

Installing the Agent

The back-end Oracle OMU Agent exchanges data with the OMU API and must be run on the same physical system as the OMU server. The Oracle OMU Agent is preconfigured to interface with the OMU Web Service and requires minimal configuration.

To install the Oracle OMU Agent, perform the following steps:

Obtain a copy of the agent installation file from the Management Server host system as specified in Exporting the Agent Installation File.
Transfer the Agent installation file to the Operations Manager system host into the directory where you intend to install the Oracle OMU Agent.

The Agent zip files are named as follows:
- HP-UX platform — hpomuAgentHPUX.tar.gz
- Solaris platform — hpomuAgentSolaris.tar.gz
- Linux platform — hpomuAgentLinux.tar.gz
Open a terminal and change the working directory to the installation directory.
Enter the appropriate command listed below to extract the Agent installation files:
- For HP-UX:
```
gunzip -c hpomuAgentHPUX.tar.gz | tar xvf -
```
- For Solaris:
```
gunzip -c hpomuAgentSolaris.tar.gz | tar xvf -
```
- For Linux:
```
tar xzvf hpomuAgentLinux.tar.gz
```
  This creates the ovo-agent directory that contains the installation files.
Change the working directory to the ovo-agent/scripts directory.
Enter the following command to run the setup script to configure the Oracle OMU Agent:
```
./configure.sh
```
The following prompts appear in this sequence:
1. Enter the UserID to use when accessing the OMU API: — Enter the user name of the OMU account for the Agent to use when accessing the OMU API. This is the OMU user account specified in the prerequisites section.
2. Enter the Password to use when accessing the OMU API: — Enter the password of the OMU account the Agent uses to access the OMU API. This is the OMU user account specified in the prerequisites section.
3. Enter the system usernames that have access to start and stop the OMU Agent. — You are prompted for a user name until an empty response is provided.
Open another terminal and log in as root.
Change the working directory to the ovo-agent/scripts directory in the Oracle OMU Agent installation directory.
Enter the following command to enable the Oracle OMU Agent to run with root permissions:
```
./root-setup.sh
```
Close the terminal where you are logged in as root.
Delete the Agent .tar.gz file from the installation directory.

Running and Stopping the Agent

Running the Agent

Before starting the Agent on the Solaris platform, verify that the LD_LIBRARY_PATH environment variable contains the /opt/OV/lib path.

To start the Oracle OMU Agent, enter the following command from the ovo-agent/scripts directory in the Oracle OMU Agent installation directory:

./start.sh

Stopping the Agent

To stop the Oracle OMU Agent, enter the following command from the ovo-agent/scripts directory in the Oracle OMU Agent installation directory:

./stop.sh

You must specify the user name and password for an account that is authorized to stop the Oracle OMU Agent.

Exporting the Agent Installation File

The agent installation file is included in the Self Update archive that was installed in Installing the Connector in Enterprise Manager.

To extract the installation file:

Determine the command required to export the adapter installation file. To do this, perform the following steps:
1. From the Setup menu, select Extensibility, then Self Update.
2. Click on the Management Connector link in the Type column.
3. Click on the OMU connector to select it, then select Export from the Actions list.
  
  A pop-up window, like the example shown in Figure 2-2, appears with the command required to export the file.
  
  Figure 2-2 Export Command Example
Open a command window on the Operations Manager host system and navigate to a temporary directory where you can copy the file.
Log into EM CLI using the following command. You will be asked to provide the password information for the sysman account.
```
emcli login -username=sysman
```
EM CLI must be executed from the OMS server system. See the Oracle Enterprise Manager Command Line Interface for information about setting up EM CLI.
Run the EM CLI export_update command from your system, changing <dirname> to the full path of the temporary directory.

This action creates a zip file. The file name is comprised of the id value you specify in the export_update command with a .zip extension. In the example command in Figure 2-2, the zip file name would be E9F684312AE7A18E98340715D079E58D.zip .
Extract the Agent installation file from the zip file using one of the following commands, depending on the platform where the agent will be deployed:
- For HP-UX:
```
unzip *.zip archives/hpomuAgentHPUX.tar.gz
```
- For Solaris:
```
unzip *.zip archives/hpomuAgentSolaris.tar.gz
```
- For Linux:
```
unzip *.zip archives/hpomuAgentLinux.tar.gz
```

Troubleshooting the Agent

The Oracle OMU Agent links in OMU libraries at run time. On some systems, you might receive an error similar to the following example when attempting to run the Agent using an account other than root.

ld.so.1: ovooper: fatal: libovsnmp.so: open failed: No such file or directory

This error message indicates that the OS runtime does not know where to pick up the OMU library files. On all supported platforms, you can use the ldd command to determine which libraries cannot be loaded.

The following sections explain about what is required to change the run-time configuration on the supported platforms.

Linux

For Linux systems, do the following to configure the run-time loader to pick up the OMU libraries:

Add the library paths to the /etc/ld.so.conf file.
Run the ldconfig command.

HP-UX

For HP-UX systems, you must add the library paths to the /etc/dld.sl.conf file.

Solaris

For Solaris systems, you must run the crle command with the -s option to add the OMU library paths to the run-time configuration.

Examples for Solaris

ldd Command Examples

Run the ldd command with no options to analyze the run-time libraries loaded by the ovooper binary. The output shows that some of the files cannot be found.

$ ldd ovooper
        libovsnmp.so =>  (file not found)
        libov.so =>      (file not found)
        libopcsv_r.so => (file not found)
        libopcdb.so =>   (file not found)
        libnsp.so =>     (file not found)
        libnsl.so.1 =>   /lib/libnsl.so.1
        libdce.so =>     /usr/lib/libdce.so
        libsocket.so.1 => /lib/libsocket.so.1
        libthread.so.1 => /lib/libthread.so.1
        libm.so.2 =>     /lib/libm.so.2
        libw.so.1 =>     /lib/libw.so.1
        libdl.so.1 =>    /lib/libdl.so.1
        libz.so =>       /usr/lib/libz.so
        libiconv.so.2 => (file not found)
        libc.so.1 =>     /lib/libc.so.1
        libmp.so.2 =>    /lib/libmp.so.2
        libmd5.so.1 =>   /lib/libmd5.so.1
        libscf.so.1 =>   /lib/libscf.so.1
        libdcecrypt.so => /usr/lib/libdcecrypt.so
        libm.so.1 =>     /lib/libm.so.1
        libdoor.so.1 =>  /lib/libdoor.so.1
        libuutil.so.1 => /lib/libuutil.so.1
        /platform/SUNW,Sun-Fire-280R/lib/libc_psr.so.1
        /platform/SUNW,Sun-Fire-280R/lib/libmd5_psr.so.1

Run the ldd command with the -s option to provide additional information, as shown below. The command output shows that the /opt/OV/lib and /opt/OV/lib paths are being ignored because of an insecure directory name. This means that the libraries are not defined in the run-time linking environment.

$ ldd -s ovooper
 
   find object=libovsnmp.so; required by ovooper
    search path=/opt/OV/lib:/usr/local/lib  (LD_LIBRARY_PATH)
    ignore path=/opt/OV/lib  (insecure directory name)
    ignore path=/usr/local/lib  (insecure directory name)
    search path=/lib:/usr/lib  (default)
    trying path=/lib/libovsnmp.so
    trying path=/usr/lib/libovsnmp.so
        libovsnmp.so =>  (file not found)

crle Command Examples

Run the crle command with no options to show the library paths currently defined for the run-time linking environment:

# crle
 
Configuration file [version 4]: /var/ld/ld.config
  Default Library Path (ELF):   /lib:/usr/lib  (system default)
  Trusted Directories (ELF):    /usr/lib/secure:/lib/secure

Command line:
  crle -c /var/ld/ld.config -s /usr/lib/secure:/lib/secure

Run the crle command with the -s option to add the OMU library paths to the run-time linking environment:
```
# crle -s /lib/secure:/usr/lib/secure:/opt/OV/lib:/usr/local/lib
```

Run the crle command again with no options to verify that the library paths are now correct for the run-time linking environment:

Configuration file [version 4]: /var/ld/ld.config
  Default Library Path (ELF):   /lib:/usr/lib  (system default)
  Trusted Directories (ELF):    /lib/secure:/usr/lib/secure:/opt/OV/lib:/usr/local/lib
 
Command line:
  crle -c /var/ld/ld.config      -s /lib/secure:/usr/lib/secure:/opt/OV/lib:/usr/local/lib

Installing the Oracle Web Service for HP Operations Manager

The Oracle OMU web service acts as a front-end for all data flowing into and out of OMU. Oracle Enterprise Manager posts calls to the web service whenever it needs to create or update a message, or get new or updated messages from OMU.

You can install the OMU web service on any UNIX or Windows system that runs the Oracle JRE 1.6 and has connectivity to the OMU server and the Oracle Enterprise Manager server.

Installing and Running the HP Operations Manager Web Service on Unix

The following sections explain how to install and then subsequently run the Web Service on a Unix platform.

Prerequisites

The following prerequisites must be met before proceeding to the next section:

Oracle Java Runtime Environment (JRE) version 6 Update 11 or higher is installed.
JAVA_HOME environment variable is set to the JRE installation directory.

Installing the Web Service on Unix

To install the web service on a Unix platform, perform the following steps:

Create a directory where you want to install the web service.
Obtain a copy of the web service HPOMU_webservices_adapter.jar installation file from the Management Server host system as specified in Exporting the Web Service Installation File.
Copy the HPOMU_webservices_adapter.jar file to the web service installation directory.
Open a command prompt window and change the working directory to the Web service installation directory.
Enter the following command to extract the web services components from the web services .jar file:
```
jar xvf HPOMU_webservices_adapter.jar
```
Note:
If the system where the OMU web service is being installed does not have the JDK installed, you cannot extract the jar file contents. You need to copy the .jar file to a system that has the installed JDK and transfer the files after they have been extracted.

This creates the adapters directory that contains the installation files.
Enter the following command to change the working directory as follows:
```
cd adapters/endpoints/hpovou
```
Enter the following command to run the installation script:
```
./install.sh
```
When the script prompts whether you want to use HTTPS:
- If you specify Y, the web service is set up to use HTTPS port number 8443.
- If you specify N, the web service is set up to use HTTP port number 8080.
When the script prompts for the user name of the web service, enter a user name that must be provided to access the OMU Web Service.

The user name can be any value and is not associated with any specific OS or OMU account. Note this value and supply it when configuring the OMU connector in Enterprise Manager.
When the script prompts for the password of the web service, enter the password that must be provided to access the OMU Web Service.

The password can be any value and is not associated with any specific OS or OMU account. Note this value and supply it when configuring the OMU connector in Enterprise Manager.
When the script prompts for the system where the Agent was installed, enter the host name or IP address where the Oracle OMU Agent was installed.

You cannot specify the host name of localhost. The host name must be the actual host name or IP address of the system.
When the script prompts for the port number the Agent uses, enter the port number the Oracle OMU Agent uses. Unless you have manually configured the Agent to use a different port number, just accept the default port number of 9007.
After the script displays the message "OMU Web Service Complete," press Enter to complete the installation.
If the web service was configured to run using the HTTPS protocol, you must set up SSL as specified in Configuring Enterprise Manager to Use SSL.
Delete the HPOMU_webservices_adapter.jar file from the installation directory.

The web service framework is now installed and ready to start.

Running the Web Service on Unix

To run the HP Operations Manager Web Service framework commands listed with the following tasks, first change the working directory to ...

adapters/bin

... in the installation directory.

Start: ./service.sh start
Shut Down: ./service.sh stop
Restart: ./service.sh restart
Check Status: ./service.sh status

Testing the Web Service on Unix

Perform the following steps to verify that the OMU Web Service is functional.

Open a terminal and change the working directory to the adapters/bin directory in the installation directory.
Enter the following command to run the test script:
```
./testAdapter.sh
```
When the utility prompts for the web service password, enter the password you specified for the OMU web service in step 10 of Installing the Web Service on Unix.

If the test completes successfully, the last line the utility displays is "Test completed successfully."

Installing and Running the HP Operations Manager Web Service on Windows

The following sections explain how to install and then subsequently run the Web Service on a Windows platform.

Prerequisites

The following prerequisites must be met before proceeding to the next section.

Oracle Java Runtime Environment (JRE) version 6 Update 11 or higher is installed.
JAVA_HOME environment variable is set to the JRE installation directory.
Zip utility, such as WinZip, is installed for unzipping a zip file.

Installing the Web Service on Windows

To install the web service on a Windows platform, perform the following steps:

Create a directory where you want to install the web service.
Obtain a copy of the web service HPOMU_webservices_adapter.jar installation file from the Management Server host system as specified in Exporting the Web Service Installation File.
Copy the HPOMU_webservices_adapter.jar file to the web service installation directory.
Open a command prompt window and change the working directory to the Web service installation directory.
Enter the following command to extract the web services components from the web services .jar file:
```
jar xvf HPOMU_webservices_adapter.jar
```
Note:
If the system where the OMU web service is being installed does not have the JDK installed, you cannot extract the jar file contents. You need to copy the jar file to a system that has the installed JDK and transfer the files after they have been extracted.

This creates the adapters directory that contains the installation files.
Enter the following command to change the working directory as follows:
```
cd adapters\endpoints\hpovou
```
Enter the following command to run the installation script:
```
install.bat
```
When the script prompts whether you want to use HTTPS:
- If you specify Y, the web service is set up to use HTTPS port number 8443.
- If you specify N, the web service is set up to use HTTP port number 8080.
When the script prompts for the user name of the web service, enter a user name that must be provided to access the OMU Web Service.

The user name can be any value and is not associated with any specific OS or OMU account. Note this value and supply it when configuring the OMU connector in Enterprise Manager.
When the script prompts for the password of the web service, enter the password that must be provided to access the OMU Web Service.

The password can be any value and is not associated with any specific OS or OMU account. Note this value and supply it when configuring the OMU connector in Enterprise Manager.
When the script prompts for the system where the Agent was installed, enter the host name or IP address where the Oracle OMU Agent was installed.

You cannot specify the host name of localhost. The host name must be the actual host name or IP address of the system.
When the script prompts for the port number the Agent uses, enter the port number the Oracle OMU Agent uses. Unless you have manually configured the Agent to use a different port number, just accept the default port number of 9007.
After the script displays the message "OMU Web Service Complete," click Enter to complete the installation.
If the web service was configured to run using the HTTPS protocol, you must set up SSL as specified in Configuring Enterprise Manager to Use SSL.
Optional: If you want to run the web service as a Windows service, perform the following steps:
1. Change the working directory to the adapters\bin directory in the installation directory.
2. Enter the following command to install the web service as a Windows service:
```
service.bat install
```
Delete the HPOMU_webservices_adapter.jar file from the installation directory.

The web service framework is now installed and ready to start.

Running the Web Service on Windows

You can run the Web Service either as a standalone service or Windows service.

Running as a Standalone Service

To start the OMU web service framework when set up as a standalone application (not set up to run as a Windows service):

Change the working directory to the adapters\bin directory in the installation directory.
Run the following command:
```
startAdapters.bat
```

To shut down the OMU web service framework, close the window where you started the Web service.

Running as a Windows Service

To start the OMU web service framework when set up to run as a Windows service, enter the following command:

net start iWaveAdapters

To shut down the OMU web service framework, enter the following command:

net stop iWaveAdapters

Testing the Web Service on Windows

Perform the following steps to verify that the OMU Web Service is functional.

Open a terminal and change the working directory to the adapters\bin directory in the installation directory.
Enter the following command to run the test script:
```
.\testAdapter.bat
```
When the utility prompts for the web service password, enter the password you specified for the OMU web service in step 10 of Section 2.5.2.2, "Installing the Web Service on Windows".

If the test completes successfully, the last line the utility displays is "Test completed successfully."

Exporting the Web Service Installation File

The web service installation file is included in the zip file that was extracted in section Exporting the Agent Installation File.

To extract the installation file:

Open a command window on the Operations Manager host system and navigate to the temporary directory where the zip file was created.
Extract the web service installation file using the following command:
```
unzip *.zip archives/HPOMU_webservices_adapter.jar
```