Configuring the Oracle Database agent

The Oracle Database agent provides monitoring capabilities for the availability, performance, and resource usage of the Oracle database. You can configure more than one Oracle Database instance to monitor different Oracle databases. The remote monitoring capability is also provided by this agent.

• To configure the agent by editing the silent response file and running the script with no interaction, complete the following steps:
  1. Open the oracle_silent_config.txt file in a text editor:
     • install_dir/samples/oracle_database_silent_config.txt.
     • install_dir\samples\oracle_database_silent_config.txt
  2. For Default Username, you can specify the name of the default database user for the connection, for example KRZ_CONN_USERID= user1.
     Note: This user must have sufficient privileges to complete the tasks that this agent completes while it is connected to the database, such as querying tables. If the user name is not entered for the database connection, the default user name is used.
  3. For Default Password, you must enter the password that is associated with the specified default database user, for example, KRZ_CONN_PASSWORD= Password.
     Note: If the password is not entered for the database connection, the default password is used.
  4. For Oracle Home directory, you must complete the following steps:
     • Leave this field empty if you do not have an Oracle database installed.
     • Complete one of the following steps:
       • Define only the Oracle Home directory now.
       • Define the Oracle Home directory now and then define the Oracle Instant Client Installation directory in the next step.
       • Define only the Oracle Instant Client Installation directory in the next step.
       • Do not define the Oracle Home directory or the Oracle Instant Client Installation directory in the next step. Then, before you start the agent, you must set the ORACLE_HOME system environment variable as shown here: #KRZ_ORACLE_HOME=home_path.
  5. For Oracle Instant Client Installation directory, you must complete the following steps:
     • Leave this field empty if you do not have an Oracle instant client installed.
     • Complete one of the following steps:
       • Download the Oracle instant client now.
         Note: If you define both the Oracle home directory and the Oracle instant client installation directory, the Oracle home directory is used for the configuration.
       • Define the full folder path of the Oracle Home directory that contains the Oracle Call Interface (OCI) library files. If the full path of the oci.dll file is C:\instantclient_10_2\oci.dll you must define this C:\instantclient_10_2 path.
       • Define the full folder path of the Oracle Home directory that contains the Oracle Call Interface (OCI) library files. If the full path of the libocci.so.10.1 file is /home/tivoli/oci/libocci.so.10.1, you must define this /home/tivoli/oci path.
     Note: The Oracle instant client installation directory is on the system where the agent is installed. The attribute does not support the Oracle instant client that is in a network drive.
  6. You specify the directory that contains the Oracle database net configuration file. The Oracle Database agent uses this file path to obtain the tnsnames.ora file. This directory is defined by the TNS_ADMIN environment variable for each Oracle database instance. The default directory is ORACLE_HOME/network/admin on UNIX or Linux systems, and ORACLE_HOME\NETWORK\ADMIN on Windows systems. ORACLE_HOME is the installation directory for the Oracle database.

     If you have multiple net configuration file directories, separate the directories by using a semicolon (;)

     If you have multiple net configuration file directories, separate the directories by using a colon (:)

     If you are monitoring Oracle databases remotely, you can copy net configuration files from the remote system to the system where the agent is installed. Also, you can merge the content of net configuration files on the remote system to the net configuration files on the system where the agent is installed.

  7. For Dynamic listener, check if the default dynamic listener is configured. The default dynamic listener is (PROTOCOL=TCP)(HOST=localhost)(PORT=1521). If the default dynamic listener is configured, set this value to TRUE as shown here; KRZ_DYNAMIC_LISTENER = TRUE.

     The valid values are TRUE and FALSE.

  8. For Customized SQL definition file name, set one of the following file names:
     • The default file name is install_dir\TMAITM6\krzcussql.properties.
     • x64 systems, the default file name is install_dir\TMAITM6_x64\krzcussql.properties.
     • The default file name is install_dir/config/krzcussql.properties.

     The customized SQL definition file name is the full file path name of the customized SQL definition file.

  9. For Connection Type, specify one of the following connection types: Basic, TNS, or Advanced. For example, KRZ_CONN_TYPE.config1=Basic.
  10. For the connection type that you selected in Step 9, specify the required parameters:

      Basic

      • For Hostname, specify the host name or the IP address of the Oracle database, for example: KRZ_CONN_HOST.config1= hostname.
      • For Port, specify the Listener port for the Oracle database, for example: #KRZ_CONN_PORT.config1= 1521.
      • For Service Name, specify the logical representation of the database by using a string for the global database name, for example: KRZ_CONN_SERVICE.config1= orcl.
        Important: If you do not define the Service Name, you must specify the Oracle System Identifier (SID).

        For the Oracle System Identifier (SID), specify an SID that identifies a specific instance of a running database, for example: KRZ_CONN_SID.config1= sid.

      TNS

      For TNS alias, specify the Network alias name from the tnsnames.ora file. For example, KRZ_CONN_TNS.config1= tnsalias.

      Advanced

      For Oracle Connection String, specify the database connection string for OCI. For example, KRZ_CONN_STR.connection1= //host:port/service

      This string supports all Oracle net naming methods as shown here:

      • For an SQL Connect URL string of the form;

        //host:[port][/service name]

      • For an Oracle Net keyword-value pair:

        "(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=dlsun242) (PORT=1521)) (CONNECT_DATA=(SERVICE_NAME=bjava21)))"

      This string also supports TNSNAMES entries, for example, inst1 where the TNS_ADMIN or the ORACLE_HOME environment variable is set and the configuration files are configured.

      Important: This attribute applies only to the advanced type of connection.

  11. For Database Username, you can specify the name of the database user for the connection, for example: KRZ_CONN_USERID= UserID.

      This user must have sufficient privileges to complete the tasks that the agent requires while it is connected to the database, for example, creating, editing, and deleting tables.

      If this field is empty, the agent uses the default user name in the default database configuration section. If Database Username was not configured, the default user name is used for this connection.

  12. For Database Password, you can specify the password that is associated with the specified database user, for example: KRZ_CONN_PASSWORD= Passsword.

      If this field is empty, the agent uses the default password in the default database configuration section. If Database Password was not configured, the default password is used for this connection.

  13. For Role, you can specify the set of privileges that are associated with the connection, for example: KRZ_CONN_MODE.connection1=DEFAULT.

      The valid values include; SYSDBA, SYSOPER, SYSASM, and DEFAULT.

      For a user that is granted the SYSDBA system privilege, you can specify a connection that includes this privilege. If this item is not defined, you can assign the DEFAULT role to the user.

  14. For Oracle Alert Log File Paths, that includes the alert log file name, you can specify the absolute file path of the mapped alert log files for the remote database instances in this database connection. For example, KRZ_LOG_PATHS.connection1= AlertLogPath.

      You use a semicolon (;) to separate the multiple files.

      You use a colon (:) to separate the multiple files.

      Each file is matched to a database instance by the alert_instance.log file name pattern. Alternatively, it is ignored if it is not matched.

      The local database instance alert log files are discovered automatically.

      If Oracle Alert Log File Paths was not configured, The Alert Log is not available.

  15. For Oracle Alert Log File Charset, you can specify the code page of the mapped alert log files. For example, KRZ_LOG_CHARSET.connection1= CharSet
      If this field is empty, the system current locale is used as shown here:

      ISO8859_1: ISO 8859-1 Western European encoding
      UTF-8: UTF-8 encoding of Unicode
      GB18030: Simplified Chinese GB18030 encoding
      CP950: Traditional Chinese encoding
      EUC_JP: Japanese encoding
      		

  16. Save and close the oracle_database_silent_config.txt file. Then, enter:
      install_dir/bin/oracle_database-agent.sh config instance_name install_dir/samples/oracle_database_silent_config.txt
      Where instance_name is the name that you want to give to the instance.
  17. To start the agent, enter:
      /bin/oracle_database-agent.sh start instance_name.
• To configure the agent by responding to prompts, complete the following steps:
  1. Open the install_dir/bin directory, where install_dir is the installation directory for the Oracle Database agent.
  2. (Optional) To check the names and settings for the configured agent instances, run the following command: ./cinfo -s rz.
  3. To configure the Oracle Database agent, run the following command: ./oracle_database-agent.sh config instance_name.
  4. When prompted to edit the Oracle Database agent settings, press Enter. The default value is Yes.
  5. When prompted to edit the Default Database Configuration settings, press Enter. The default value is Yes.
  6. To enter the default database configuration information, complete the following steps.
     1. When prompted for the default user name, type the default database user ID for the connection and press Enter.

        This user ID is the one that the agent uses to access the connected database instance. This user ID must have select privileges on the dynamic performance views and tables that are required by the agent.

     2. For default password, type the password that is associated with the specified default database user ID, and press Enter. Then, confirm the password.
     3. If you have the Oracle database that is installed, type the Oracle home directory, and press Enter. If you want to clear the value for the Oracle home directory, press the space bar, and then press Enter. If you do not press Enter, complete the next step.
     4. Type the Oracle instant client installation directory, and press Enter. If you entered the Oracle home directory, this value is ignored.
     5. Type the file path of the directory that contains the Oracle database net configuration file, and press Enter.
     6. Choose whether the default dynamic listener is configured at this workstation, and press Enter.
     7. Type the full file path of the customized SQL definition file, and press Enter.
  7. When prompted to edit the Database Connection settings, press Enter. The default value is Yes.
  8. To add a database connection, type 1, and press Enter.
  9. To enter the database connection information, complete the following steps:
     1. When prompted for the connection name, type the alias for the connection to the database and press Enter.

        Only letters, Arabic numerals, the underline character, and the minus character can be used in the connection name. The maximum length of a connection name is 25 characters.

     2. When prompted for the connection type, select one of the following types of connection:
        • Basic

          The default connection type is Basic. Select the Basic connection type when the target monitored database is a single instance, such as RDBMS, ASM single instance, DataGuard Primary Node single instance, or DataGuard standby node single instance.

          1. When prompted for the Hostname, type the host name or IP address for the Oracle database, and press Enter.
          2. When prompted for the port, type the port number, and press Enter.
          3. (Optional) When prompted for the service name, type the name of the service that is a logical representation of a database, a string that is the global database service name, and press Enter.
          4. (Optional) When prompted for the SID, type the Oracle System Identifier that identifies a specific instance of a running database, and press Enter.
        • TNS

          Select the TNS connection type when the ORACLE HOME directory is specified and the TNS alias for the target monitored database is defined in the $ORACLE_HOME/network/admin/tnsnames.ora file.

          1. Type the TNS Alias name, and press Enter.
        • Advanced

          Select the Advanced connection type when there is more than one Oracle Instance across multiple physical nodes for the target monitored database. For example, the Real Applications Cluster (RAC) database or the ASM cluster database.

          1. Type the Oracle connection string, and press Enter.
             This attribute supports all Oracle net naming methods as follows:

             • SQL Connect URL string of the form://host:port/service name. For example, //dlsun242:1521/bjava21.
             • Oracle Net keyword-value pair. For example,

               (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=dlsun242) (PORT=1521)) 
               (CONNECT_DATA=(SERVICE_NAME=bjava21)))

             • TNSNAMES entries, such as inst1, with the TNS_ADMIN or ORACLE_HOME environment variable set and the configuration files configured.
     3. When prompted for the database user name type the database user ID for the connection, and press Enter.

        For RDBMS instances, this user ID must have select privileges on the dynamic performance views and tables that are required by the agent.

        For ASM instances, use an account with the SYSDBA or SYSASM role. For example, the sys account.

     4. When prompted for the database password, type the password that is associated with the specified database user ID.
     5. When prompted for Role, type the role name, and press Enter.

        The role is the set of privileges to be associated with the connection. For a user that was granted the SYSDBA system privilege, you can specify a connection that includes that privilege.

        For ASM instances, use the SYSDBA role for the Oracle database 10 g, and the SYSDBA or SYSASM role for the Oracle database 11 g.

     6. When prompted for Oracle alert log file paths, type the Alert Log paths, and press Enter.

        The absolute file paths of mapped alert log files for remote database instances in this database connection. The agent monitors alert logs by reading these files.

        If the Oracle Database agent runs and reads the alert log files through the network, the remote file path must follow the universal naming convention for Windows systems. For example, \\tivx015\path\alert_orcl.log.

        Important: Enter the path and alert log file name together. A mapped network driver is not supported for the alert log path.

        If the Oracle Database agent runs, a locally mounted file system is required for remote alert logs.

        Multiple files are separated by a semicolon (;).

        Multiple files are separated by a colon (:).

        Each file is matched to a database instance by using the alert_instance.log file name pattern or if it is unmatched, it is ignored.

        Local database instance alert log files can be discovered automatically.

     7. When prompted for oracle alert log file charset, type the code page of the mapped alert log files, and press Enter
        If this field is blank, the system current locale is used, for example:

        • ISO8859_1, ISO 8859-1 Western European encoding
        • UTF-8, UTF-8 encoding of Unicode
        • GB18030, Simplified Chinese GB18030 encoding
        • CP950, Traditional Chinese encoding
        • EUC_JP, Japanese encoding
        • EUC_KR, Korean encoding

        For the full list of all the supported code pages, see the ICU supported code pages.

  10. (Optional) To add multiple database connections to monitor multiple database instances, type 1 and press Enter. Then, select one of the following options:
      1. 2 Edit, to edit a database connection
      2. 3 Del, to delete a database connection
      3. 4 Next, to change to next database connection
      4. 5 Exit, to exit the database connection section
  11. Type 5, and press Enter.