Chapter 2. Installation Instructions

This chapter provides you with specific installation instructions for the standard scenarios. For more complex installations, use the instructions in this chapter together with the information in Chapter 3, “Managing Multiple ORACLE Databases.”

In the remainder of this guide, “the database system” means the remote system that is running the ORACLE database instance you wish to monitor, “the database instance” refers to the database instance on the database system, and “the monitoring system” refers to the system where the PCP monitoring tools are running.

PCP Collector Installation

On a PCP collector system, follow the procedure described in “Collector Installation Procedure” once for each ORACLE database instance that you wish to monitor. This procedure installs one PCP agent for each ORACLE database, and ensures that the associated ORACLE performance metrics can be exported into the PCP framework.

Collector Prerequisites

Prerequisites for the collector system are as follows:

  • The pcp.sw, pcp_eoe.sw, and pcp_ora.sw.collector product images must have been installed, using either swmgr or inst; see the inst(1M) reference page.

  • The pmcd daemon must be running on the PCP collector system.

  • You must have superuser (root) permission to run Install.

  • You must know the ORACLE_HOME and ORACLE_SID environment variables for the desired database instance.

  • The ORACLE database instance must be up and running.

  • You must have DBA access to the database instance as the SYS database user.

The pmdaoracle agent needs access to the database, so an ORACLE user must be created on your system for this. The Install script automatically generates SQL statements to create the ORACLE database user and grant that user suitable privileges for the database (that is, “select” access to the dynamic V$* views).

Before running Install you must decide on a name for this ORACLE user. You have two options: create a conventional user with a password (such as pcp/pcp), or use a default login (such as ops$pcp). If you are upgrading an existing PCP installation, the old pmcd configuration file (/etc/pmcd.conf) shows the previously specified user. See “Upgrading an Existing Installation” or the pmcd(1) and pmdaoracle(1) reference pages.

If a system contains multiple ORACLE database instances, it is strongly recommended that you use the same ORACLE database user for all of the ORACLE database instances and corresponding instances of pmdaoracle on that system. If you elect to use a default login for pmdaoracle (an ops$... user), then it is essential that the same user be specified for all database instances. However, note that the ORACLE database user may differ between systems, if necessary.

Collector Security Issues

There are some security issues. Under the “user with a password” approach, the user's name and password appear on the command line of the ORACLE agent run by pmcd. Disclosure of this information may allow unauthorized users to connect to the database as this PCP for ORACLE user, and have read access to the performance data made available by ORACLE. However, note that no access is granted to any other data in the database.

If possible, it is better to create an ops$... login instead, so that no password appears on the command line. If you choose this option, you must create an IRIX user account with the appropriate name prior to running the Install script (for example, an account named pcpora for the ops$pcpora ORACLE user). If this account is used only for the ORACLE agent, it is strongly recommended that you disable standard logins for it. Refer to IRIX Admin: System Configuration and Operation for information on the procedure to disable logins.

Caution: If an ORACLE database user with the same name already exists, part of the installation process grants that user select (only) access on several of the ORACLE dynamic performance views.

Collector Installation Procedure

Run Install by performing the tasks outlined below. The ORACLE database must be up and running before you can perform the following procedure.

To install a collector for one ORACLE database instance, follow these steps:

  1. Become superuser using the su command or by logging in as root.

  2. Set the environment variables ORACLE_HOME and ORACLE_SID for the ORACLE database you want.

    Note: If the ORACLE_SID is not a valid PCP namespace identifier, run Install with the -r option to specify an alternative name for this database's ORACLE metrics in the namespace. Valid identifiers consist of an initial letter followed by zero or more letters, digits, or underscores. For example, if your ORACLE_SID is 7.1.6 you might specify -r inst_7_1_6.

  3. Enter the following command, replacing XXX with the ORACLE database user identification (and optional password) you chose:

    # ./Install XXX 

    For example, if you elected to use a default login of ops$pcp, you would enter:

    # ./Install 'ops$pcp' 

    The single quotes in the command above stop the shell from trying to evaluate $pcp as a shell variable.

    If instead you decided to create a user named pcpora with a password of secret9, you would enter:

    # ./Install pcpora/secret9 

    If there are any errors, your PCP configuration is restored to its previous state before you ran Install.

  4. When finished, Install prints a few post-installation tasks that you must perform. In the example text below, DBNAME is the name of your ORACLE database.[1] You see a message similar to the following:

    You must run setup.DBNAME.sql as SYS on the ORACLE_SID database 
    to grant the Oracle PMDA access to the dynamic performance tables.

    For example:

    # $ORACLE_HOME/bin/sqldba lmode=y 
    SQLDBA> connect sys 
    SQLDBA> @setup.DBNAME.sql 

    Once this has been done, start the pmdaoracle PMDA to verify that the installation has completed correctly:

    # killall -HUP pmcd 
    # ./Verify-DBNAME 

    When performing these tasks, make sure that you use the ORACLE_HOME and ORACLE_SID that were in the environment when you ran Install.

The pmcd daemon is started automatically when the system reboots. ORACLE databases too are often started automatically when the system reboots. Because they take some time to initialize and become available, they are often started in the background so as not to hold up the reboot sequence. If PMCD is started before the ORACLE database is available, the ORACLE PMDA will not be able to connect to the database.

If it has no connection, pmdaoracle periodically attempts to (re)connect to the database.

Note that the pmcd process does this only when ORACLE performance metrics are requested. In addition, there is a cooling-off period between connection attempts, to prevent a flood of requests for ORACLE metrics from generating a corresponding flood of ORACLE database connection attempts. See the pmdaoracle(1) reference page for more details.

If you do not want the common prefix for the names of PCP ORACLE metrics in the namespace to correspond with the ORACLE database instance name, the Install command's -r option allows you to specify an alternative. For example, the following commands cause pmdaoracle to run on the demo database instance:

# ORACLE_SID=demo 
# ./Install -r pqo_demo 'ops$pcp' 

However, the metrics appear in the namespace under oracle.pqo_demo, as opposed to oracle.demo. This can be useful when several databases on different systems have the same ORACLE_SID. Once started, pmdaoracle in this case creates an activity record in /var/adm/pcplog/oracle-pqo_demo.log to report unusual or error conditions that occur while the PMDA is running.

Customized Configuration Files

The base PCP product and PCP for ORACLE contain a number of configuration files that can be modified to reflect the local configuration or product customizations. When you install a new version of PCP and the installation software discovers that you have customized a file, it performs one of two possible actions:

  • It may save the customized file (by appending .O to its name) then put the new version of the file in its place.

  • It may leave the customized version of the file in place and save the new one to a temporary name (by appending .N to the default name).

Use the following command to find conflicts, then reconcile differences as needed, using xdiff to compare files (see xdiff(1L) for details).

$ showfiles -cCH pcp\* 

PCP Monitor Installation

On a PCP monitor system, the installation procedure is quite simple, involving just the installation of graphical monitoring tools.

Monitor Prerequisites

Prerequisites for the monitoring system are as follows:

  • The pcp.sw, pcp_eoe.sw, and pcp_ora.sw.monitor product images must have been installed, using either swmgr or inst; see the inst(1M) reference page.

  • You must have superuser (root) permission to run Install.

  • Install must have been run on the database system to install an ORACLE agent for the database instance.

In the remainder of this guide, “the database system” means the remote system that is running the ORACLE database instance you wish to monitor, “the database instance” refers to the database instance on the database system, and “the monitoring system” refers to the system where the PCP monitoring tools are running.

Upgrading an Existing Installation

Given the variation possible in ORACLE installations, it is not possible to automatically upgrade an existing PCP for ORACLE installation by typing a single upgrade command. Fortunately, upgrading is a straightforward process.

Note: The PCP for ORACLE directory moved from /usr/demos/PerfCoPilot/pmdas/oracle7 in PCP for ORACLE 1.0, then to /usr/pcp/pmdas/oracle7 in PCP for ORACLE 1.1, then to /var/pcp/pmdas/oracle7 in PCP for ORACLE 1.2, and finally to /var/pcp/pmdas/oracle in this release, PCP for ORACLE 2.0. The Install and Remove scripts described in this document should be run from this new directory.

Follow this procedure:

  1. Make a copy of the current /etc/pmcd.conf. Use this command:

    # cp /etc/pmcd.conf /etc/pmcd.conf.old 

    If you have customized the flags used for pmdaoracle, you can use the saved version as a reference for replacing your customizations. For more information on flags, see the pmdaoracle(1) reference page. Even if you did not customize flags, the pmcd.conf.old file contains all the previous domain assignments if you need to reconstruct them.

  2. Find the username and password of each pmdaoracle.

    To upgrade each pmdaoracle you need to know the username and password it uses to connect to its database. Use the grep command to search for the string pmdaoracle in /etc/pmcd.conf. The ORACLE_HOME and ORACLE_SID appear as the last two entries on each line. If there is a -c flag, it is followed by the username/password pair that the agent uses for database connections. If there is no -c flag, an ops$... login is being used; the pmdaoracle executable has the setuid mode bit set, and the IRIX user who owns the file determines the ops$... user for ORACLE.

    For example, if pmdaoracle is setuid and owned by pcpora, as in the example below, the corresponding ORACLE username is ops$pcpora.

    # cd /var/pcp/pmdas/oracle 
    # ls -l pmdaoracle 
    -rwsr-xr-x    1 pcpora   sys     3119516 Nov 11 12:38 pmdaoracle

  3. Use the instructions earlier in this chapter to install the new version of PCP for ORACLE. Use the same ORACLE username (and optional password) that the existing pmdaoracle uses. Remember that there are two kinds of installation: one for systems configured as PCP collectors, and one for PCP monitor systems.

    The ORACLE username and password are necessary only for PCP collector installations. PCP collector systems must be upgraded because the agent has been enhanced to extract new metrics. PCP monitor systems must also be upgraded so the new metrics appear in the PCP namespace.

  4. If you have trouble upgrading, you may use the Remove script to delete the pmdaoracle, then install it from scratch by following the instructions in “PCP Collector Installation” and in “PCP Monitor Installation”.

  5. Reapply any customizations you might have made to ORACLE agents in the /etc/pmcd.conf file on each system running an ORACLE database. Use the saved version from step 1 (/etc/pmcd.conf.old) as a guide.

  6. Check that metrics are available from each system. For example:

    $ pminfo -f oracle 

  7. Remove any old PCP for ORACLE directories and their contents. For example:

    # rm -rf /usr/demos/PerfCoPilot/pmdas/oracle7 
    # rm -rf /usr/pcp/pmdas/oracle7.0 
    # rm -rf /var/pcp/pmdas/oracle7 

Removing an Installation

The Remove script is the reverse of Install. The Remove script is run in the same way on both the PCP collector systems and on the PCP monitor systems. Remove must have the name of the ORACLE metrics in the PCP namespace (without the oracle part of the name) as a parameter.

For example, the following sequence of Bourne shell commands installs a PCP collector for the demo database instance:

# ORACLE_SID=demo 
# export ORACLE_SID 
# ORACLE_HOME=/oracle/home 
# export ORACLE_HOME 
# ./Install 'ops$pcp' 

To undo the actions of the above commands, use the following command:

# ./Remove demo 

The same command works on PCP monitor systems, provided you specify the correct name for the ORACLE metrics to be removed.

If you are not sure what ORACLE metrics are available in the namespace, the following command produces a list of names suitable for use as parameters to Remove:

$ pminfo oracle | cut -f2 -d. | sort -u 

Remember that the name of the ORACLE metrics in the namespace should be used as the parameter. If the -r option was used to override ORACLE_SID when Install added the ORACLE metrics to the namespace, the name of the ORACLE metrics in the namespace may not correspond to ORACLE_SID. Consider the following sequence of commands on a PCP collector system:

# ORACLE_SID=demo 
# export ORACLE_SID 
# ORACLE_HOME=/oracle/home 
# export ORACLE_HOME 
# ./Install -r pqo_demo 'ops$pcp' 

To undo the effects of this installation, enter the following command:

# ./Remove pqo_demo 

Remove checks that the corresponding entry in /etc/pmda.conf is removed, notifies pmcd to ensure termination of the PMDA, and culls all of the associated ORACLE metrics from the PCP namespace. If this is the only existing ORACLE PMDA, Remove also deletes the pmdaoracle executable.

Remove does not remove any users added to the ORACLE database for monitoring the ORACLE performance statistics—this must be done separately.

[1] DBNAME should be the same as the ORACLE_SID of your database unless you gave it a different name by using the -r option when you ran Install.