3
Configuring Oracle Real Application Clusters Databases

Oracle Real Application Clusters Guard enhances the high-availability features for Oracle Real Application Clusters databases running on Microsoft clusters. When you configure an Oracle Real Application Clusters database into an MSCS cluster with Oracle Real Application Clusters Guard, Oracle Real Application Clusters Guard:

• Provides a wizard that helps you to configure Oracle Real Application Clusters databases into an MSCS cluster

• Provides a wizard that simplifies the process of configuring new instances

• Optionally runs a user-written script before or after database instance state changes occur

This chapter discusses the following topics:

Topic	Reference
What Does It Mean to Configure a Database?	Section 3.1
Discovering Unconfigured Oracle Real Application Clusters Databases	Section 3.2
Configuring Oracle Real Application Clusters Databases	Section 3.3
Configuring Additional Database Instances	Section 3.4
Unconfiguring Oracle Real Application Clusters Database Instances	Section 3.5
User-Specified Script for Database Instance State Change Events	Section 3.6
Network Configuration for Configured Databases	Section 3.7
Client Connections to Configured Oracle Real Application Clusters Databases	Section 3.8
Changing the Database Password	Section 3.9
Performing Administrative Tasks on a Configured Database Instance	Section 3.10
Clients and Cluster-Aware Applications	Section 3.11

3.1 What Does It Mean to Configure a Database?

Because of the numerous hardware and software components involved, configuring Oracle Real Application Clusters databases into an MSCS cluster can be a complex process. However, the Oracle Real Application Clusters Guard Manager Configure Database Wizard helps you to configure databases into an MSCS cluster automatically and with minimal work by a network manager. The wizard minimizes the risk of introducing configuration problems during implementation. It also reduce the level of expertise required to configure Oracle Real Application Clusters. Most policies that are set by default when you configure the database can be modified later with Oracle Real Application Clusters Guard Manager.

Once the wizard has collected all needed information, Oracle Real Application Clusters Guard Manager interacts with Oracle Services for MSCS to facilitate an enhanced high-availability environment.

Based on the information that you provide with the wizard, Oracle Real Application Clusters Guard derives any additional information it requires to configure the environment.

The following list describes the specific steps Oracle Real Application Clusters Guard performs to configure an Oracle Real Application Clusters database into an MSCS cluster:

1. Ensures that the Oracle homes are symmetrical across all cluster nodes

2. Creates a group for each database instance and populates each with these resources:
   • Oracle Real Application Clusters database instance

   • Oracle Net listener created by Oracle Real Application Clusters Guard

   • Virtual address or addresses that you specify

3. Validates the virtual address you specified by doing the following:
   • Pinging each virtual address that you specified to ensure that it is valid.

   • Testing that every virtual address can come online on all cluster nodes.

4. Configures access to the database instances using a virtual addresses:
   1. Configures Oracle Net to use the virtual address on all nodes listed in the possible owner nodes list for the database instance

   2. Duplicates the network configuration information on all nodes in the cluster and on the server running Oracle Real Application Clusters Guard Manager

5. Ensures that each database instance can come online on its preferred owner node

By performing these steps, Oracle Real Application Clusters Guard ensures that the database, listener, and virtual addresses are correctly configured and instance groups are capable of failing over and failing back to all possible owner nodes of the group to which they have been added.

3.2 Discovering Unconfigured Oracle Real Application Clusters Databases

Oracle Real Application Clusters Guard discovers unconfigured Oracle Real Application Clusters databases (whose instances are not in a group) to display them in the Oracle Real Application Clusters Guard Manager tree view by issuing the SRCVTL config command.

As shown in Figure 3-1, you can view the unconfigured Oracle Real Application Clusters databases in the Oracle Real Application Clusters Guard Manager tree view by expanding the Unconfigured Databases folder. To view the instances for the unconfigured database, expand the Oracle Real Application Clusters database, then expand the Instances folder.

Figure 3-1 Tree View of Unconfigured Databases and Instances

Text description of the illustration ops_stndalone_tree.gif

3.3 Configuring Oracle Real Application Clusters Databases

Oracle Real Application Cluster Guard Manager provides the Configure Database Wizard to help you create a group and virtual address for each of the Oracle Real Application Clusters database instances and configure the Oracle Real Application Clusters database into the MSCS cluster. To open the wizard, select the unconfigured Oracle Real Application Clusters database from the Oracle Real Application Clusters Guard Manager tree view, then from the Real Application Clusters menu, choose the Configure Database option.

When the configuration is complete, modify the tnsnames.ora file on each client system to recognize the virtual address of each group that contains an Oracle Real Application Clusters database instance. (See Section 3.7 for more information.)

3.3.1 Configuration Data for Oracle Real Application Clusters Databases

Oracle Real Application Clusters Guard Manager provides the Configure Database Wizard to assist you in configuring an Oracle Real Application Clusters database into an MSCS cluster. The pages presented in the wizard vary, depending on the number of instances associated with the Oracle Real Application Clusters database.

Typically, one virtual address is added to each group; more complex configurations might have more than one virtual address. To perform a typical configuration using the Configure Database Wizard, you need the following data:

• Identity of the Oracle Real Application Clusters database (database name and database service name)

• An account through which MSCS and Oracle Services for MSCS can access the database (You can specify the SYS account or use operating system authentication.)

• Whether or not you want Oracle Services for MSCS to maintain password files (if they exist for the standalone database)

• A least one virtual address per Oracle Real Application Clusters database instance

• The initialization parameter file specification for each Oracle Real Application Clusters database instance

The following sections describe the configuration requirements for Oracle Real Application Clusters databases in detail.

3.3.1.1 Database Identity

The Configure Database Wizard requests database identity information to uniquely identify the Oracle Real Application Clusters database that is being configured, as shown in Figure 3-2. Oracle Real Application Clusters Guard uses this data to update cluster information, such as the tnsnames.ora file. It also passes the data that you supply to MSCS, where it is registered for use when a database instance is brought online, taken offline, or when Is Alive polling is performed. Oracle Real Application Clusters Guard requests the following information:

• Database name

  This is the DBName parameter used to identify the database in the initialization parameter file. It is the name that was used when the database was created.

• Database service name

  The database service name is a string that is the global database name (a name consisting of the database name and domain name entered during database installation or creation). If you are not sure what the global database name is, you can obtain it from the SERVICE_NAMES parameter in the database initialization file, init<database-name>.ora.

• Port number

  The port number is the port on which you want the Oracle listener to receive database requests. The default port number is 1521.

Figure 3-2 Configure Database Wizard - Identity Page

Text description of the illustration ops_config_wiz_id.gif

3.3.1.2 Account

The Account page is presented if the account or accounts under which Oracle Services for MSCS and MSCS were installed are not in one of the following Windows operating system groups: the ORA_DBA group or each of the ORA_<SID>_DBA groups associated with the database. (There is an ORA_<SID>_DBA group for each instance associated with an Oracle Real Application Clusters database.) When the account or accounts under which Oracle Services for MSCS and MSCS were installed are in the ORA_DBA group or each of the ORA_<SID>_DBA groups, they can use operating system authentication to access the database and its instances. If the account or accounts are not members of the ORA_DBA group or each of the ORA_<SID>_DBA groups, they must use the SYS account to access the database and its instances.

This page allows you to specify whether Oracle Services for MSCS and MSCS should use operating system authentication or the SYS account to access the database and its instances, as shown in Figure 3-3.

Note: The Account page is not presented if the account or accounts under which Oracle Services for MSCS and MSCS were installed are already members of a Windows local group that will allow them to access the database using operating system authentication.

Figure 3-3 Configure Database Wizard - Account Page

Text description of the illustration ops_config_wiz_account.gif

If you select the "Use operating system authentication" option, then Oracle Services for MSCS opens the Confirm Add to DBA Group window, as shown in Figure 3-4.

The text in Figure 3-4 indicates that Oracle Services for MSCS and MSCS were installed under the NEDCDOMAIN\cluadmin account. If you click Yes, the NEDCDOMAIN\cluadmin account will be added to the Windows operating system groups ORA_crm1_DBA on node ntclu-80 and ORA_crm2_DBA on node ntclu-81. crm1 and crm2 are the database SIDs for the crm database instances.

Figure 3-4 Confirm Add to DBA Group Window

Text description of the illustration confirm_add_dba.gif

3.3.1.3 Password

If Oracle Services for MSCS detects that the unconfigured Oracle Real Application Clusters database instances have password files associated with them, then the Configure Database Wizard asks if you want Oracle Services for MSCS to maintain these password files, as shown in Figure 3-5.

Oracle Corporation recommends that you select the "Yes, maintain the password files" option. A password file is often required when you perform remote operations. For example, Recovery Manager (RMAN) requires a password file when connecting to the target database over a nonsecure Oracle Net connection, especially when you want to back up an Oracle Real Application Clusters database from more than one node in the cluster concurrently, using only one RMAN session.

If you select the "No, do not maintain the password files" option, all users must access the database using operating system authentication and remote access will not be possible.

Note: If Oracle Services for MSCS does not detect password files for the database instances associated with the database that you are configuring, then it does not present the Password page.

Figure 3-5 Configure Database Wizard - Password Page

Text description of the illustration ops_config_wiz_passwd.gif

Oracle Services for MSCS makes the following adjustments to the database initialization parameter file (if needed), depending on whether or not you choose to have Oracle Services for MSCS maintain the password files:

• Yes, maintain the password files

  Sets the REMOTE_LOGIN_PASSWORDFILE parameter to SHARED or EXCLUSIVE.

• No, do not maintain the password files

  Sets the REMOTE_LOGIN_PASSWORDFILE parameter to NONE.

  Note: Oracle Real Application Clusters Guard does not support setting the Windows registry DBA_AUTHORIZATION parameter to the value of BYPASS.

If you want to change the password for the SYS account after the Oracle Real Application Clusters database has been configured, you must also update the password through Oracle Real Application Clusters Guard Manager. See Section 3.9 for information on how to update the password for this account after the Oracle Real Application Clusters database has been configured into the MSCS cluster.

3.3.1.4 Group

The Configure Database Wizard requests a base name for the groups that Oracle Real Application Clusters Guard will create to hold each database instance, as shown in Figure 3-6. Oracle Real Application Clusters Guard will use the base name that you specify to create groups as follows: <base group name>_<node_name>, where node_name is the cluster node on which the instance is running. For example, if you specify a base group name of Test for a database with one instance running on node ntclu-80 and another instance running on node ntclu-81, then Oracle Real Application Clusters Guard will create the groups Test_ntclu-80 and Test-ntclu-81.

Figure 3-6 Configure Database Wizard - Group Page

Text description of the illustration ops_config_wiz_group.gif

3.3.1.5 Instances

The Configure Database Wizard Instances page is informational only. It presents the name of the database you are configuring, the number of instances associated with that database, the names of the instances, and the nodes they are running on, as shown in Figure 3-7.

Figure 3-7 Configure Database Wizard - Instances Page

Text description of the illustration ops_config_wiz_instances.gif

This page also prepares you for the succeeding pages in the wizard. These pages will ask you to specify at least one virtual address per database instance. For example, the information presented in Figure 3-7 indicates that there are 2 database instances, therefore you should be prepared to provide at least two virtual addresses in the succeeding wizard pages. In addition, you will be asked to provide the name of the initialization parameter file for each instance.

3.3.1.6 Virtual Addresses

This page of the wizard will be presented several times, once for each cluster node. This lets you to specify the virtual address or addresses to be included in the group created for each cluster node. The first time it is presented, the Virtual Addresses list box is empty, as shown in Figure 3-8.

Client applications connect to the resources in a group using one of the virtual addresses in the group.

When you add a virtual address to the group, the group is accessible by clients at the same network address, regardless of which cluster node is hosting the group.

Multiple virtual addresses in a group provide flexible configuration options. For example, you might have users access a database instance over the public network while you perform a database backup operation over the private network. Or you might allocate different virtual addresses on different network segments to control security, with administrators accessing the database instance on one segment, while users access the database instance on another segment.

If there are many database users, you might have some users access the database instance using one virtual address and the others use the other virtual address, to balance the network traffic.

This page may also request the name of the initialization parameter file for the instance. When an Oracle Real Application Clusters database instance starts up, it uses the initialization parameter file to specify the name of the database, the amount of memory to allocate, the names of control files, and various limits and other system parameters. Typically, this field is prefilled for you.

Oracle Real Application Clusters Guard requires that a text initialization parameter file (PFILE) be specified in the Parameter File field. To use a binary server parameter file (SPFILE) with configured databases, specify the location of the SPFILE from within the PFILE using the SPFILE=<SPFILE-location> parameter. For example, the contents of the PFILE might include the following parameters:

SPFILE=I:\Oracle-Home\admin\oradb9i\pfile\spfileoradb9i.ora
remote_login_password=none

(If you specify an SPFILE in the PFILE that Oracle Real Application Clusters Guard uses, be careful if and when you export the SPFILE. If you use the CREATE PFILE FROM SPFILE command without including file specifications, you will overwrite the PFILE that Oracle Real Application Clusters Guard is using. Therefore, be sure to specify a unique file name for the exported SPFILE. See the Oracle9i Database Administrator's Guide for detailed information on server parameter files.)

Figure 3-8 Configure Database Wizard - Virtual Addresses Page

Text description of the illustration ops_config_wiz_va1.gif

Click New to open the Create Virtual Address dialog box, as shown in Figure 3-9. In this figure, the user has entered a virtual address of ntclu-83. The wizard will present the Virtual Address page several times, until you have specified at least one virtual address for each Oracle Real Application Clusters database instance.

3.3.1.7 Create Virtual Address Dialog Box

The Create Virtual Address dialog box requests information about the network on which the virtual address will run, its host name, and IP address, as shown in Figure 3-9. When you select the "Show networks accessible by clients" option, the Network box provides a drop-down list of networks that are available to clients who will be accessing the database instance from a noncluster node. A public network is appropriate for most applications. When you select the "Show networks private to the cluster" option, the Network box provides a drop-down list of networks that are available only across the private interconnect. A private network is typically used in special cases where the database is accessed only from an application on another node in the cluster.

Figure 3-9 Create Virtual Address Dialog Box

Text description of the illustration ops_config_wiz_vac.gif

3.3.1.8 Finish Configuring the Database

When you have stepped through all the wizard pages and clicked Finish, you are presented with the Finish Configuring the Database dialog box. It presents a summary of all the choices you selected in the wizard, as shown in Figure 3-10. If you need to make changes, click Cancel, and then click Back to make corrections. If no changes are needed, click OK, and Oracle Real Application Clusters Guard will configure the database to work in the cluster.

Figure 3-10 Finish Configuring the Database

Text description of the illustration finish_configure.gif

3.3.1.9 Configuring Real Application Clusters Database

After you click OK, Oracle Real Application Clusters Guard opens a window to display the progress of the configure database operation, as shown in Figure 3-11.

Figure 3-11 Configuring Real Application Clusters Database Window

Text description of the illustration config_lro.gif

3.4 Configuring Additional Database Instances

If you add a new node to an existing cluster, you will probably want to configure an additional database instance for that new node. (Instructions for installing the software to add a new node to an existing cluster are described in the Oracle Real Application Clusters Guard Installation Guide.)

If you add a database instance to an Oracle Real Application Clusters database after the database has been configured into the MSCS cluster, you can add the instance to the Oracle Real Application Clusters Guard configuration without unconfiguring the database. To configure additional instances, in Oracle Real Application Clusters Guard Manager, select the database to which you want to add an instance from the tree view, then from the Real Application Clusters menu, choose the Configure Additional Instances option. Oracle Real Application Clusters Guard Manager opens the Configure Additional Instances Wizard, as shown in Figure 3-12. The Configure Additional Instances Wizard uses a subset of pages from the Configure Database Wizard for you specify one or more virtual address for the instance you are adding to the configuration.

Figure 3-12 Configure Instances Wizard

Text description of the illustration configure_instance.gif

3.5 Unconfiguring Oracle Real Application Clusters Database Instances

If, for some reason, you decide that you no longer want one or all Oracle Real Application Clusters database instances configured into the MSCS cluster, you can perform an unconfigure operation. To specify an unconfigure operation, in Oracle Real Application Clusters Guard Manager, from the Real Application Clusters menu, choose the Unconfigure option. Oracle Real Application Clusters Guard Manager opens the Unconfigure Database dialog box, as shown in Figure 3-13.

Figure 3-13 Unconfigure Database Dialog Box

Text description of the illustration unconfigure.gif

By default, all instances will be included in the unconfigure operation. If you want to unconfigure the entire Oracle Real Application Clusters database, click OK. Otherwise, if you want to unconfigure selected instances only, remove the instances that you do want to remain configured from the "Unconfigure these instances" box. (To remove an instance, select it and click the left arrow to move it to the "Available instances" box.) When the "Unconfigure these instances" box contains only the instances that you want to unconfigure, click OK.

3.6 User-Specified Script for Database Instance State Change Events

After you configure an Oracle Real Application Clusters database into an MSCS cluster, you can use the Script property page, as show in Figure 3-14, to specify that a script you have written be executed if a database instance changes state. You might specify a script to perform actions that Oracle Real Application Clusters Guard or Oracle Real Application Clusters cannot perform automatically. For example, you might create a script to handle errors that are returned during online or offline operations, to page a DBA when an instance fails, or to notify applications when an instance has come online.

Note that the Script property page might not be immediately apparent. When you select an Oracle Real Application Clusters database from the tree view, click the right arrow next to the property sheet tabs to view the Script tab.

Figure 3-14 Script Property Page

Text description of the illustration script.gif

If you specify a script, Oracle Real Application Clusters Guard uses it for all instances of a given Oracle Real Application Clusters database. You must place an identical copy of the script on the local drive of each cluster node. You can specify a script timeout, which by default, is 180 seconds. The script timeout is the amount of time Oracle Real Application Clusters Guard will allow the script to run before terminating it. The minimum script timeout value is 1 second; the maximum is 600 seconds.

Oracle Real Application Clusters Guard allows the script to run for the script timeout period. If the script is still running at the end of the script timeout period, Oracle Real Application Clusters Guard considers the script to be hung and terminates it.

If the work your script performs requires more than the maximum script timeout period (600 seconds), consider putting the work into a program that is called asynchronously from within your script and setting the script timeout period to the maximum. However, when you use a called program from within your script, be aware of the following:

• If the script is still running at the end of the script timeout period, Oracle Real Application Clusters Guard will terminate it. However, Oracle Real Application Clusters Guard has no control over the called program. If the called program becomes hung, Oracle Real Application Clusters Guard will not detect that it is hung, nor terminate it.

• Oracle Real Application Cluster Guard resumes monitoring the database instances and may change the state of one or more instances as part of its normal operations. This can be a problem if your called program is still running and Oracle Real Application Clusters Guard changes the state of an instance on which your called program is performing work.

An Oracle Real Application Clusters database instance resource executes the script using the following command line:

Script-name.ext [InstName][Node] [Role] [Status] [Date] [OracleErrorCode]

The command parameters are as follows:

• Script-name.ext

  The name you have given to the script.

• InstName

  The name of the instance, as it appears in the Oracle Real Application Clusters Guard Manager tree view.

• Node

  The name of the node from which the script will be run.

• Role

  The role of the instance. This can be unknown, primary, or secondary.

• Status

  The current status of the instance. Table 3-1 summarizes the possible status values and whether or not Oracle Real Application Clusters Guard operations will be suspended while the script is running.

• Date

  The date on which the script is being run. The date is represented in the format yyyy/mm/dd-hh:mm:ss; where yyyy is the year, mm is the month, dd is the day, hh is the hour (based on a 24-hour clock), mm is the minute, and ss is the second.

• OracleErrorCode

  The Oracle error code returned while an instance was being placed online or taken offline. This parameter is specified only if the status is error_up or error_down.

Table 3-2 summarizes the events that trigger script execution (when script execution is enabled).

For example, suppose you create a script called myscript.bat and on February 16, 2001 at 11:30 you issue an Oracle Real Application Clusters Guard Manager Take Offline command for an instance called clusterdb1 that has the primary role and whose preferred owner node is node-1. The Oracle Real Application Clusters database instance resource will issue the following command after you issue the Take Offline command, but before any instructions are executed to take the instance offline:

myscript.bat clusterdb1 node-1 primary planned_down 2001/02/16-11:30:00 

The portions of your script that will be run are those you have written for the planned_down, down, and cleanup status values.

Note that you specify one script for all instances of an Oracle Real Application Clusters database; within the script you can specify actions to be taken for each status value that can be passed to the script. You can specify actions for any, all, or none of the status values. If you do not want to specify actions for any of the status values, select the "Do not execute a script" option when you configure the Oracle Real Application Clusters database. Similarly, if you specified a script during configuration and later decide you do not want it to be run, in the Script property page for the configured Oracle Real Application Clusters database, select the "Do not execute a script" option.

If you specify a script, the Oracle Real Application Clusters database instance resource executes the script in its own separate process. The script is run every time there is a change in an instance's status, for each status value passed to the script. For example, suppose Oracle Real Application Clusters Guard attempts to restart an instance twice, and then succeeds on the third attempt. (There are two failures and one success.) The script will be run 10 times: three times for planned_up (when Oracle Real Application Clusters Guard attempts to place the instance online), two times for error_up (when an error occurs during the attempt to place the instance online), two times each for down and cleanup (when the attempts to bring the instance online fails), and once for up (when the attempt to bring the instance online succeeds).

When a script is run, the command line and return code (to indicate failure, success, or exceeded timeout value) are written to the Windows Event log.

Table 3-1  Status Values for User-Specified Database Instance Event Scripts

Status Value	Suspend Operations?	Status Value Meaning
planned_up	Yes	The instance is about to be brought online.
up	No	The instance has been successfully placed online.
error_up	Yes	An error occurred while the instance was coming online.
planned_down	Yes	The instance is about to be taken offline in response to a DBA issuing a Take Resource Offline command through Oracle Real Application Clusters Guard Manager.
down	Yes	The instance is about to be taken offline in response to a DBA request or automatically by Oracle Real Application Clusters Guard. When the instance is being taken offline in response to a DBA request, the script will first be executed with the planned_down status and then executed again with the down status.
cleanup	No	The instance has been taken offline successfully.
error_down	Yes	An error occurred while the instance was being taken offline.
hang_detected_fail	Yes	The instance is about to be taken offline because Oracle Real Application Clusters Guard has determined that it is hung.
hang_detected_nofail	No	The instance is hung, but the Oracle Real Application Clusters Guard monitor has determined that it will not be taken offline.
hang_resolved	No	A previously hung instance is now running, as determined by Is Alive polling.

Table 3-2 displays events that cause a script to be run and the status value for which the script will be run. When multiple status values are listed, Oracle Real Application Clusters Guard will execute the script multiple times; once for each status value, in the order in which the status values are listed in the table. References to a primary or secondary instance refer to the role that the instance held just prior to the event occurring. (Note that configuring an Oracle Real Application Clusters database does not trigger script execution.)

Table 3-2  Events That Trigger Script Execution and Status Values

Event	Status Values Passed to Script
Unconfigure an Oracle Real Application Clusters database.	On each instance's preferred owner node: down, cleanup
Place an instance online using Oracle Real Application Clusters Guard Manager.	On preferred owner node: planned_up, up
Place an instance online using MSCS Cluster Administrator.	On preferred owner node: planned_up, up
Error occurs placing an instance online.	On preferred owner node: planned_up, error_up
Take an instance offline using Oracle Real Application Clusters Guard Manager.	On preferred owner node: planned_down, down, cleanup
Take an instance offline using MSCS Cluster Administrator.	On preferred owner node: down, cleanup
Error occurs taking an instance offline.	On preferred owner node: planned_down, down, error_down if instance is taken offline through Oracle Real Application Clusters Guard Manager On preferred owner node: down, error_down if instance is taken offline through MSCS Cluster Administrator
Move Primary.	On preferred owner node for primary instance: planned_down, down, cleanup
Stop Secondary.	On preferred owner node for secondary instance: planned_down, down, cleanup
Switchover.	On preferred owner node for primary instance: down, cleanup, planned_up, up On preferred owner node for secondary instance: planned_down, down, cleanup, planned_up, up
Restore.	On preferred owner node for secondary instance: planned up, up
Move an instance group from the preferred owner node to a non-preferred owner node.	On preferred owner node: planned_down, down, cleanup On non-preferred owner node: planned_up, error_up
Move an instance group from non-preferred owner node to preferred owner node.	On non-preferred owner node: down, cleanup On preferred owner node: planned_up, up
An instance fails.	On preferred owner node: down, cleanup
A node fails.	On non-preferred owner node: planned_up, error_up
A failed node comes back online.	On non-preferred owner node: down, cleanup On preferred owner node: planned_up, up
Oracle Real Applications Cluster Guard is about to terminate an instance that it has detected is hung.	hang_detected_fail
Oracle Real Applications Cluster Guard has detected that an instance is hung, but will not terminate it.	hang_detected_nofail
Oracle Real Applications Cluster Guard has determined that a previously hung instance is no longer hanging.	hang_resolved

3.7 Network Configuration for Configured Databases

For a connection between a client and a database instance to be made, the network address in the tnsnames.ora file on the client and the network address in the listener.ora file on the server must match. In other words, a client uses a network address to send a connection request to a particular network object location, and the recipient listens for requests on this address and grants a connection based on its address information matching its client information.

When you configure an Oracle Real Application Clusters Guard database, Oracle Real Application Clusters Guard creates a listener for each group in the same Oracle home where each instance resides. When Oracle Real Application Clusters Guard configures the virtual address information, it updates the tnsnames.ora files in all Oracle homes on all cluster nodes and on the client system from which you were running Oracle Real Application Clusters Guard Manager when you configured the database. This allows Oracle Real Application Clusters Guard to access the database instance using the updated configuration.

The following sections describe how Oracle Real Application Clusters Guard creates an entry in the listener.ora file and updates the tnsnames.ora file after a database is configured in the cluster. The host name of the node where unconfigured database instances were running is replaced with the virtual server address of the groups containing the database instances. This ensures that clients can connect to a database instance, regardless of which cluster node is hosting each database instance group.

Note: Oracle Real Application Clusters Guard does not support the use of the TNS_ADMIN Windows environment variable or registry parameter. Oracle Real Application Clusters Guard retrieves and updates Oracle Net files in the <Oracle_Home>\network\admin directory; it ignores the TNS_ADMIN Windows environment variable or registry parameter if either is specified.

3.7.1 The tnsnames.ora File

Oracle Real Application Clusters Guard updates the net service name in the tnsnames.ora file for each database instance to use the virtual addresses of its group. Oracle Real Application Clusters Guard updates the tnsnames.ora files on all cluster nodes (that are possible owners for the database) and on the client node where you are running Oracle Real Application Clusters Guard Manager.

If you need to enable additional remote clients to process work against Oracle Real Application Clusters database instances, you must edit the tnsnames.ora files to update the host name with the virtual address information. Edit each additional client's local tnsnames.ora file using a network configuration tool, such as Oracle Net Configuration Assistant. An annotated version of the tnsnames.ora file that explains each entry that Oracle Real Application Clusters Guard updates is available on the server nodes in the following directory, where <Oracle_Home> is the home of the Oracle Real Application Clusters database and <db-name> is the name of the database:

<Oracle_Home>\network\ADMIN\tnsnames_<db-name>_reference.ora

Suppose an Oracle Real Application Clusters database named crm has not yet been configured in the cluster. Instance crm1 is running on node ntclu-80 (as shown in Figure 3-15) and instance crm2 is running on node ntclu-81.

The following code segment shows an entry in the tnsnames.ora file for the Oracle Real Application Clusters database. In this example, instance crm1 is on node ntclu-80 and instance crm2 is on node ntclu-81:

crm.us.oracle.com =
  (DESCRIPTION=
    (LOAD_BALANCE=ON)
    (ADDRESS_LIST=
      (ADDRESS=
        (PROTOCOL=TCP)
        (HOST=138.2.26.80)
        (PORT=1521)
      )
      (ADDRESS=
        (PROTOCOL=TCP)
        (HOST=138.2.26.81)
        (PORT=1521)
      )
    )
    (CONNECT_DATA=
      (SERVICE_NAME=crm.us.oracle.com)
    )

Figure 3-15 Unconfigured Oracle Real Application Clusters Database Instance

Text description of the illustration ops_unconf_tnsnames.gif

The next code segment shows the same entry in the tnsnames.ora file after the Oracle Real Application Clusters database has been configured into an MSCS cluster with virtual addresses ntclu-83 and ntclu-84 (IP addresses 138.2.26.83 and 138.2.26.84, respectively). Note that the cluster node addresses (ntclu-80 and ntclu-81) have been replaced with the virtual server IP addresses (138.2.26.83 and 138.2.26.84) of each instance group.

crm.us.oracle.com =
  (DESCRIPTION=
    (LOAD_BALANCE=ON)
    (ADDRESS_LIST=
      (ADDRESS=
        (PROTOCOL=TCP)
        (HOST=138.2.26.83)
        (PORT=1521)
      )
      (ADDRESS=
        (PROTOCOL=TCP)
        (HOST=138.2.26.84)
        (PORT=1521)
      )
    )
    (CONNECT_DATA=
      (SERVICE_NAME=crm.us.oracle.com)
    )
  )

Figure 3-16 shows the Oracle Real Application Clusters database after it has been configured into an MSCS cluster.

Figure 3-16 Configured Oracle Real Application Clusters Database Instance

Text description of the illustration ops_conf_tnsnames.gif

3.7.2 The listener.ora File

When you configure an Oracle Real Application Clusters database into an MSCS cluster, Oracle Real Application Clusters Guard creates a new Oracle Net listener for each database instance. Oracle Real Application Clusters Guard configures each listener to listen on the virtual address or addresses associated with its database instance by doing the following:

1. Removing the SID_DESC parameter from the unconfigured database instance listener

2. Creating a new listener that is configured to listen on the virtual address associated with the configured database instance

3. Adding the SID_DESC parameter to the new listener

4. Stopping and restarting the unconfigured database listener to accept the changes that have been made

5. Starting the new listener

For information about adjustments you may need to make to the Oracle Net configuration, see the following topics:

• Configuring Oracle Net on Nodes with Multiple Listeners (Section 3.8.1)

• Using External Procedures with Configured Databases (Section 3.8.2)

• Enabling the Use of Shared Sockets (Section 3.8.3)

3.8 Client Connections to Configured Oracle Real Application Clusters Databases

General information about changes that Oracle Real Application Clusters Guard makes to the tnsnames.ora and listener.ora files is described in Section 3.7. The following sections describe adjustments you need to make to the Oracle Net configuration if any of the following is true:

• There is more than one listener per cluster node.

• You are using external procedures.

• You are using shared servers.

3.8.1 Configuring Oracle Net on Nodes with Multiple Listeners

When Oracle Real Application Clusters Guard searches for an unconfigured Oracle Real Application Clusters database listener, it looks at the listeners defined in all Oracle homes. When multiple Oracle servers are installed (in one or more Oracle homes), it is possible to have more than one listener. Even when there are multiple listeners, Oracle Real Application Clusters Guard can find the listeners for the unconfigured Oracle Real Application Clusters database.

After you install additional Oracle homes on your system, you should decide how many listeners to use and which listeners to use on the system. Then:

1. Remove the definitions of listeners that you do not use from the listener.ora files. This ensures that Oracle Real Application Clusters Guard will not find unnecessary listeners.

2. Make sure that no two listeners listen on the same address of the SID. (An Oracle listener will not start if another active listener is already listening on the same address or SID.)

3. Start the listeners that you will use. Make sure that these listeners are set to start automatically in the Windows Control Panel in the Service Startup.

The state of a listener defined in a listener.ora file affects the result when Oracle Real Application Clusters Guard searches for the listener of an unconfigured database instance. The following list shows the order in which Oracle Real Application Clusters Guard looks for the listeners:

1. Listener is started.

2. Listener is stopped.

3. Listener has no Windows service defined.

For example, suppose you have a database instance with two listeners in two different Oracle homes, and assume that the listener in Home 1 is stopped and the listener in Home 2 is started. When Oracle Real Application Clusters Guard looks through the two homes on the system, it finds the listener in Home 2 because in the first pass, Oracle Real Application Clusters Guard looks only for listeners that are started. As soon as a started listener is found, Oracle Real Application Clusters Guard stops looking. If a started listener is not found, Oracle Real Application Clusters Guard looks through the list for stopped listeners, and so on.

Note: Make sure that the listeners of an unconfigured database instance are in the state (stopped or started) that you intend before you run any Oracle Real Application Clusters Guard operations.

Oracle Real Application Clusters Guard always creates a listener for an instance group in the same Oracle home where the database instance contained in the group resides.

3.8.2 Using External Procedures with Configured Databases

Oracle Real Application Clusters Guard configures the address of an external procedure in the Oracle Net listener definition for an instance group (the listener.ora file). As the first database instance is configured into a group, Oracle Real Application Clusters Guard determines whether or not external procedures are configured in the original Oracle Net listener serving the database instance. If they are configured, Oracle Real Application Clusters Guard creates both an IPC listener address and a SID descriptor (SID_DESC) in the listener.ora file for the instance group.

Oracle Real Application Clusters Guard creates the key of the IPC address by concatenating the prefix "EXTPROC" to the network name of the first virtual address in the group. Oracle Real Application Clusters Guard uses the alphabetic order of the virtual address network names in the group to determine which network name is first. Therefore, if the network name of the first virtual address is ntclu156, then the key value is EXTPROCntclu156 and the IPC address entry will be as follows:

(ADDRESS=
   (PROTOCOL=IPC)
   (KEY=EXTROPROCntclu156)
)

Oracle Real Application Clusters Guard copies the SID descriptor information from the original Oracle Net listener for the database instance to the Oracle Net listener for the instance group. For example, if the original Oracle Net listener for the database instance has the following SID descriptor, then the Oracle Net listener for the instance group will have the same descriptor:

    (SID_DESC=
      (SID_NAME=PLSExtProc)
      (ORACLE_HOME = C:\Oracle\Ora9i)
      (PROGRAM=extproc)
    )

When a PL/SQL or SQL application calls an external procedure, the application specifies the EXTPROC_CONNECTION_DATA net service name in the tnsnames.ora file. This entry contains the information needed by the listener to start a process for the external procedure. The IPC address of the Oracle Net listener in an instance group is added to the EXTPROC_CONNECTION_DATA net service name in all tnsnames.ora files on the cluster.

3.8.3 Enabling the Use of Shared Sockets

You enable the use of shared sockets by setting the Windows registry parameter USE_SHARED_SOCKET to true. When this parameter is set to true, the network listener passes the socket descriptor for client connections to the database thread. As a result, the client does not need to establish a new connection to the database thread and database connection time improves. Also, all database connections share the port number used by the network listener, which can be useful if you are setting up third-party proxy servers.

On Windows NT version 4.0 Service Pack 3 or earlier, enabling this option precluded bringing the network listener up or down in a case where a database connection spawned by the network listener is active. This is not an issue on Windows NT version 4.0 Service Pack 4 or later. Oracle Corporation recommends that you upgrade to Windows NT version 4.0 Service Pack 4 or later if you intend to set this parameter.

This parameter only works in dedicated server mode in a TCP/IP environment. Furthermore, this feature works for Oracle9i listeners and databases only. If you set the USE_SHARED_SOCKET parameter to true in Oracle homes prior to Oracle9i, the following error message is returned when you configure or unconfigure a database:

Oracle shared sockets are enabled for listeners in <home-name> home on node 
<node-name>.  Please disable shared sockets

Note: Oracle Real Application Clusters Guard recognizes the USE_SHARED_SOCKETS registry parameter only; it ignores the USE_SHARED_SOCKETS environment variable.

3.9 Changing the Database Password

If you change the SYS password of a database while it is configured into an MSCS cluster, you must use Oracle Real Application Clusters Guard Manager to change the authentication information of the corresponding database instance resource. Perform the following steps:

1. Change the SYS password for each database instance as described in your database documentation:

   Refer to the Administrator's Guide that is available with the documentation for your Oracle database. Search for information about changing the SYS password.

2. In Oracle Real Application Clusters Guard Manager, select the database from the tree view and click the Authentication tab. Update the password and confirm password fields to match the changes you made for the database instances. (If these fields are read-only, then a password file was not specified when the database was added to a group.)

If Oracle Services for MSCS uses the SYS account to access the database, then when you update the SYS password in Oracle Real Application Clusters Guard Manager, Oracle Real Application Clusters Guard tries to connect to the database to make sure the password works. If an instance is offline at the time that you make the change, the password cannot be verified immediately for that instance; however, it will be verified when the instance comes online.

3.10 Performing Administrative Tasks on a Configured Database Instance

You perform administrative tasks on an Oracle Real Application Clusters database configured into an MSCS cluster as you would for any Oracle Real Application Clusters database, with one exception. You must use Oracle Real Application Clusters Guard or the ORACGCMD command-line interface (see Chapter 5) to take a database instance offline (and stop cluster monitoring of the database instance) during any operation that restricts access to the database instance. This includes not only cold backup operations but also administrative operations that need to be performed while users continue to access the database instance, or operations that could affect response times during the periodic Is Alive polling of the database instance by MSCS.

Use these steps to perform administrative tasks on a database instance that is configured into a cluster:

1. Use Oracle Real Application Clusters Guard or the ORACGCMD command to take the database instance offline, shut down the database, and suspend monitoring of the database by the cluster. All users connected to the database instance will be disconnected.

2. Use a tool such as SQL*Plus to start up the database instance and to perform your administrative tasks. (While the database instance is started, users can access the instance.)

3. Once you have completed the administrative tasks, use a tool such as SQL*Plus to shut down the database instance.

4. Use Oracle Real Application Clusters Guard Manager or the ORACGCMD command to place the database online again. The cluster will resume monitoring the database instance.

3.11 Clients and Cluster-Aware Applications

When you configure an Oracle Real Application Clusters database into an MSCS cluster, you ensure a high level of server-side availability. You can also ensure a high level of client-side availability by implementing transparent application failover (TAF). When an application is configured to use transparent application failover, it is said to be a cluster-aware application.

You can make an instance failure transparent to the applications by designing them to automatically reconnect to the virtual address associated with the database instance. Cluster-aware applications handle all details associated with reconnecting to the virtual address and replaying any transactions that might have been lost when the failure occurred. To build a complete high-availability solution in your Oracle Real Application Clusters Guard environment, you should make your applications cluster-aware by implementing automatic application reconnection.

This section describes how to make ODBC and OCI applications cluster-aware to minimize the effect of database instance failure to users.

If an application is cluster-aware, it can automatically do the following:

• Connect to another active instance when a failure is detected

• Redo uncommitted transactions

• Reexecute SQL SELECT statements that were interrupted, retrieving the same number of rows as were fetched prior to the failure

• Check the state of transactions that were committed from the client, but for which no acknowledgment was received from the server

Once a database connection is reestablished, applications continue to work as though a failure never occurred; users probably will be unaware of the failure.

Applications that are not cluster-aware cannot recover automatically. Thus, when a failure occurs, it requires that the users manually do the following:

• Reconnect to another instance at the same virtual server address

• Resubmit any transactions that were rolled back

• Perform other necessary recovery operations

Application reconnection does not happen by default. You need to modify your applications to handle errors automatically and transparently with the goal of surviving the failure of an instance without losing the client session.

OCI applications (configured with Oracle Net) are designed to retain the client state. That is, they keep a set of prepared cursors and remember in-process SQL SELECT statements to expedite reconnection upon database recovery.

An application written using Oracle OCI can reconnect automatically without having to specifically recognize that it has lost the database connection. This capability is provided by the Oracle OCI transparent application failover feature. Any native OCI application (such as SQL*Plus) and any application built with an interface that layers on the OCI libraries (such as the Oracle ODBC driver, Oracle Objects for OLE, and Thick JDBC) can take advantage of transparent application failover with no application code changes required.

To take advantage of transparent application failover when connected to a database configured with Oracle Real Application Clusters Guard, the client applications must connect through Oracle Net to the database.

For information on configuring transparent application failover, see the Oracle9i Net Services Administrator's Guide and the Oracle9i Real Application Clusters Concepts manual.