4.2 Configuring Oracle Restart

«« Previous
Next »»

To configure Oracle Restart, you can add components, remove components, or modify options for components.
  • About Configuring Oracle Restart
If you install Oracle Restart by installing the Oracle Grid Infrastructure for a standalone server and then create your database, the database is automatically added to the Oracle Restart configuration, and is then automatically restarted when required. However, if you install Oracle Restart on a host computer on which a database already exists, you must manually add the database, the listener, the Oracle Automatic Storage Management (Oracle ASM) instance, and possibly other components to the Oracle Restart configuration.

After configuring Oracle Restart to manage your database, you may want to:

➨ Add additional components to the Oracle Restart configuration.
➨ Remove components from the Oracle Restart configuration.
➨ Temporarily suspend Oracle Restart management for one or more components.
➨ Modify the Oracle Restart configuration options for an individual component.
  • Preparing to Run SRVCTL
Many Oracle Restart tasks require that you run the SRVCTL utility. You must ensure that you run SRVCTL from the correct Oracle home, and that you log in to the host computer with the correct user account.

Table 4-6 lists the components that you can configure with SRVCTL, and for each component, lists the Oracle home from which you must run SRVCTL.

Component Being Configured Oracle Home from which to Start SRVCTL
Database, database service Database home
Oracle ASM instance, disk group, listenerFoot 3, ONS Oracle Grid Infrastructure home
Assumes the listener was started from the Oracle Grid Infrastructure home. If you installed Oracle Restart for an existing database, the listener may have been started from the database home, in which case you start SRVCTL from the database home.

To prepare to run SRVCTL:

1. Use to determine the Oracle home from which you must run SRVCTL.

2. If you intend to run a SRVCTL command that modifies the Oracle Restart configuration (add, remove, enable, disable, and so on), then do one of the following:

- On UNIX and Linux, log in to the database host computer as the user who installed the Oracle home that you determined in Step 1.
- On Windows, log in to the database host computer as an Administrator.

Otherwise, log in to the host computer as any user.

3. Open the command window that you will use to enter the SRVCTL commands.
To enter commands, you might need to ensure that the SRVCTL program is in your PATH environment variable. Otherwise, you can enter the absolute path to the program.
  • Obtaining Help for SRVCTL
Online help is available for the SRVCTL utility.

1. Prepare to run SRVCTL as described in "Preparing to Run SRVCTL".

2. Enter the following command:

srvctl

For more detailed help, enter the following command:

srvctl -help

For detailed help on a particular command, enter:

srvctl command -help

For example, to obtain help for the add command and the different options for each component type, enter:

srvctl add -help

For detailed help on a particular command for a particular component type, enter:

srvctl command object -help

For example, to obtain help about adding a database service, enter the following command:

srvctl add service -help

Starting with Oracle Database 12c, single-letter parameters are deprecated in favor of keyword parameters. To support backward compatibility, you can use a mix of single-letter parameters and new keyword parameters. The help shows the keyword parameters by default, but you can obtain the single-letter equivalents, where applicable, by adding the -compatible parameter after the -help parameter.

For example, to obtain help about adding a database service that includes the single-letter equivalents, enter the following command:

srvctl add service -help -compatible

The single-letter equivalents appear in parentheses next to the keyword parameters. Parameters that are new in Oracle Database 12c do not have single-letter equivalents.
  • Adding Components to the Oracle Restart Configuration
In most cases, creating an Oracle component on a host that is running Oracle Restart automatically adds the component to the Oracle Restart configuration. However, in some cases, you must add components manually.

The component is then automatically restarted when required.

The following are occasions when you must manually add components to the Oracle Restart configuration with SRVCTL:

- You install Oracle Restart after creating the database.
- You create an additional Oracle database on the same host computer using the CREATE DATABASE SQL statement.
- You create a database service with DBMS_SERVICE.CREATE_SERVICE package procedure. (The recommended way is to use SRVCTL.)

Note: Adding a component to the Oracle Restart configuration is also referred to as "registering a component with Oracle Restart."

Adding a component to the Oracle Restart configuration does not start that component. You must use a srvctl start command to start it.

When you add a component to the Oracle Restart configuration with SRVCTL, you can specify optional configuration settings for the component.

To add a component to the Oracle Restart configuration with SRVCTL:

1. Prepare to run SRVCTL as described in "Preparing to Run SRVCTL".

2. Enter the following command:

srvctl add object options

where object is one of the components listed in Table 4-7. See the SRVCTL add command for available options for each component.

Example 4-1 Adding a Database

This example adds a database with a DB_UNIQUE_NAME of dbcrm. The mandatory -oraclehome option specifies the Oracle home location.

srvctl add database -db dbcrm -oraclehome /u01/app/oracle/product/12.1.0/dbhome_1

Example 4-2 Adding a Database Service

For the database with the DB_UNIQUE_NAME of dbcrm, this example both creates a new database service named crmbatch and adds it to the Oracle Restart configuration.

srvctl add service -db dbcrm -service crmbatch

Example 4-3 Adding the Default Listener

This example adds the default listener to the Oracle Restart configuration.

srvctl add listener

Note:
When you manually add a database to the Oracle Restart configuration, you must also add the Oracle grid infrastructure software owner as a member of the OSDBA group of that database. This is because the grid infrastructure components must be able to connect to the database as SYSDBA to start and stop the database.

For example, if the host user who installed the grid infrastructure home is named grid and the OSDBA group of the new database is named dba, then user grid must be a member of the dba group.
  • Removing Components from the Oracle Restart Configuration
When you use an Oracle-recommended method to delete an Oracle component, the component is also automatically removed from the Oracle Restart configuration.

For example, if you use Database Configuration Assistant (DBCA) to delete a database, DBCA removes the database from the Oracle Restart configuration. Likewise, if you use Oracle Net Configuration Assistant (NETCA) to delete a listener, NETCA removes the listener from the Oracle Restart configuration. If you use a non-recommended or manual method to delete an Oracle component, you must first use SRVCTL to remove the component from the Oracle Restart configuration. Failing to do so could result in an error.

To remove a component from the Oracle Restart configuration:

1. Prepare to run SRVCTL as described in "Preparing to Run SRVCTL".

2. Enter the following command:

srvctl remove object [options]

Example 4-4 Removing a Database

This example removes a database with a DB_UNIQUE_NAME of dbcrm.

srvctl remove database -db dbcrm
  • Disabling and Enabling Oracle Restart Management for a Component
You can temporarily disable Oracle Restart management for a component. One reason to do this is when you are performing maintenance on the component. For example, if a component must be repaired, then you might not want it to be automatically restarted if it fails or if the host computer is restarted. When maintenance is complete, you can reenable management for the component.

When you disable a component:

- It is no longer automatically restarted.
- It is no longer automatically started through a dependency.
- It cannot be started with SRVCTL.
- Any component dependent on this resource is no longer automatically started or restarted.

To disable or enable automatic restart for a component:

1. Prepare to run SRVCTL, as described in "Preparing to Run SRVCTL".

2. Do one of the following:

To disable a component, enter the following command:

srvctl disable object [options]

To enable a component, enter the following command:

srvctl enable object [options]

Example 4-5 Disabling Automatic Restart for a Database

This example disables automatic restart for a database with a DB_UNIQUE_NAME of dbcrm.

srvctl disable database -db dbcrm

Example 4-6 Disabling Automatic Restart for an Oracle ASM Disk Group

This example disables automatic restart for the Oracle ASM disk group named recovery.

srvctl disable diskgroup -diskgroup recovery

Example 4-7 Enabling Automatic Restart for an Oracle ASM Disk Group

This example reenables automatic restart for the disk group recovery.

srvctl enable diskgroup -diskgroup recovery
  • Viewing Component Status
You can use SRVCTL to view the running status (running or not running) for any component managed by Oracle Restart. For some components, additional information is also displayed.

To view component status:

1. Prepare to run SRVCTL as described in "Preparing to Run SRVCTL".

2. Enter the following command:
srvctl status object [options]

Example 4-8 Viewing Status of a Database

This example displays the status of the database with a DB_UNIQUE_NAME of dbcrm.

srvctl status database -db dbcrm
Database is running.
  • Viewing the Oracle Restart Configuration for a Component
You can use SRVCTL to view the Oracle Restart configuration for any component. Oracle Restart maintains different configuration information for each component type. In one form of the SRVCTL command, you can obtain a list of components managed by Oracle Restart.

To view component configuration:

1. Prepare to run SRVCTL as described in "Preparing to Run SRVCTL".

2. Enter the following command:
srvctl config object options

Example 4-9 Viewing a List of All Databases Managed by Oracle Restart

srvctl config database

dbcrm
orcl

Example 4-10 Viewing the Configuration of a Particular Database

This example displays the configuration of the database with a DB_UNIQUE_NAME of orcl.

srvctl config database -db orcl

Database unique name: orcl
Database name: orcl
Oracle home: /u01/app/oracle/product/12.1.0/dbhome_1
Oracle user: oracle
Spfile: +DATA/orcl/spfileorcl.ora
Domain: us.example.com
Start options: open
Stop options: immediate
Database role:
Management policy: automatic
Disk Groups: DATA
Services: mfg,sales
  • Modifying the Oracle Restart Configuration for a Component
You can use SRVCTL to modify the Oracle Restart configuration of a component. For example, you can modify the port number that a listener listens on when Oracle Restart starts it, or the server parameter file (SPFILE) that Oracle Restart points to when it starts a database.

To modify the Oracle Restart configuration for a component:

1. Prepare to run SRVCTL as described in "Preparing to Run SRVCTL".

2. Enter the following command:

srvctl modify object options

where object is one of the components listed in Table 4-7. See the SRVCTL modify command for available options for each component.

Example 4-11 Modifying the Oracle Restart Configuration for a Database

For the database with a DB_UNIQUE_NAME of dbcrm, the following command changes the management policy to MANUAL and the start option to NOMOUNT.

srvctl modify database -db dbcrm -policy MANUAL -startoption NOMOUNT

With a MANUAL management policy, the database is never automatically started when the database host computer is restarted. However, Oracle Restart continues to monitor the database and restarts it if a failure occurs.
  • Managing Environment Variables in the Oracle Restart Configuration
The Oracle Restart configuration can store name/value pairs for environment variables.

➨ About Environment Variables in the Oracle Restart Configuration

You can set environment variable values in the Oracle Restart configuration.

If you typically set environment variables (other than ORACLE_HOME and ORACLE_SID) before starting your Oracle database, then you can set these environment variable values in the Oracle Restart configuration. You can store any number environment variables in the individual configurations of the following components:

1. Database instance
2. Listener
3. Oracle ASM instance

When Oracle Restart starts one of these components, it first sets environment variables for that component to the values stored in the component configuration. Although you can set environment variables that are used by Oracle components in this manner, this capability is primarily intended for operating system environment variables.

Note:
Do not use this facility to set standard environment variables like ORACLE_HOME and ORACLE_SID; these are set automatically by Oracle Restart.

➨ Setting and Unsetting Environment Variables

You use SRVCTL to set and unset environment variable values in the Oracle Restart configuration for a component.

To set or unset environment variables in the configuration:

1. Prepare to run SRVCTL as described in "Preparing to Run SRVCTL".
2. Do one of the following:

To set an environment variable in the configuration, enter the following command:

srvctl setenv {asm|database|listener} options

To remove an environment variable from the configuration, enter the following command:

srvctl unsetenv {asm|database|listener} options

Example 4-12 Setting Database Environment Variables

This example sets the NLS_LANG and the AIX AIXTHREAD_SCOPE environment variables in the Oracle Restart configuration for the database with a DB_UNIQUE_NAME of dbcrm:

srvctl setenv database -db dbcrm -envs "NLS_LANG=AMERICAN_AMERICA.AL32UTF8, 
   AIXTHREAD_SCOPE=S"

➨ Viewing Environment Variables

You use SRVCTL to view the values of environment variables in the Oracle Restart configuration for a component.

To view environment variable values in the configuration:

1. Prepare to run SRVCTL as described in "Preparing to Run SRVCTL".
2. Enter the following command:
srvctl getenv {database|listener|asm} options

Example 4-13 Viewing All Environment Variables for a Database

This example gets and displays the environment variables in the Oracle Restart configuration for the database with a DB_UNIQUE_NAME of dbcrm:

srvctl getenv database -db dbcrm

dbcrm:
NLS_LANG=AMERICAN_AMERICA
AIXTHREAD_SCOPE=S
GCONF_LOCAL_LOCKS=1

Example 4-14 Viewing Specific Environment Variables for a Database

This example gets and displays the NLS_LANG and AIXTHREAD_SCOPE environment variables from the Oracle Restart configuration for the same database:

srvctl getenv database -db dbcrm -envs "NLS_LANG,AIXTHREAD_SCOPE"

dbcrm:
NLS_LANG=AMERICAN_AMERICA
AIXTHREAD_SCOPE=S
  • Creating and Deleting Database Services with SRVCTL
When managing a database with Oracle Restart, Oracle recommends that you use SRVCTL to create and delete database services. When you use SRVCTL to add a database service, the service is automatically added to the Oracle Restart configuration and a dependency between the service and the database is established. Thus, if you start the service, Oracle Restart first starts the database if it is not started.

When you use SRVCTL to delete a database service, the service is also removed from the Oracle Restart configuration.

To create a database service with SRVCTL:

1. Prepare to run SRVCTL as described in "Preparing to Run SRVCTL".

2. Enter the following command:

srvctl add service -db db_unique_name -service service_name [options]

The database service is created and added to the Oracle Restart configuration.

To delete a database service with SRVCTL:

1. Prepare to run SRVCTL as described in "Preparing to Run SRVCTL".

2. Enter the following command:

srvctl remove service -db db_unique_name -service service_name [-force]
The database service is removed from the Oracle Restart configuration. If the -force flag is present, the service is removed even if it is still running. Without this flag, an error occurs if the service is running.

Example 4-15 Creating a Database Service

For the database with the DB_UNIQUE_NAME of dbcrm, this example creates a new database service named crmbatch.

srvctl add service -db dbcrm -service crmbatch

Example 4-16 Creating a Role-Based Database Service

This example creates the crmbatch database service and assigns it the Data Guard role of PHYSICAL_STANDBY. The service is automatically started only if the current role of the dbcrm database is physical standby.

srvctl add service -db dbcrm -service crmbatch -role PHYSICAL_STANDBY
  • Enabling FAN Events in an Oracle Restart Environment
To enable Oracle Restart to publish Fast Application Notification (FAN) events, you must create an Oracle Notification Services (ONS) network that includes the Oracle Restart servers and the integrated clients.

These clients can include Oracle Connection Manager (CMAN), Java Database Connectivity (JDBC), and Universal Connection Pool (UCP) clients. If you are using Oracle Call Interface or ODP.NET clients, then you must enable Oracle Advanced Queuing (AQ) HA notifications for your services. In addition, ONS must be running on the server.

To enable FAN events in an Oracle Restart environment:

1. Prepare to run SRVCTL as described in "Preparing to Run SRVCTL".

2. Add the database to the Oracle Restart Configuration if it is not already managed by Oracle Restart. 

3. Add ONS to the configuration:
srvctl add ons
ONS is disabled when it is added.

4. Enable ONS:
srvctl enable ons

5. Start ONS:
srvctl start ons

6. Add the service to the Oracle Restart Configuration.
For Oracle Call Interface and ODP.NET clients, ensure that the -notification option is set to TRUE to enable the database queue.

7. Enable each client for fast connection failover.
  • Automating the Failover of Connections Between Primary and Standby Databases
In a configuration that uses Oracle Restart and Oracle Data Guard primary and standby databases, the database services fail over automatically from the primary to the standby during either a switchover or failover.

You can use Oracle Notification Services (ONS) to immediately notify clients of the failover of services between the primary and standby databases. The Oracle Data Guard Broker uses Fast Application Notification (FAN) to send notifications to clients when a failover occurs. Integrated Oracle clients automatically failover connections and applications can mask the failure from end-users.

To automate connection failover, you must create an ONS network that includes the Oracle Restart servers and the integrated clients (CMAN, listener, JDBC, and UCP). If you are using Oracle Call Interface or ODP.NET clients, you must enable the Oracle Advanced Queuing queue. The database and the services must be managed by Oracle Restart and the Oracle Data Guard Broker to automate the failover of services.

To automate the failover of services between primary and standby databases:

1. Configure the primary and standby database with the Oracle Data Guard Broker. 

2. Prepare to run SRVCTL as described in "Preparing to Run SRVCTL".

3. Add the primary database to the Oracle Restart configuration on the primary server if it has not been added. Ensure that you specify PRIMARY for the database role. 

4. Add the standby database to the Oracle Restart configuration on the standby server if it has not been added. Ensure that you specify the appropriate standby database role.

5. Enable FAN events on both the primary database server and the standby database server. "Enabling FAN Events in an Oracle Restart Environment".

6. Add the services that clients will use to connect to the databases to the Oracle Restart configuration on the primary database and the standby database. When you add a service, ensure that:

- The -role option is set to the proper role for each service
- The -notification option is set to TRUE if you are using ODP.NET or Oracle Call Interface

7. Enable each client for fast connection failover.
  • Enabling Clients for Fast Connection Failover
Fast Connection Failover provides high availability to Fast Application Notification (FAN) integrated clients, such as clients that use JDBC, OCI, or ODP.NET. If you configure the client to use fast connection failover, then the client automatically subscribes to FAN events and can react to database UP and DOWN events. In response, Oracle Database gives the client a connection to an active instance that provides the requested database service.

➨ About Enabling Clients for Fast Connection Failover

In a configuration with a standby database, after you have added Oracle Notification Services (ONS) to your Oracle Restart configurations and enabled Oracle Advanced Queuing (AQ) HA notifications for your services, you can enable clients for fast connection failover.

The clients receive Fast Application Notification (FAN) events and can relocate connections to the current primary database after an Oracle Data Guard failover.

For databases with no standby database configured, you can still configure the client FAN events. When there is a failure, you can configure the client to retry the connection to the database. Since Oracle Restart will restart the failed database, the client can reconnect when the database restarts. Ensure that you program the appropriate delay and retries on the connection string, as illustrated in the examples in this section.

➨ Enabling Fast Connection Failover for JDBC Clients

Enabling FAN for the Oracle Universal Connection Pool enables Fast Connection Failover (FCF) for the client. Your application can use either thick or thin JDBC clients to use FCF.

To configure the JDBC client, set the FastConnectionFailoverEnabled property before making the first getConnection() request to a data source. When you enable Fast Connection Failover, the failover applies to every connection in the connection cache. If your application explicitly creates a connection cache using the Connection Cache Manager, then you must first set FastConnectionFailoverEnabled.

This section describes how to enable FCF for JDBC with the Universal Connection Pool. For thick JDBC clients, if you enable Fast Connection Failover, do not enable Transparent Application Failover (TAF), either on the client or for the service. Enabling FCF with thin or thick JDBC clients enables the connection pool to receive and react to all FAN events.

To enable Fast Connection Failover for JDBC clients:

1. On a cache enabled DataSource, set the DataSource property FastConnectionFailoverEnabled to true as in the following example to enable FAN for the Oracle JDBC Implicit Connection Cache:
PoolDataSource pds = PoolDataSourceFactory.getPoolDataSource();
pds.setONSConfiguration("nodes=primaryhost:6200,standbyhost:6200");
pds.setFastConnectionFailoverEnabled(true);
pds.setURL("jdbc:oracle:thin:@(DESCRIPTION= 
  (LOAD_BALANCE=on) 
  (ADDRESS=(PROTOCOL=TCP)(HOST=primaryhost)(PORT=1521)) 
  (ADDRESS=(PROTOCOL=TCP)(HOST=standbyhost)(PORT=1521))
  (CONNECT_DATA=(service_name=service_name)))");

......
In this example, primaryhost is the server for the primary database, and standbyhost is the server for the standby database.

Applications must have both ucp.jar and ons.jar in their CLASSPATH.

Note: Use the following system property to enable FAN without making data source changes: -D oracle.jdbc.FastConnectionFailover=true.

2. When you start the application, ensure that the ons.jar file is located on the application CLASSPATH. The ons.jar file is part of the Oracle client installation.

➨ Enabling Fast Connection Failover for Oracle Call Interface Clients.

Oracle Call Interface clients can enable Fast Connection Failover (FCF) by registering to receive notifications about Oracle Restart high availability FAN events and respond when events occur.

This improves the session failover response time in Oracle Call Interface and removes terminated connections from connection and session pools. This feature works on Oracle Call Interface applications, including those that use Transparent Application Failover (TAF), connection pools, or session pools.

First, you must enable a service for high availability events to automatically populate the Advanced Queuing ALERT_QUEUE. If your application is using TAF, then enable the TAF settings for the service. Configure client applications to connect to an Oracle Restart database. Clients can register callbacks that are used whenever an event occurs. This reduces the time that it takes to detect a connection failure.

During DOWN event processing, Oracle Call Interface:

- Terminates affected connections at the client and returns an error
- Removes connections from the Oracle Call Interface connection pool and the Oracle Call Interface session pool
The session pool maps each session to a physical connection in the connection pool, and there can be multiple sessions for each connection.
- Fails over the connection if you have configured TAF

If TAF is not configured, then the client only receives an error.

Note: Oracle Call Interface does not manage UP events.

To Enable Fast Connection Failover for an Oracle Call Interface client:

1. Ensure that the service that you are using has Advanced Queuing notifications enabled by setting the services' values using the SRVCTL modify command. For example:
srvctl modify service -db proddb -service gl.us.example.com -notification 
true -role primary -failovertype select -failovermethod basic -failoverretry 5 
-failoverdelay 180 -clbgoal long

2. Enable OCI_EVENTS at environment creation time on the client as follows:
( OCIEnvCreate(...) )

3. Link client applications with the client thread or operating system library.

4. (Optional) Register a client EVENT callback.

5. Ensure that the client uses an Oracle Net connect descriptor that includes all primary and standby hosts in the ADDRESS_LIST. For example:
gl =
(DESCRIPTION =
 (CONNECT_TIMEOUT=10)(RETRY_COUNT=3)
   (ADDRESS_LIST =
     (ADDRESS = (PROTOCOL = TCP)(HOST = BOSTON1)(PORT = 1521))
     (ADDRESS = (PROTOCOL = TCP)(HOST = CHICAGO1)(PORT = 1521))
     (LOAD_BALANCE = yes)
)
(CONNECT_DATA=
  (SERVICE_NAME=gl.us.example.com)))

➨ Enabling Fast Connection Failover for ODP.NET Clients

Oracle Data Provider for .NET (ODP.NET) connection pools can subscribe to notifications that indicate when services are down. After a DOWN event, Oracle Database cleans up sessions in the connection pool that go to the instance that stops, and ODP.NET proactively disposes connections that are no longer valid.

To enable Fast Connection Failover for ODP.NET clients:

1. Enable Advanced Queuing notifications by using SRVCTL modify service command, as in the following example:
srvctl modify service –db dbname –service gl -notification true -clbgoal long

2. Execute the following for the users that will be connecting by way of the .Net Application, where user_name is the user name:
execute DBMS_AQADM.GRANT_QUEUE_PRIVILEGE('DEQUEUE','SYS.SYS$SERVICE_METRICS', user_name);

3. Enable Fast Connection Failover for ODP.NET connection pools by subscribing to FAN high availability events. Set the HA events connection string attribute to true at connection time. The pooling attribute must be set to true, which is the default. The following example illustrates these settings, where user_name is the name of the user and password is the user password:
// C#
using System;
using Oracle.DataAccess.Client;
class HAEventEnablingSample
{
  static void Main()
  {
    OracleConnection con = new OracleConnection();
    // Open a connection using ConnectionString attributes
    // Also, enable "load balancing"
    con.ConnectionString =
      "User Id=user_name;Password=password;Data Source=oracle;" +
      "Min Pool Size=10;Connection Lifetime=120;Connection Timeout=60;" +
      "HA Events=true;Incr Pool Size=5;Decr Pool Size=2";
    con.Open();
    // Create more connections and perform work against the database here.
    // Dispose OracleConnection object
    con.Dispose();
  }
}

4. Ensure that the client uses an Oracle Net connect descriptor that includes all primary and standby hosts in the ADDRESS_LIST. For example:
gl =
(DESCRIPTION =
 (CONNECT_TIMEOUT=10)(RETRY_COUNT=3)
   (ADDRESS_LIST =
     (ADDRESS = (PROTOCOL = TCP)(HOST = BOSTON1)(PORT = 1521))
     (ADDRESS = (PROTOCOL = TCP)(HOST = CHICAGO1)(PORT = 1521))
     (LOAD_BALANCE = yes)
)
(CONNECT_DATA=
  (SERVICE_NAME=gl.us.example.com)))

«« Previous
Next »»