2 Installing the Connector

2.3.1 Exporting the Installation Files

The agent and web service installation files are included in the Self Update archive that was installed in Installing the Connector in Enterprise Manager.

To export the installation files:

1. 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 IBM Tivoli Netcool/OMNIbus connector to select it, then select Export from the Actions list.

      A pop-up window similar to the example shown in Figure 2-2 appears with the command required to export the file.

      Figure 2-2 Export Command Example

      
      

2. Open a command window on the Enterprise Manager host system and navigate to a temporary directory where you can copy the file.

3. Log into EM CLI using the following command:

   emcli login -username=<Enterprise Manager Super Administrator log in>
   

   You will be asked to provide the password information.

   You must execute EM CLI from the OMS server system. See the Oracle Enterprise Manager Command Line Interface for information about setting up EM CLI.

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

   1208A7C0D8913455B18D12F65ABCA8A0.zip
   

5. Extract the installation files from the zip file using the following command:

   unzip *.zip archives/*
   

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

2.5.2 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. Copy the OMNIbus_webservices_adapter.jar file from the Management Server host system to the web service installation directory. The file is located in the archives directory that was extracted in Exporting the Installation Files.

3. Open a command prompt window and change the working directory to the web service installation directory.

4. Enter the following command to extract the web services components from the web services .jar file:

   jar xvf OMNIbus_webservices_adapter.jar
   

   Note:

   If the system where the web service for Netcool/OMNIbus is being installed does not have the JRE installed, you cannot extract the jar file contents. You need to copy the .jar file to a system that has the installed JRE and transfer the files after they have been extracted.

   This creates the adapters directory that contains the installation files.

5. Enter the following command to change the working directory:

   cd adapters/endpoints/omnibus
   

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

   sh ./install.sh
   

7. When the script prompts whether you want to use HTTPS:

   • If you specify Y, then the web service is set up to use HTTPS port number 8443.

   • If you specify N, then the web service is set up to use HTTP port number 8080.

8. When the script prompts for the user name of the web service, enter a user name that must be provided to access the web service for Netcool/OMNIbus.

   The user name can be any value and is not associated with any specific OS or Netcool/OMNIbus account. Make a note of this value and supply it when configuring the Netcool/OMNIbus connector in Enterprise Manager.

9. When the script prompts for the password of the web service, enter the password that must be provided to access the web service for Netcool/OMNIbus.

   The password can be any value and is not associated with any specific OS or Netcool/OMNIbus account. Note this value and supply it when configuring the Netcool/OMNIbus connector in Enterprise Manager.

10. When the script prompts for the username to access the Object Server database, enter the username of an account that has read access to the alerts.status, alerts.details, and alerts.journals database tables.

11. When the script prompts for the password to access the Object Server database, enter the password for the account specified in the previous step.

12. When the script prompts for the host name of the Object Server system, enter the host name or IP address of the system where the Object Server is installed. You will not be allowed to specify a host name of localhost, because the web service will fail when attempting to connect to the Object Server database.

13. When the script prompts for the Object Server database port number, enter the port number to use when connecting to the Object Server database. The default port number is 4100. To determine the port number used by your system, start the Netcool/OMNIbus Administrator and open the Object Servers window. The port number for the Object Server is listed on this window.

14. The web service can be configured to attempt to connect to a backup Object Server database if there are problems connecting to the primary Object Server database. You are prompted to specify whether you want to configure the web service to connect to a backup Object Server instance. If you answer N to the prompt, skip to step 17.

15. When the script prompts for the host name of the backup Object Server system, enter the host name or IP address of the system where the backup Object Server is installed. You are not allowed to specify a host name of localhost, because the web service will fail when attempting to connect to the Object Server database.

16. When the script prompts for the backup Object Server database port number, enter the port number to use when connecting to the backup Object Server database. The default port number is 4100. To determine the port number used by your system, start the Netcool/OMNIbus Administrator and open the Object Servers window. The port number for the Object Server is listed on this window.

17. When the script prompts for the master EIF probe host name, enter the host name or IP address of the system where the master TEC EIF probe is installed.

18. When the script prompts for the master EIF probe port number, enter the port number to use when connecting to the master TEC EIF probe. The port number is defined in the PortNumber property in the tivoli_eif.props file. The file is located in the EIF probe installation directory.

19. The web service can be configured to also send events to a slave EIF probe when sending events to the master EIF probe. You will be prompted to specify whether you want to configure the web service to send events to a slave EIF probe. If you answer N to the prompt, skip to step 22.

20. When the script prompts for the slave EIF probe host name, enter the host name or IP address of the system where the slave TEC EIF probe is installed.

21. When the script prompts for the slave EIF probe port number, enter the port number to use when connecting to the slave TEC EIF probe. The port number is defined in the PortNumber property in the tivoli_eif.props file. The file is located in the EIF probe installation directory.

22. After the script displays the message "Netcool/OMNIbus Adapter Install Complete," press Enter to complete the installation.

23. Copy additional required jar files as specified in Copying the Required .jar Files

24. If the web service was configured to run using the HTTPS protocol, you must set up SSL as specified in Section 6.1, "Configure Oracle Enterprise Manager to Use SSL."

25. Delete the OMNIbus_webservices_adapter.jar file from the installation directory.

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

2.5.3 Running the Web Service on Unix

To run the web service for Netcool/OMNIbus 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

2.5.4 Testing the Web Service on Unix

Perform the following steps to verify that the web service for Netcool/OMNIbus is functional.

1. Open a terminal and change the working directory to the adapters/bin directory in the installation directory.

2. Run the test script:

   ./testAdapter.sh
   

3. When the utility prompts for the web service password, enter the password you specified for the web service for Netcool/OMNIbus in step 9 of Installing the Web Service on Unix.

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

2.5.5 Copying the Required .jar Files

The web service for Netcool/OMNIbus requires you to copy the following .jar files to the lib/adapters directory:

• log.jar — Used by the EIF probe

• evd.jar — Used by the EIF probe

• jconn2.jar — Sybase JDBC driver file

To copy the appropriate .jar files, complete the following steps:

1. From the Object Server system, access the following directory:

   Unix:

   $OMNIHOME/probes/<platform>
   

   Windows:

   %OMNIHOME%\probes\<platform>
   

   Where:

   <platform> is the actual platform name (such as win32).

2. Copy the log.jar and evd.jar files to the lib/adapters directory in the web service installation directory.

3. Access the following URL to download the Sybase JDBC driver file:

   http://downloads.sybase.com/swd/summary.do?client=support&baseprod=63
   

4. Create an account, which is required to download the driver. After you have created an account, select All from the drop-down list next to "Display" and "in all months" next to "platforms."

5. Click Go to get a list of drivers available for download.

6. Select jConnect for JDBC - EBF 13904: 5.5 ESD #22 and download.

   This action downloads the EBF13904.tgz file. This file includes the jconnect55.zip file. The jconn2.jar file is located in this zip file in the jconnect55/jConnect-5_5/classes directory.

7. Copy the jconn2.jar file to the lib/adapters directory.

2.5.6 Uninstalling the Web Service on Unix

To uninstall the web service on Unix:

1. Open a command terminal on the system where the web service is installed.

2. Change the working directory to the adapters/bin directory in the web service installation directory.

3. Enter the following command to shut down the web service:

   ./service.sh stop
   

4. Enter the following command to go up two levels in the directory structure:

   cd ../..
   

5. Remove the adapters directory and all subdirectories using the following command:

   rm -rf adapters
   

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

2.6.2 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. Copy the OMNIbus_webservices_adapter.jar file from the Management Server host system to the web service installation directory. The file is located in the archives directory that was extracted in Exporting the Installation Files

3. Open a command prompt window and change the working directory to the web service installation directory.

4. Enter the following command to extract the web services components from the web services .jar file:

   jar xvf OMNIbus_webservices_adapter.jar
   

   Note:

   If the system where the web service for Netcool/OMNIbus is being installed does not have the JRE installed, you cannot extract the jar file contents. You need to copy the jar file to a system that has the installed JRE and transfer the files after they have been extracted.

   This creates the adapters directory that contains the installation files.

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

   cd adapters\endpoints\omnibus
   

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

   install.bat
   

7. When the script prompts whether you want to use HTTPS:

   • If you specify Y, then the web service is set up to use HTTPS port number 8443.

   • If you specify N, then the web service is set up to use HTTP port number 8080.

8. When the script prompts for the user name of the web service, enter a user name that must be provided to access the web service for Netcool/OMNIbus.

   The user name can be any value and is not associated with any specific OS or Netcool/OMNIbus account. Note this value and supply it when configuring the Netcool/OMNIbus connector in Enterprise Manager.

9. When the script prompts for the password of the web service, enter the password that must be provided to access the web service for Netcool/OMNIbus.

   The password can be any value and is not associated with any specific OS or Netcool/OMNIbus account. Note this value and supply it when configuring the Netcool/OMNIbus connector in Enterprise Manager.

10. When the script prompts for the username to access the Object Server database, enter the username of an account that has read access to the alerts.status, alerts.details, and alerts.journals database tables.

11. When the script prompts for the password to access the Object Server database, enter the password for the account specified in the previous step.

12. When the script prompts for the host name of the Object Server system, enter the host name or IP address of the system where the Object Server is installed. You will not be allowed to specify a host name of localhost, because the web service will fail when attempting to connect to the Object Server database.

13. When the script prompts for the Object Server database port number, enter the port number to use when connecting to the Object Server database. The default port number is 4100. To determine the port number used by your system, start the Netcool/OMNIbus Administrator and open the Object Servers window. The port number for the Object Server is listed on this window.

14. The web service can be configured to attempt to connect to a backup Object Server database if there are problems connecting to the primary Object Server database. You will be prompted to specify whether you want to configure the web service to connect to a backup Object Server instance. If you answer N to the prompt, skip to step 17.

15. When the script prompts for the host name of the backup Object Server system, enter the host name or IP address of the system where the backup Object Server is installed. You will not be allowed to specify a hostname of localhost, because the web service will fail when attempting to connect to the Object Server database.

16. When the script prompts for the backup Object Server database port number, enter the port number to use when connecting to the backup Object Server database. The default port number is 4100. To determine the port number used by your system, start the Netcool/OMNIbus Administrator and open the Object Servers window. The port number for the Object Server is listed on this window.

17. When the script prompts for the master EIF probe hostname, enter the host name or IP address of the system where the master TEC EIF probe is installed.

18. When the script prompts for the master EIF probe port number, enter the port number to use when connecting to the master TEC EIF probe. The port number is defined in the PortNumber property in the tivoli_eif.props file. The file is located in the EIF probe installation directory.

19. You can also configure the web service to also send events to a slave EIF probe when sending events to the master EIF probe. You will be prompted to specify whether you want to configure the web service to send events to a slave EIF probe. If you answer N to the prompt, skip to step 22.

20. When the script prompts for the slave EIF probe hostname, enter the host name or IP address of the system where the slave TEC EIF probe is installed.

21. When the script prompts for the slave EIF probe port number, enter the port number to use when connecting to the slave TEC EIF probe. The port number is defined in the PortNumber property in the tivoli_eif.props file. The file is located in the EIF probe installation directory.

22. After the script displays the message "Netcool/OMNIbus Adapter Install Complete," click Enter to complete the installation.

23. Copy additional required jar files as specified in Copying the Required .jar Files

24. If the web service was configured to run using the HTTPS protocol, you must set up SSL as specified in Section 6.1, "Configure Oracle Enterprise Manager to Use SSL."

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

26. Delete the OMNIbus_webservices_adapter.jar file from the installation directory.

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

2.6.3 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 web service for Netcool/OMNIbus framework when set up as a standalone application (not set up to run as a Windows service):

1. Change the working directory to the adapters\bin directory in the installation directory.

2. Run the following command:

   startAdapters.bat
   

To shut down the web service Netcool/OMNIbus framework, close the window where you started the web service.

Running as a Windows Service

To start the web service for Netcool/OMNIbus framework when set up to run as a Windows service, enter the following command:

net start iWaveAdapters

To shut down the web service Netcool/OMNIbus framework, enter the following command:

net stop iWaveAdapters

2.6.4 Testing the Web Service on Windows

Perform the following steps to verify that the web service for Netcool/OMNIbus is functional.

1. Open a terminal and change the working directory to the adapters\bin directory in the installation directory.

2. Enter the following command to run the test script:

   .\testAdapter.bat
   

3. When the utility prompts for the web service password, enter the password you specified for the web service for Netcool/OMNIbus in step 9 of Installing the Web Service on Windows.

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

2.6.5 Uninstalling the Web Service on Windows

To uninstall the web service on Windows:

1. Open a command terminal on the system where the web service is installed.

2. Change the working directory to the adapters\bin directory in the web service installation directory.

3. Enter the following command to shut down the web service:

   .\service stop
   

4. If the web service was configured to run as a windows service, enter the following command to uninstall the web service as a windows service:

   .\service uninstall
   

5. Delete the web service installation directory (adapters) and all subdirectories.

2.7.1 Uninstalling the Oracle Agent for Netcool/OMNIbus

To uninstall the Oracle Agent for Netcool/OMNIbus:

1. Perform the steps in Uninstalling Modifications to Netcool/OMNIbus.

2. Delete the Oracle Agent for Netcool/OMNIbus installation directory and all of its contents.

2.8.1 Configuring the Object Server Database

Perform the following steps to run the configuration script that sets up the Netcool/OMNIbus Object Server database to work with the installed Oracle Agent and web service components.

1. If the Oracle Agent for Netcool/OMNIbus was NOT installed on the primary Object Server system, copy the configure_oracle_webservice.sql file from the system where the Oracle Agent for Netcool/OMNIbus was installed to the system where the primary Object Server is installed.

2. Run the SQL script using the appropriate command listed below based on the applicable platform:

   Unix:

   $OMNIBUSHOME/bin/nco_sql -S <objserver> -U <username> -P <password>
   < <script_directory>/configure_oracle_webservice.sql
   

   Windows:

   "%OMNIBUSHOME%\bin\isql" -S <objserver> -U <username> -P <password>
   -i <script_directory>\configure_oracle_webservice.sql
   

   When entering the commands, provide the following information:

   • objserver — Object Server name

   • username — User name that will be used when connecting to the database. The account must have permission to create tables, triggers, and procedures in the Object Server database.

   • password — Password associated with the user name

   • script_directory — Directory where the configure_oracle_webservice.sql file is located. If the Oracle Agent for Netcool/OMNIbus was installed on the primary Object Server system, this will be the Oracle Agent for Netcool/OMNIbus installation directory. Otherwise, it will be the directory where the file was copied.

2.8.2 Configuring the TEC EIF Probe

You need to manually change the set up of the TEC EIF probe configuration to accept alerts from the web service for Netcool/OMNIbus. You must modify the existing EIF probe rules file to include an Oracle-supplied rules file.

To install the new rules file, perform the following steps:

1. Shut down the EIF probe.

2. Access the EIF probe installation directory.

3. Make a back-up copy of the existing tivoli_eif.rules file.

4. Copy the oracle_eif.rules file from the system where the Oracle Agent for Netcool/OMNIbus was installed to the EIF probe install directory.

5. Modify the tivoli_eif.rules file as follows:

   1. Insert the following statements before any other executable statements:

      defaultAlerts = registertarget("<PRIMARY>", "<BACKUP>", "alerts.status")
      OracleAlerts = registertarget("<PRIMARY>", "<BACKUP>", "custom.oracle_status")
      

   2. Replace <PRIMARY> with the name of the primary object server.

   3. Replace <BACKUP> with the name of the back-up server. If a back-up is not configured, replace it with an empty string so that the back-up server is "".

   4. In the location where the tivoli_eif_tpc.rules and tivoli_eif_tsm.rules files are included, add an include statement for the oracle_eif.rules file.

   5. Save the tivoli_eif.rules file.

6. Make sure the Inactivity parameter for the tivoli_eif.props file is set to 0.

7. Restart the EIF probe.

2.8.3 Change Deduplication Trigger Priority

The oracle_alert_reinserted trigger in the primary_only group must run first in order to function properly. To ensure the trigger runs first, the priority of the deduplication trigger in the default_triggers group must be changed from 1 to 2.The trigger priority can modified using the Netcool/OMNIbus Administrator application.

2.8.4 Uninstalling Modifications to Netcool/OMNIbus

To uninstall modification made to Netcool/OMNIbus:

Revert Deduplication Trigger Priority

Change the priority of the deduplication trigger in the default_triggers group back to 1. The trigger priority can modified using the Netcool/OMNIbus Administrator application.

Revert TEC EIF Probe Configuration

Perform the following to revert the TEC EIF probe configuration back to its original settings:

1. Shut down the EIF probe.

2. Access the EIF probe installation directory.

3. Replace the tivoli_eif.rules file with the backup copy of the file that was created during installation.

4. Delete the oracle_eif.rules file from the EIF probe install directory.

5. Restart the EIF probe.

Revert the Object Server Database Configuration

Perform the following steps to uninstall the customizations made to the Netcool/OMNIbus Object Server database during installation:

1. If the Oracle Agent for Netcool/OMNIbus was NOT installed on the primary Object Server system, copy the uninstall_oracle_webservice.sql file from the system where the Oracle Agent for Netcool/OMNIbus was installed to the system where the primary Object Server is installed.

2. Run the SQL script using the appropriate command listed below based on the applicable platform:

   • Unix:

     $OMNIBUSHOME/bin/nco_sql -S <objserver> -U <username> -P <password> <script_directory>/uninstall_oracle_webservice.sql
     

   • Windows:

     "%OMNIBUSHOME%\bin\isql" -S <objserver> -U <username> -P <password> -i <script_directory>\uninstall_oracle_webservice.sql
     

   When entering the commands, provide the following information:

   • objserver — Object Server name

   • username — User name that will be used when connecting to the database. The account must have permission to delete tables, triggers, and procedures from the Object Server database.

   • password — Password associated with the user name

   • script_directory — Directory where the uninstall_oracle_webservice.sql file is located. If the Oracle Agent for Netcool/OMNIbus was installed on the primary Object Server system, this will be the Oracle Agent for Netcool/OMNIbus installation directory. Otherwise it will be the directory where the file was copied.