2 Installing the Connector

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

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

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

Figure 2-1 Connector Communication Between Components

The following sections in this chapter discuss these topics:

• Installation Platforms

• Installing and Running the HP OpenView Operations Agent

• Installing the HP OpenView Operations Web Service

• Installing the HP OpenView Operations Connector in Oracle Enterprise Manager

• Registering Templates

Installation Platforms

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

• Microsoft Windows

• Sun Solaris

• HP-UX

• Linux

You can install the HP OpenView Operations Agent on the following platform:

• HP-UX on Itanium architecture with OS version 8 and above

• Solaris on SPARC architecture with OS version 10 and above

Installing and Running the HP OpenView Operations Agent

The following sections provide procedures that successfully enable you to install the Agent, then subsequently run it.

Installing the Agent

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

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

1. Download the hp_ovou_connector_bundler.jar file from the Oracle Technology Network to the installation directory.

2. Make sure the JAVA_HOME environment variable is set to the directory where Java 1.6 is installed.

3. Extract the .jar file by running the following command:

   jar -xvf hp_ovou_connector_bundle.jar
   

4. Put the appropriate installation file into the directory where you intend to install the Oracle OVO Agent. Note that you need to do this on the HP OpenView Operations system host.

   For the HP-UX platform, the Agent zip file is named agent-hpovou-connector.tar.gz, and for the Solaris platform, the Agent zip file is named agent-solaris-connector.tar.gz.

5. Open a terminal and change the working directory to the installation directory.

6. Enter the appropriate command listed below to unzip the Agent zip:

   • For HP-UX:

     gunzip agent-hpovou-connector.tar.gz
     

   • For Solaris:

     gunzip agent-solaris-hpovou-connector.tar.gz
     

7. Enter the appropriate command listed below to extract the installation files from the resulting .tar file:

   • For HP-UX:

     tar xvf agent-hpovou-connector.tar
     

   • For Solaris:

     tar xvf agent-solaris-hpovou-connector.tar
     

   This creates the ovo-agent directory that contains the installation files.

8. Change the working directory to the ovo-agent/scripts directory.

9. Enter the following command to run the setup script to configure the Oracle OVO Agent:

   ./setup.sh

   The following prompts appear in this sequence:

   1. Enter the OpenView message groups to register — Enter a space-separated list of the OVO message group(s) to be picked up by Oracle Enterprise Manager when polling for new or updated alerts.

      Note:

      All message groups registered with the Agent must have an automatic action defined. This enables the Agent to detect new messages created in OVO. For any message groups that do not already have a defined automatic action, the recommended approach is to set up an automatic action to invoke a script that does nothing.

   2. Enter the OVO UserID to be used — Enter the user name for the OVO account to be used for accessing the OVO API. This is the OVO user account specified in the prerequisites section.

   3. Enter the OVO Password — Enter the password for the OVO account to be used in accessing the OVO API. This is the OVO user account specified in the prerequisites section.

      Note that for security reasons, the password information will not be echoed to the terminal.

   4. Enter the system UserID that has access to start and stop the service — Enter the system user name that will be able to start and stop the Oracle OVO Agent.

      Note:

      For the Solaris platform, the account that starts the Agent must include the /opt/OV/lib path in the LD_LIBRARY_PATH environment variable. This instructs the OS where to find the OVO libraries that the Agent references.

   5. Enter the host name of the HP-OVO Adapter — Enter the host name where the OVO web service will be installed. This can be on the same system or on a different system that has connectivity to the OVO server and the Oracle Enterprise Manager server.

10. Open another terminal and log in as root.

11. Change the working directory to the ovo-agent/scripts directory in the Oracle OVO Agent installation directory.

12. Enter the following command to enable the Oracle OVO Agent to run with root permissions:

    ./root-setup.sh

13. Close the terminal where you are logged in as root.

14. Delete the agent-hpovou-connector.tar 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 OVO Agent, enter the following command:

./startallbb

Stopping the Agent

To stop the Oracle OVO Agent, enter the following command:

./stopallbb

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

Installing the HP OpenView Operations Web Service

The OVO web service acts as a front-end for all data flowing into and out of OVO. 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 OVO.

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

Installing and Running the HP OpenView Operations Web Service on Unix

The following sections explain how to install and then subsequently run the Web Service.

Installing the Web Service on Unix

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

1. Create a directory where you want to install the web service.

2. Open a terminal and change the working directory to the installation directory.

3. Download the hp_ovou_connector_bundler.jar file from the Oracle Technology Network to the installation directory.

4. Make sure the JAVA_HOME environment variable is set to the directory where Java 1.6 is installed.

5. Extract the .jar file by running the following command:

   jar -xvf hp_ovou_connector_bundle.jar
   

6. Enter the following command to unzip the .tar file:

   gunzip ws-hpovou-connector-unix.tar.gz

7. Enter the following command to extract the installation files:

   tar xvf ws-hpovou-connector-unix.tar

   This creates the iwave-af-1.1.1 directory that contains the installation files.

8. Enter the following command to change the working directory as follows:

   cd iwave-af-1.1.1/endpoints/hpovou

9. Enter the following command to run the installation script:

   ./install.sh

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

11. When the script prompts for the host name of the HP-OVO server, enter the host name where the Oracle OVO Agent is installed.

    Note that you cannot specify the host name of a local host. The host name must be the actual host name or IP address of the system.

12. Enter the following command to change the working directory to the iwave-af-1.1.1 directory:

    cd ../..

13. Enter the following command to change the user name and password for accessing the OVO web service:

    bin/propertiesEditor.sh -e framework.username="<username>" -e framework.password="<password>" conf/spring.properties

    ... where <username> is the user name to specify for the web service, and <password> is the password.

    This command encrypts the user name and password information in the configuration file.

14. Delete the ws-hpovou-connector-unix.tar file from the installation directory.

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

If the HP OpenView Operations Web Service was configured to use the HTTPS protocol, the certificate must be imported into Enterprise Manager. See Adding Signed Certificates to Enterprise Manager for instructions.

Running the Web Service on Unix

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

iwave-af-1.1.1/bin

... in the installation directory.

• Start — ./service.sh start

• Shut Down — ./service.sh stop

• Restart — ./service.sh restart

• Check Status — ./service.sh status

Installing and Running the HP OpenView Operations Web Service on Windows

The following sections explain how to install and then subsequently run the Web Service.

Prerequisites

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

• Java Runtime Environment (JRE) version 6 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:

1. Create a directory where you want to install the web service.

2. Open a terminal and change the working directory to the installation directory.

3. Download the hp_ovou_connector_bundler.jar file from the Oracle Technology Network to the installation directory.

4. Make sure the JAVA_HOME environment variable is set to the directory where Java 1.6 is installed.

5. Extract the .jar file by running the following command:

   jar -xvf hp_ovou_connector_bundle.jar
   

6. Open a command prompt window and change the working directory to the installation directory.

7. Unzip the ws-hpovou-connector-windows.zip file using a zip utility.

8. Change the working directory to the iwave-af-1.1.1\conf directory.

9. Enter the following command to install the OVO connector configuration file:

   copy ..\endpoints\hpovou\hpovou-spring.xml .

10. Enter the following command to configure the web service to connect to the Oracle OVO Agent ...

    ..\bin\propertiesEditor.bat -p hpovou.xmlagent=http://<OVOserver>:9007 spring.properties 
    

    ... where <OVOserver> is the host name or IP address of the OVO server.

11. Configure the URL used by the web service based on whether you want to encrypt data. There are two possible protocols available: the default protocol is HTTP, which does not provide encryption of data. The other protocol available is HTTPS, which provides encryption of data using SSL certificates.

    Oracle recommends that you use HTTPS as the protocol for the communication between Enterprise Manager and the HP OVOU Web Service server. Use HTTP only if a secure connection is not required and the data can be transferred in clear text between the two systems.

    • To configure the web service without encryption, enter the following command to configure the web service URL ...

      ..\bin\propertiesEditor.bat -p services.url=http://<hostname>:8080/ services spring.properties
      

      ... where <hostname> is the host name or IP address of the system where the web service will be installed.

      The propertiesEditor.bat script is specifically for the Windows platform. The equivalent script for UNIX platforms is propertiesEditor.sh.

    • To configure the web service to use encryption, enter the following command to configure the web service URL ...

      ..\bin\propertiesEditor.bat -p services.url=https://<hostname>:8443/ services spring.properties
      

      ... where <hostname> is the host name or IP address of the system where the web service will be installed.

12. Install an SSL certificate. You need to do this whether or not the data will be encrypted. If you configured the web service to use the HTTP protocol in the preceding step, install a self-signed SSL certificate. If you configured the web service to use the HTTPS protocol, you can install a self-signed SSL certificate or one that the Certificate Authority assigns.

    • To generate and install a self-signed SSL certificate:

      • Enter the following command, and replace <hostname> with the system host name or IP address specified in the preceding step:

        "%JAVA_HOME%\bin\keytool" -genkey -alias iwave -keyalg RSA -keysize 1024 -dname "CN=<hostname>, OU=Development, O=iWave Software, L=Frisco, ST=TX, C=US" -keypass iwavepw -storepass iwavepw -keystore keystore.jks
        

    • To install a certificate that the Certificate Authority issues:

      • Request a certificate from a Certificate Authority, such as VeriSign.

      • In the certificate request, make sure to specify the host name or IP address of the system specified in the preceding step. The host name in the certificate must match the host name configured for the web service. If they do not match, the web service cannot function.

      • After you obtain the certificate from the Certificate Authority, enter the following command to install the certificate, where <certificateFile> is the full path name of the file provided by the Certificate Authority:

        "%JAVA_HOME%\bin\keytool" -export -alias iwave -file <certificateFile> -keypass iwavepw 
        -storepass iwavepw -keystore keystore.jks
        

13. Enter the following command to change the user name and password for accessing the OVO web service ...

    ..\bin\propertiesEditor.bat -e framework.username="<username>" -e framework.password="<password>" spring.properties

    ... where <username> is the user name to specify for the web service, and <password> is the password.

    This command encrypts the user name and password information in the configuration file.

14. Delete the ws-hpovou-connector-windows.zip file.

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

If the HP OpenView Operations Web Service was configured to use the HTTPS protocol, the certificate must be imported into Enterprise Manager. See Adding Signed Certificates to Enterprise Manager for instructions.

Running the Web Service on Windows

To start the OVO web service framework:

1. Change the working directory to the iwave-af-1.1.1\bin directory in the installation directory.

2. Run the following command:

   startAdapters.bat

To shut down the OVO web service framework, press Ctrl-C in the window where you started the adapter.

Adding Signed Certificates to Enterprise Manager

The Service Manager SSL certificate must be imported into Enterprise Manager. For versions 10.2.0.4 and 10.2.0.5, perform the steps in Adding Signed Certificates to Wallet Manager. For version 11.1.0.1, perform the steps in Adding Signed Certificates to cacerts.

Adding Signed Certificates to Wallet Manager

Note:

Oracle Wallet Manager is available at $ORACLE_HOME/bin on OMS for versions 10.2.0.4 and 10.2.0.5. See the Oracle Application Server Administrator's Guide for details.

Perform the following steps in Oracle Enterprise Manager to add signed certificates:

1. Do the following to obtain a copy of the certificate that the OVO web service is using:

   1. Open a command prompt window and change the working directory to ...

      <OVOWS_INSTALL>/iwave-af-1.1.1/conf

      ... where <OVOWS_INSTALL> is the directory where the OVO web service is installed.

   2. Issue the following command to extract the certificate:

      — Unix platforms:

      $JAVA_HOME/bin/keytool -exportcert -alias iwave -file ovows.cer -keystore keystore.jks -storepass iwavepw

      — Windows platforms:

      %JAVA_HOME%\bin\keytool -exportcert -alias iwave -file ovows.cer -keystore keystore.jks -storepass iwavepw

   3. Transfer the certificate file ovows.cer to the system where Enterprise Manager is installed.

2. Open a new terminal and set the ORACLE_HOME environment variable to the directory where OMS is installed.

3. As Super Administrator, create a wallet using the following orapki utility command at the OMS host:

   $OMS_HOME/../agent11g/orapki wallet create -wallet client -auto_login

4. Add the trusted certificate to the wallet by entering the following command:

   $OMS_HOME/../agent11g/orapki wallet add -wallet client -trusted_cert -cert <certFile>

5. To view the content of the wallet, enter the following command:

   $OMS_HOME/../agent11g/orapki wallet display -wallet client

   Verify that the certificate that was added is listed in the Trusted Certificates.

6. Start Oracle Wallet Manager and open the client wallet.

7. Click on Trusted Certificates and select Operations on the main menu.

8. Select Export All Trusted Certificates.

9. Save the file as certdb.txt.

10. Place the file certdb.txt in the connector home root directory ($OMS_HOME/sysman/connector).

    If the certdb.txt file already exists in the root directory, open the file and add the contents of your certdb.txt file to the existing content.

Java SSL can now use this file for communication between Oracle Enterprise Manager and the OVO web service in HTTPS mode.

See Also:

For additional information on creating a wallet, see "Creating and Viewing Oracle Wallets with orapki" in the Oracle Database Advanced Security Administrator's Guide, 10g Release 2 (10.2).

Adding Signed Certificates to cacerts

Do the following in Enterprise Manager to add signed certificates to the Java cacerts keystore:

1. Copy the certificate to the Enterprise Manager server system.

2. Determine the location of the JRE in the Oracle Home directory.

3. Open a command window and navigate to the JRE bin directory.

4. Enter the following command to add the certificate to the cacerts keystore:

   keytool -importcert -keystore ..\lib\security\cacerts -storepass changeit -trustcacerts -file <certfile> -alias ovouws_cert
   

5. Restart OMS by opening a command window, changing the working directory to <ORACLE_HOME>/oms10g/bin, and issuing the following commands:

   emctl stop oms
   emctl start oms
   

Installing the HP OpenView Operations Connector in Oracle Enterprise Manager

The following steps explain how to add the new HP OpenView Operations Unix Connector to Oracle Enterprise Manager Grid Control.

Note:

Table 2–1 at the end of this section provides descriptions for the parameters shown for the emctl command in this procedure.

Note:

The commands in this section and the following section reference the OMS_HOME environment variable. OMS_HOME must be set to the OMS sub-directory in the Enterprise Manager installation directory. For versions 10.2.0.4 and 10.2.0.5, this is the oms10g directory. For version 11.1.0.1, this is the oms11g directory. Example settings of the OMS_HOME variable are /gc/OracleHomes/oms10g on a Unix platform running version 10.2.0.5, and C:\Oracle\Middleware2\oms11g on a Windows platform running version 11.1.0.1.

1. Enter the following command to extract the connector .jar file for versions 10.2.0.5 and 11.1.0.1:

   $OMS_HOME/bin/emctl extract_jar connector -jar <jarfile> -cname <connectorTypeName>
   

   For version 10.2.0.4, enter the following command:

   $OMS_HOME/bin/emctl extract_jar connector <jarfile> <connectorTypeName>  <OracleHome>
   

   Note:

   You should perform this extraction on all OMS instances, because all OMS instances need to access the files locally.

   10.2.0.5 and 11.1.0.1 Command Example

   $OMS_HOME/bin/emctl extract_jar connector -jar "$OMS_HOME/ bin/sysman/connector/hpovou.jar" -cname "HP OVOU Connector"
   

   When run, this creates the following new connector sub-directory:

   $OMS_HOME/sysman/connector/HP_OVOU_Connector
   

2. Register the connector by entering the following command based on your Enterprise Manager version, noting the required double-quotes. You only need to perform the registration once.

   11.1.0.1

   $OMS_HOME/bin/emctl register_connector connector -dd "<deployment file>" -repos_pwd <repos_pwd>
   

   10.2.0.5

   $OMS_HOME/bin/emctl register_connector connector -dd "<deployment file>" -cs //<server>:<port>/<databaseSID> -repos_user <repos_user> -repos_pwd  <repos_pwd>
   

   10.2.0.4

   $OMS_HOME/bin/emctl register_connector connector “<deployment file>”  <server> <port> <databaseSid> <reposuser> <repospwd> “<omshome>”
   

   11.1.0.1 Command Example

   $OMS_HOME/bin/emctl register_connector connector -dd “$OMS_HOME/ sysman/connector/HP_OVOU_Connector/HPOVOUConnector.xml”
   -repos_pwd password
   

The new HP OVO connector should now appear in the Management Connectors page after the emctl register_connector command has loaded the connector, as shown in Figure 2–2.

Figure 2-2 Installed HP OVO Connector

Table 2–1 provides descriptions for the parameters shown in the procedure above.

Table 2-1 emctl Parameters

Parameter	Description
cname	Connector name. Specify "HP OVOU Connector". The double quotes ("") are mandatory.
cs	Connect string. Specify as "//$emHost:$dbPort/$dbSID”, where, $emHost is the server, $dbPort is the port, and $dbSID is the database session identifier.
ctname	Connector type name. Specify "HP OVOU Connector". The double quotes ("") are mandatory.
database sid/ Service Name for RAC DB	Repository database instance ID or service name if you are using a RAC database as the repository.
deployment file	Fully-qualified name of the connector deployment file. This HPOVOUConnector.xml file resides in the following HP OVOU connector directory: $OMS_HOME/sysman/connector/HP_OVOU_Connector/
description	Short description for the ticket template. This description is also displayed in Enterprise Manager.
iname	Internal name — Depending on the template, the values can be acknowledgeAlerts, createEvent, getNewAlerts, getUpdatedAlerts, or updateEvent.
oraclehome	Top directory of the OMS installation.
omshome	"<oraclehome>\oms10g" with double quotes recommended.
port	Listener port of the repository.
repos_pwd	Password for SYSMAN.
repos_user	Specify SYSMAN.
server	Host name of the Enterprise Manager repository.
tname	Template name — Depending on the template, the values can be Acknowledge Alerts, Create Event, Get New Alerts, Get Updated Alerts, or Update Event.
ttype	Template type — Specify 1 for inbound transformation and 2 for outbound transformation.

Registering Templates

The following steps explain how to register templates for various Enterprise Manager versions.

1. For each template, run the following emctl register_template connector command based on the Enterprise Manager version. The command must be run as a user with execute privilege on emctl and the ability to read the template.

   11.1.0.1

   $OMS_HOME/bin/emctl register_template connector -t <template.xml> -repos_pwd <password> -ctname <connector_type_name> -cname <connector_name> -tname <template_name> -iname <internal_name> -ttype <template_type> -d <description>
   

   10.2.0.5

   $OMS_HOME/bin/emctl register_template connector -t <template.xml> -cs //<server>:<port> /<database sid> -repos_user <username> -repos_pwd <password> -ctname <connector_type_name> -cname <connector_name> -tname <template_name> -iname <internal_name> -ttype <template_type> -d <description>
   

   10.2.0.4

   $OMS_HOME/bin/emctl register_template connector -t <template.xml> -cs //<server>:<port>/<databaseSID> -repos_user <username> -repos_pwd <password> -ctname <connector_type_name> -cname <connector_name> -iname <internal_name> -tname <template_name> -ttype <template_type> -d <description>
   

2. Replace <template.xml>, <internal_name>, <template_name> and <template_type> with the values listed in Table 2–2, which lists the properties of each template for the HP OpenView Operations Connector.

Table 2-2 Possible Replacement Values For register_template Parameters

template.xsl and template_xml	template_name	internal_name	template_type
acknowledge_request.xsl	Acknowledge Alerts	acknowledgeAlerts	2
createEvent_request.xsl	Create Event	createEvent	2
createEvent_response.xsl	Create Event	createEvent	1
generic_request_acknowledgealerts.xml	Acknowledge Alert	acknowledgeAlerts	3
getNewAlert_request.xsl	Get New Alerts	getNewAlerts	2
getNewAlerts_response.xsl	Get New Alerts	getNewAlerts	1
getUpdatedAlert_request.xsl	Get Updated Alerts	getUpdatedAlerts	2
getUpdatedAlerts_response.xsl	Get Updated Alerts	getUpdatedAlerts	1
updateEvent_request.xsl	Update Event	updateEvent	2
updateEvent_response.xsl	Update Event	updateEvent	1
template_type Key: template_type1 — Inbound transformation template_type 2 — Outbound transformation template_type 3 — XML outbound transformation

The following example is based on the template values shown in Table 2–2.

Example 2-1 Request XSL File for acknowledgeAlerts Method

$OMS_HOME/bin/emctl register_template connector -t $OMS_HOME/sysman/connector/ HP_OVOU_Connector/acknowledge_request.xsl -repos_pwd mypassword -ctname "HP OVOU Connector" -cname "HP OVOU Connector" -tname "Acknowledge Alerts" -iname "acknowledgeAlerts" -ttype 2 -d "This is the request xsl file for acknowledgeAlerts method"