5 Oracle Application Server Guard asgctl Command-line Reference

This chapter contains reference information describing the asgctl commands. Table 5-1 summarizes all the asgctl commands. Table 5-2 summarizes all the asgctl commands that were deprecated beginning with OracleAS release 10.1.2.0.2. Subsequent sections provide detailed reference information common to many commands and about each command.

Table 5-1 Summary of asgctl Commands

Command	Description
add instance	Adds to the local topology file, the specified instance name and name of the host system on which this instance is installed, and if specified, propagates this updated topology file to all instances in the Disaster Recovery production environment.
asgctl	Invokes the Oracle Application Server Guard client command-line utility asgctl. On UNIX systems, `asgctl.sh` is located in `<ORACLE_HOME>/dsa/bin` and on Windows systems, `asgctl.bat` is located in `<ORACLE_HOME>\dsa\bin`.
clone instance	Copies a single Application Server instance at a production site host to a standby site host.
clone topology	Copies two or more Application Server instances at a production site to the standby site.
connect asg	Connects the Oracle Application Server Guard client to the Oracle Application Server Guard server.
create standby database	Creates the standby database on the remote host system.
disconnect	Disconnects the Oracle Application Server Guard client from the Oracle Application Server Guard server.
discover topology	Discovers by querying Oracle Internet Directory all instances within the topology that share the same Oracle Internet Directory for a production site and generates a topology XML file that describes the topology.
discover topology within farm	Discovers the topology within the farm for a site when Oracle Internet Directory is not available; in this case, Oracle Application Server Guard server uses OPMN to discover the topology within the farm.
dump policies	Directs Oracle Application Server Guard server to write detailed, default policy information to respective XML formatted files for a set of asgctl commands. Each policy file can then be edited and later specified to define the topology's disaster recovery policy to be used with the respective administrative command.
dump topology	Directs the Oracle Application Server Guard server to write detailed information about the topology to the screen or if specified, to a file.
exit	Disconnects the Oracle Application Server Guard client from any existing connections and exits the Oracle Application Server Guard client. This has the same effect as the quit command.
failover	During an unscheduled outage of the production site, the standby site becomes the production site.
help	Displays help information at the command line.
instantiate topology	Creates a topology at the standby site (after verifying that the primary and standby sites are valid for OracleAS Disaster Recovery); also synchronizes the standby site with the primary site so that the primary and standby sites are consistent.
quit	Disconnects the Oracle Application Server Guard client from any existing connections and exits the Oracle Application Server Guard client. This has the same effect as the exit command.
remove instance	Removes from the local topology file, the specified instance name, and if specified, propagates this updated topology file to all instances in the Disaster Recovery production environment.
run	Remotely executes a script or program that resides in any home where Oracle Application Server Guard is installed.
set asg credentials	Sets the credentials used to authenticate the Oracle Application Server Guard client connections to Oracle Application Server Guard servers and connections between Oracle Application Server Guard servers to a specific host.
set echo	Sets command-echoing on or off in an asgctl script.
set new primary database	Identifies the OracleAS Infrastructure database on the standby topology as the new primary OracleAS Infrastructure database.
set noprompt	Sets the noprompt state in an asgctl script in which all interactive prompts are thereafter ignored.
set primary database	Identifies the OracleAS Infrastructure database on the primary topology.
set trace	Enables or disables tracing for the specified trace flag. When tracing for a flag is set to on, the output of the trace is written to the Oracle Application Server Guard log files.
show env	Shows the current environment of the Oracle Application Server Guard server to which the Oracle Application Server Guard clients is connected.
show operation	Shows the current operation.
shutdown	Shuts down the Oracle Application Server Guard server at the operating system command-line prompt on a system on which OPMN is not running. This command is only used with cloning an instance or cloning a topology.
shutdown topology	Shuts down a running topology.
startup	Starts up the Oracle Application Server Guard server at the operating system command-line prompt on a system on which OPMN is not running. This command is only used with cloning an instance or cloning a topology.
startup topology	Starts up a shutdown topology.
stop operation	Stops the specified operation.
switchover topology	During a scheduled outage of the production site, switches the roles of the production site with the standby site so that the standby site now becomes the production site.
sync topology	Synchronizes the standby site with the primary site so that the primary and standby sites are consistent.
verify topology	Verifies that the topology is running and the configuration is valid. If a standby topology is specified, this command compares the primary and standby topologies to verify that they conform to the requirements for OracleAS Disaster Recovery.

Table 5-2 Summary of Deprecated asgctl Commands

Command	Description
dump farm (Deprecated)	Directs the Oracle Application Server Guard server to write detailed information about the farm to the screen or if specified, to a file.
instantiate farm (Deprecated)	Creates a farm at the standby site (after verifying that the primary and standby sites are valid for OracleAS Disaster Recovery; also synchronizes the standby site with the primary site so that the primary and standby sites are consistent.
shutdown farm (Deprecated)	Shuts down a running farm.
startup farm (Deprecated)	Starts up a shutdown farm.
switchover farm (Deprecated)	During a scheduled outage of the production site, switches the roles of the production site with the standby site so that the standby site now becomes the production site.
sync farm (Deprecated)	Synchronizes the standby site with the primary site so that the primary and standby sites are consistent.
verify farm (Deprecated)	Verifies that the farm is running and the configuration is valid. If a standby farm is specified, this command compares the primary and standby farms to verify that they conform to the requirements for OracleAS Disaster Recovery.

5.1 Information Common to Oracle Application Server Guard asgctl Commands

This section describes information that is common to Oracle Application Server Guard asgctl commands.

General Information

All asgctl commands should be run using the physical host names of systems where there is a parameter in which a system host name can be specified.

The Oracle Application Server Guard client must be connected to an Oracle Application Server Guard server when you issue any asgctl command with the exception of startup and shutdown commands.

The Oracle Application Server Guard server will act as the coordinating server for all operations performed on the systems being configured. By default, this is the local system where the connect asg command is being executed. This system must be a member of the production site topology.

Oracle Application Server Guard Server Information

The Oracle Application Server Guard server must be started on the standby host system (<standby_topology_host>. The Oracle Application Server Guard server can be stopped and started using the opmnctl command-line Utility as follows:

For 10.1.2.x and 10.1.4.x releases, these commands start and stop OracleAS Guard on UNIX:
<ORACLE_HOME>/opmn/bin/opmnctl  startproc  ias-component=DSA
<ORACLE_HOME>/opmn/bin/opmnctl  stopproc  ias-component=DSA

For 10.1.3.x releases, these commands start and stop OracleAS Guard on UNIX:
<ORACLE_HOME>/opmn/bin/opmnctl  startproc  ias-component=ASG
<ORACLE_HOME>/opmn/bin/opmnctl  stopproc  ias-component=ASG

For 10.1.2.x and 10.1.4.x releases, these commands start and stop OracleAS Guard on Windows:
<ORACLE_HOME>\opmn\bin\opmnctl  startproc  ias-component=DSA
<ORACLE_HOME>\opmn\bin\opmnctl  stopproc  ias-component=DSA

For 10.1.3.x releases, these commands start and stop OracleAS Guard on Windows:
<ORACLE_HOME>\opmn\bin\opmnctl  startproc  ias-component=ASG
<ORACLE_HOME>\opmn\bin\opmnctl  stopproc  ias-component=ASG

5.2 Information Specific to a Small Set of Oracle Application Server Guard Commands

This section describes information that is specific to a small set of Oracle Application Server Guard operations, such as instantiate, sync, failover, switchover, dump topology, discover topology, clone topology, verify topology, setting the primary database, and setting asg credentials.

Before performing any Oracle Application Server Guard operations, you must shut down the emagents. This operation is required for Oracle Application Server Guard commands that recycle OracleAS services, such as failover and switchover operations. You can issue the asgctl run command in a script to perform this operation from within Oracle Application Server Guard. Otherwise, for example you may get an "ORA-01093: ALTER DATABASE CLOSE only permitted with no sessions connected" error message. Shutting down emagents is only described for performing a switchover operation. However, it applies to all Oracle Application Server Guard operations as previously described.

Oracle Application Server Guard requires that you set the credentials for any Oracle Application Server Guard server system in the topology that has different credentials from the Oracle Application Server Guard server to which you are connected before performing any important Oracle Application Server Guard operations, such as instantiate, sync, switchover, and failover. See set asg credentials for an example.

You must perform a discover topology command when you first set up your OracleAS Disaster Recovery environment in order to initially create the topology XML file; there after, you should perform a discover topology operation whenever you procure another Oracle home in a production site or change roles from a production to a standby site through a switchover or failover operation.

Oracle Application Server Guard Administrators must give a delay of about a minute before performing the next asgctl sync topology, switchover topology, or instantiate topology operation. This is especially important when performing incremental sync topology operations. This is a known limitation intended to keep sequences of underlying events as orderly as possible.

The following information and scenarios will help to clarify the usage of topology files.

For OracleAS release 10.1.2 and earlier, use the discover topology command. If Oracle Internet Directory is not in the topology, then use the discover topology within farm command.
For OracleAS releases 10.1.2 and 10.1.3, connect to the Oracle Application Server Guard 10.1.2 server (from either an OracleAS 10.1.2 or 10.1.3 home) and perform a discover topology command. Oracle Application Server Guard will write a topology.xml file to each OracleAS home in the discovered topology. Next, if you want to add an instance (add instance command), then you must perform this operation from the OracleAS 10.1.3 home and connect to any OracleAS 10.1.2 system in the existing topology and perform the add instance command.
For OracleAS release 10.1.3, connect to an Oracle Application Server Guard 10.1.3 server and add that instance to the topology (which does not yet exist). Then, add any additional instances using the same Oracle Application Server Guard connection.

An important point to emphasize in these last two scenarios is that if the topology.xml file does not exist in the OracleAS home of the instance you are adding to the topology, Oracle Application Server Guard creates a new topology.xml file, which essentially defines a new topology.

If you want to use a policy file, edit the contents of the XML policy file to define by instance the domain of execution operations that are permitted for any one of these asgctl commands (clone topology, dump topology, failover, instantiate topology, switchover topology, sync topology, and verify topology). Each instance list entry in this XML policy file (clone_policy.xml, dump_policy.xml, failover_policy.xml, instantiate_policy.xml, switchover_policy.xml, sync_policy.xml, and verify_policy.xml) logically tags a production-standby peer combination with a particular attribute that defines the success requirement for the commands successful operation. See Section 2.4, "Dumping Policy Files and Using Policy Files With Some asgctl Commands" for more information and an example of an XML policy file.

5.2.1 Special Considerations for OracleAS Disaster Recovery Configurations in CFC Environments

In an OracleAS Disaster Recovery configuration that uses CFC on the primary topology or standby topology, or both, the following information must be considered before performing an asgctl clone, instantiate topology, switchover topology, or failover command. Before taking a cold backup or restoring the metadata repository database, the OracleAS Recovery Manager shuts down the database first.

For example, in the Windows CFC environment, Oracle Fail Safe performs database polling and restarts the database if it is down. Hence, every time before the administrator performs a clone, instantiate, switchover, or failover operation, the administrator must disable database polling in Oracle Fail Safe and re-enable it after the backup/restore operation (after the clone, instantiate, switchover, or failover operation completes). The steps to perform this sequence of operations are described in a note in Section 5.2.1.1, "Special Considerations for Running Instantiate and Failover Operations in CFC Environments" and Section 5.2.1.3, "Special Considerations for Running a Switchover Operation in CFC Environments".

5.2.1.1 Special Considerations for Running Instantiate and Failover Operations in CFC Environments

Before taking a cold backup or restoring the metadata repository database, the OracleAS Recovery Manager shuts down the database first.

The steps to perform this sequence of operations are as follows:

Using Microsoft Cluster Administrator, open the cluster group that contains the Application Server resources. Take the following resources offline in this order: Oracle Process Manager, then Oracle Database, then Oracle Listener.
Using Windows Service Control Manager, start the following services in this order: Fail Safe Listener, then the Oracle Database service.
From a Windows command prompt, use the sqlplus command-line Utility to startup the database.
Using Windows Service Control Manager, start the Oracle Process Manager.
Perform the asgctl commands, including the clone, instantiate, switchover, or failover operation.
Using Microsoft Cluster Administrator, open up the cluster group that contains the Application Server resources and bring up the following resources online in this order: Oracle Listener, then Oracle Database, then Oracle Process Manager.

5.2.1.2 A Special Consideration and Workaround for Performing an Instantiate Operation in CFC Environments

When performing an instantiate operation, Oracle Application Server Guard puts an entry for the remote database in the tnsnames.ora file on both the production and standby site. The service name of this entry is constructed by concatenating _REMOTE1 to the database service name (for example, ORCL_REMOTE1). The entry contains the IP address of the target host where the database is running. On the production site, the IP will refer to the standby system and on the standby site, the IP refers to the production system.

In a CFC environment, the database is accessed using a virtual IP rather than a physical IP. When Oracle Application Server Guard creates the tnsnames.ora entry it should use the virtual IP, but it uses the physical IP instead. This problem will be fixed in a future release of Oracle Application Server Guard. As a workaround, when performing an instantiate operation in this environment, edit the tnsnames.ora file after an instantiation operation and replace the physical IP in the entry with the virtual IP used to access the database.

5.2.1.3 Special Considerations for Running a Switchover Operation in CFC Environments

In an OracleAS Disaster Recovery configuration that uses CFC on the primary topology or standby topology or both, the following information must be considered before performing an asgctl instantiate topology, switchover topology, or failover command.

Before taking a cold backup or restoring the metadata repository database, the OracleAS Recovery Manager shuts down the database first.

The steps to perform this sequence of operations are as follows:

Using Microsoft Cluster Administrator, open the cluster group that contains the Application Server resources. Take the following resources offline in this order: Oracle Process Manager, then Oracle Database, then Oracle Listener.
Using Windows Service Control Manager, start the following services in this order: Fail Safe Listener, then the Oracle Database service.
From a Windows command prompt, use sqlplus to start up the database.
Perform the asgctl commands, including the instantiate topology, switchover topology, or failover command.
Using Microsoft Cluster Administrator, open up the cluster group that contains the Application Server resources and bring up the following resources online in this order: Oracle Listener, then Oracle Database, then Oracle Process Manager.

5.2.2 Other Special Considerations for OracleAS Disaster Recovery Environments

See Section 4.1, "Special Considerations for Some OracleAS Metadata Repository Configurations" and Section 4.2, "Special Considerations for OracleAS Disaster Recovery Environments" for information describing some additional special considerations for OracleAS Disaster Recovery environments.

add instance

Adds to the local topology file, the specified instance name and name of the host system name on which this instance is installed, and if specified, propagates the updated topology file to all instances in the Disaster Recovery production environment.

You can use this command to add either an Application Server instance or an Oracle database instance to the local topology file.

Format

add instance <instance_name> on <instance_host> [to topology]

Parameters

instance_name

The name of the instance to be added to the topology file.

If you are adding a database instance to the topology file, instead of specifying the database instance name, specify the database identifier. If the database is a RAC database, the database identifier is the database SID. If the database is a single instance Linux database, then the database identifier is the database unique name.

instance_host

The name of the host on which this instance is installed. In the Disaster Recovery environment, if this host has a virtual hostname or a virtual hostname alias, then the virtual hostname must be used because it is this value that is placed in the topology file. For hosts with a virtual hostname or a virtual hostname aliases, use the fully qualified virtual hostname or fully qualified virtual hostname alias (the fully qualified name includes the domain name) for the instance host.

If the host does not have a virtual hostname or virtual hostname alias, use its fully qualified physical hostname.

Note:

See Section 1.2.1, "Planning and Assigning Hostnames" for more information about planning and assigning physical hostnames, network hostnames, virtual hostnames, and virtual hostname aliases for hosts in your Disaster Recovery environment.

to topology: A keyword, that if present in the command line, directs Oracle Application Server Guard to propagate the updated topology file to all instances in the Disaster Recovery production environment. Any Oracle Application Server Guard operation that affects the standby site, such as verify, instantiate, sync, and switchover will automatically propagate the production topology file across the standby environment.

Usage Notes

This command is useful for managing an instance on an Oracle Application Server Guard server to which the Oracle Application Server Guard client is connected. For example, you may have used the remove instance command to remove from the local topology file or from all topology files within the topology, an instance on this local host system because of a problem with it. Now you want to add to the local topology file or to all topology files in the topology, the good instance. In this case, you may not have wanted to manage the bad instance through the policy file where you could have set the success requirement attribute to Ignore for this instance when invoking asgctl commands to run across the entire topology.

This command is particularly useful for managing Disaster Recovery farms in which Oracle Internet Directory (OID) is not available, in other words, an OracleAS Release 10.1.3 only topology. You must use the discover topology within farm command to initially create the topology file for each instance within this farm. Then you can manage instances by adding or removing individual instances from the local topology file using the add instance and remove instance commands. If you specify the to topology or from topology keywords, the updated local topology file changes are propagated to all instances in the Disaster Recovery environment. See Section 5.2, "Information Specific to a Small Set of Oracle Application Server Guard Commands" for more information about topology files.

This command is useful for adding an OracleAS 10.1.3 J2EE instance to an OID based 10.1.2.0.2 topology to support a mixed version Disaster Recovery environment. For example, you can use the add instance command to add an OracleAS 10.1.3 J2EE instance to your OID based 10.1.2.0.2 topology. See Section 2.6, "Adding or Removing Oracle Application Server 10.1.3 Instances to Redundant Single Oracle Application Server 10.1.3 Home J2EE Topology Integrated with an Existing Oracle Identity Management 10.1.4.2 Topology" for a use case. See Section 5.2, "Information Specific to a Small Set of Oracle Application Server Guard Commands" for more information about topology files.

Example

The following command in the example adds to the local topology file only, an instance named oc4j1 that is installed on the local host system named prodinfra.

ASGCTL> connect asg prodinfra ias_admin/adminpwd
Successfully connected to prodinfra:7890
ASGCTL> discover topology within farm
ASGCTL> add instance oc4j1 on prodinfra.oracle.com

asgctl

Invokes the Oracle Application Server Guard client from the operating system command-line prompt or runs a script, if the path name to the script is provided.

Format

asgctl@[filename]

Parameters

filename = <file-path>: The path to a file that contains asgctl commands that you want to run as a script.

Usage Notes

On UNIX systems, asgctl.sh is located in <ORACLE_HOME>/dsa/bin and on Windows systems, asgctl.bat is located in <ORACLE_HOME>\dsa\bin.

Example

> asgctl.sh
Application Server Guard: Release 10.1.3.2.0(c) Copyright 2004, 2007 Oracle Corporation. All rights reserved
ASGCTL>

clone instance

Copies a single Oracle Application Server instance at a production site host to the same directory on a standby site host. This command also establishes the Disaster Recovery production-standby relationship for the instances.

Format

clone instance <instance> to <standby_topology_host> [no standby]

Parameters

instance: The name of the instance.

standby_topology_host

The name of the standby site host to which the instance is to be cloned. In the Disaster Recovery environment, if this host has a physical hostname, use the fully qualified physical hostname (the fully qualified name includes the domain name) for the host.

If the host does not have a physical hostname (for example, if it is an Infrastructure host), use its fully qualified network hostname (the fully qualified name includes the domain name).

Note:

no standby

This keyword directs Oracle Application Server Guard to copy the Application Server instance home from the production site host to the standby site host, but not establish the Disaster Recovery relationship between the production instance and standby instance. When you use this keyword, the Oracle Application Server instance home at the production site host is only copied to the standby site host, which is equivalent to using Oracle Universal Installer to install the instance at the standby site host.

When this keyword is used for a clone instance command that copies an Application Server home installed by an Infrastructure installation and a database with the Metadata Repository schemas was created in the Application Server home during the installation, Oracle Application Server Guard will copy the database to the standby site host, but will not configure Oracle Data Guard for the database.

Usage Notes

The default command copies an Oracle Application Server instance at a primary site host to the same directory on the standby site peer host and then sets up the Disaster Recovery relationship between the production and standby instance.

If you clone an Oracle Application Server instance installed by an Infrastructure installation and a database with the Metadata Repository schemas was created in the Application Server home during the installation, then Oracle Application Server Guard will copy the database to the standby site peer host and will configure Oracle Data Guard for the primary and standby databases.

Note:

The only type of database that the clone instance command copies and configures Oracle Data Guard for is described in the previous paragraph.

For more information about the Oracle Data Guard configuration set up for this type of database by this command, refer to Section 1.1.1.2, "Understanding the Default Oracle Data Guard Configuration Set Up by Oracle Application Server Guard."

For more information on including databases in your OracleAS Disaster Recovery topology and configuring Oracle Data Guard for those databases, refer to Section 1.1.1.1, "Configuring Oracle Data Guard for Databases in an OracleAS Disaster Recovery Topology."

The production instance must be included in the Disaster Recovery topology at the primary site. Refer to the add instance command description for information on adding an instance to the Disaster Recovery topology.

The production instance to be cloned cannot exist on the standby site host.

The following are prerequisites for the clone instance command:

Install and start the Oracle Application Server Guard standalone kit in its own Oracle home on the standby site host. Do not install any other Oracle components in the Oracle home for the Oracle Application Server Guard standalone kit on the standby site host.
A Java development kit with its jar utility must be installed on the standby site host.

For Windows hosts, release 5.0.2134.1 or higher of the services kit (sc.exe) must be installed under C:\WINDOWS\system32 on the production and standby site hosts.

If you do not take this step prior to performing a cloning operation on Windows, you may see errors similar to these during a cloning operation:

stajz09: -->ASG_DUF-4040: Error executing the external program or script.
The error code is "255"
"IM.asinfra.us.oracle.com"
stajz09P: -->ASG_IAS-15689: Error running the backup script
stajz09: -->ASG_IAS-15685: Failed to backup configuration data for instance
"IM.asinfra.us.oracle.com"
stajz09: -->ASG_DUF-3027: Error while executing Clone Instance at step -
backup step.
stajz09: -->ASG_DUF-3027: Error while executing Clone Topology at step -
clone home step.

For the dcm-daemon component in the %ORACLE_HOME%\opmn\conf\opmn.xml file on Windows hosts, increase the start timeout parameter's retry interval to 5 seconds. The following example shows the section of the opmn.xml file for the dcm-daemon component with the start timeout parameter's retry interval set to 5:

<ias-component id="dcm-daemon" status="enabled" id-matching="true">
    <process-type id="dcm-daemon" module-id="DCMDaemon">
        <start timeout="600" retry="5"/>
        <stop timeout="120"/>
        <process-set id="dcm" numprocs="1">

If you do not take this step prior to performing a cloning operation on Windows, you may see errors similar to these during a cloning operation:

stajz09: -->ASG_SYSTEM-100: Command "C:\work\im/opmn/bin/opmnctl.exe shutdown"
failed, check log file C:\work\im\dsa\bkup\log/2007-07-17_01-41-51_loha.log
for detail.
stajz09: -->ASG_SYSTEM-100: Failure : prepare failed.
stajz09: -->ASG_SYSTEM-100:
stajz09: -->ASG_SYSTEM-100: OPMN managed processes could not be stopped.
stajz09: -->ASG_SYSTEM-100: Status code:
stajz09: -->ASG_SYSTEM-100: opmnctl shutdown failed.

Use the no standby parameter with the clone instance command to clone the current configuration, but not establish the target as a standby site. The ability to create Application Server cluster topologies was introduced in Application Server release 10.1.3.1, but the clustering attributes cannot be propagated to the target without interfering with the original cluster if the target is on the same network. To alleviate this problem, ASG removes the topology entry [<topology>...</topology>] from the opmn.xml configuration file and leaves the resulting target unclustered. After the clone instance command with the no standby parameter has completed, you can cluster the resulting target configuration by editing and renaming the opmn.xml_asg file in each Oracle home. When the target is configured and maintained as a standby site, the standby cluster is automatically reconfigured during failover and switchover operations.

It is important to understand that during every asgctl clone operation the following are copied from the production site host (or hosts) to the standby site peer host (or hosts):

the Oracle home directory and files for each of the Oracle Application Server instances involved in the clone operation
the entire Oracle Universal Installer Central Inventory (Central Inventory) for each production site host for which an Oracle Application Server home is copied

Be aware of the following implications of the cloning behavior described in the previous list:

You cannot successfully clone one Application Server instance from one production site host and then a second Application Server instance from a different production site host to a single standby site host. Each clone instance command will successfully copy the Oracle home directory and files for the specified Application Server instance from the production site host to the standby site host. Because the entire Central Inventory for the production site host is also copied to the standby site host during the clone operation, the Central Inventory from the production site host overwrites the Central Inventory on the standby site host.

Therefore, in this cloning scenario, during the second clone operation the Central Inventory from the second production site host is copied to the standby site host, and it overwrites the Central Inventory that was copied to the standby site host during the first clone operation. After the second clone operation, there will no longer be a Central Inventory entry at the standby site host for the first Application Server instance that was cloned, so you will not be able to use the software for the first Application Server instance that was cloned to the standby site host.

However, after the second clone operation in this scenario, you can use Oracle Universal Installer to register the Application Server home that was copied to the standby site host during the first clone operation with the Central Inventory on that host. Registering the Application Server home that was copied during the first clone operation will allow you to use that software when the standby site becomes the production site (after a switchover or failover operation). Use the -attachHome flag of Oracle Universal Installer to register the home with the Central Inventory on the standby site host. See Oracle Universal Installer and OPatch User's Guide for information on using the -attachHome flag.
If a production site host has several Application Server instances installed and you clone one of those instances to a standby site host, the clone operation will copy the Oracle home directory and files for the specified Application Server instance to the standby site host and the entire Central Inventory for the production site host. After the clone operation completes, the standby site host's Central Inventory includes references to all of the Oracle homes that were installed on the production site host. However, the home for the Application Server instance that was specified with the clone instance command is the only Oracle home that was actually copied to the standby site host. The other Oracle homes referenced in the Central Inventory on the standby site were not copied from the production site host to the standby site host.

In this scenario, after the clone operation completes, you can use Oracle Universal Installer to remove references to the Oracle homes that were not copied to the standby site host from the Central Inventory on that host. Removing a reference to an Oracle home from the Central Inventory is called detaching an Oracle home. After detaching the Oracle homes that do not exist at the standby site host, the Central Inventory for that host will have the correct Oracle home information. Use the -detachHome flag of Oracle Universal Installer to detach Oracle homes from the Central Inventory on the standby site host. See Oracle Universal Installer and OPatch User's Guide for information on using the -detachHome flag.

See Section 2.7, "Oracle Application Server Guard Operations -- Standby Site Cloning of One or More Production Instances to a Standby System" for more information.

The basic procedure consists of the following pre-clone steps and clone steps.

Pre-Clone Steps

Perform the following steps:

Log in as su - root on UNIX or as Administrator on Windows to the production site host where the Application Server instance that you want to clone is installed.
CD to the instance home on the production site host for the instance that you want to clone.
On Windows, make sure that release 5.0.2134.1 or higher of the services kit (sc.exe) is installed in the C:\WINDOWS\system32 directory on the production site host.

Shut down the Oracle Application Server Guard server.

For 10.1.2.x and 10.1.4.x releases, this command stops OracleAS Guard on UNIX:
> <ORACLE_HOME>/opmn/bin/opmnctl stopproc ias-component=DSA

For 10.1.3.x releases, this command stops OracleAS Guard on UNIX:
> <ORACLE_HOME>/opmn/bin/opmnctl stopproc ias-component=ASG

For 10.1.2.x and 10.1.4.x releases, this command stops OracleAS Guard on Windows:
> <ORACLE_HOME>\opmn\bin\opmnctl stopproc ias-component=DSA

For 10.1.3.x releases, this command stops OracleAS Guard on Windows:
> <ORACLE_HOME>\opmn\bin\opmnctl stopproc ias-component=ASG

On UNIX, log in as root on the standby site host that the Application Server instance home will be cloned to and make sure dsaServer.sh in <ORACLE_HOME>/dsa/bin is executable by everyone. If it is not, record the permission, then change the executable permission by issuing the following command:
```
chmod +x dsaServer.sh
chmod u+x asgexec
```
On Windows, on the standby site host that the Application Server instance home will be cloned to:
1. Add the jdk\bin path to the system path on the standby site host.
2. Create a new command window.
3. In the new command window, run the jar command with no parameters to make sure the jar utility is found.
4. Make sure that release 5.0.2134.1 or higher of the services kit (sc.exe) is installed in the C:\WINDOWS\system32 directory on the standby site host.

On both the production site host and standby site host that will be involved in the clone operation, invoke asgctl and issue the startup command.

From the <ORACLE_HOME>/dsa/bin directory on a UNIX host:
> asgctl.sh startup

From the <ORACLE_HOME>\asg\bin directory in the new command window on a Windows host:
> asgctl startup

On UNIX hosts, log out as root.

Clone Steps

Perform the following steps:

Log in as user (non root user on UNIX hosts) to the production site host where the Application Server instance that you want to clone is installed.
CD to the instance home on the production site host for the Application Server instance that you want to clone.
Invoke asgctl on the production site host and run the clone instance command to clone the Application Server instance and home to the same directory on the standby site peer host.

Note:
In the command output, you will see a number of connect messages. This is normal as the Oracle Application Server Guard server is recycled during these operations.
Log out of the production site host.

Note:

If Oracle Application Server Guard does not run as root on UNIX hosts, the user will be prompted by the Oracle Application Server Guard client to run the underlying operations at each of the instance homes as root (manually) in order to continue with the operation.

This last step completes the cloning instance operation and brings the hosts back to where they were before you started the clone instance operation. At this point you could invoke asgctl, connect to a production site host, discover the topology, and then perform a verify operation to determine whether the production and standby topologies are valid and consistent with one another as you would expect them to be.

Example

The following command in the example clones an instance named portal_2 to the standby site host named asmid2.

1. Check the prerequisites as described in the Usage Notes.
2. Perform the Pre-Clone steps as described in the Usage Notes.
3. Perform the Clone steps as described in the Usage Notes.
   a. Log in as user to the production site host for the instance you want to clone.
   b. CD to the Oracle home for the Application Server instance to be cloned.
   c. Invoke asgctl and run the clone instance command.
> asgctl.sh

For 10.1.2.x and 10.1.4.x releases, use this command to connect to an ASG server:
ASGCTL> connect asg prodoc4j ias_admin/adminpwd
Successfully connected to prodoc4j:7890

For 10.1.3.x releases, use this command to connect to an ASG server:
ASGCTL> connect asg prodoc4j oc4jadmin/adminpwd
Successfully connected to prodoc4j:7890

ASGCTL> set primary database sys/testpwd@asdb
Checking connection to database asdb
ASGCTL> clone instance portal_2 to asmid2.oracle.com
.
.
.
ASGCTL> disconnect
ASGCTL> exit
>
   d. Log off the production site host.

clone topology

Copies all the Oracle Application Server instances from all of the production site hosts to the same directories on the standby site peer hosts. This command also establishes the Disaster Recovery production-standby relationship for these instances.

Format

clone topology to <standby_topology_host> [using policy <file>] [no standby]

Parameters

standby_topology_host

The name of a standby site host to which one or more instances will be cloned. In the Disaster Recovery environment, if this host has a physical hostname, use the fully qualified physical hostname for the host (the fully qualified name includes the domain name).

If the host does not have a physical hostname (for example, if it is an Infrastructure host), use its fully qualified network hostname (the fully qualified name includes the domain name).

Note:

using policy <file>

Full path and file specification for the XML policy file.

You can use a policy file with the clone topology command to copy only a subset of the Oracle Application Server homes at the production site hosts to the standby site peer hosts. Refer to Section 2.4, "Dumping Policy Files and Using Policy Files With Some asgctl Commands" for more information about using policy files.

no standby

This keyword directs Oracle Application Server Guard to copy the Application Server instance homes from the production site hosts to the standby site hosts, but not establish the Disaster Recovery relationship between the production instances and standby instances. When you use this keyword, the Oracle Application Server instance homes at the production site hosts are only copied to the standby site hosts, which is equivalent to using Oracle Universal Installer to install the instances at the standby site hosts.

When this keyword is used for a clone topology command that copies any Application Server home installed by an Infrastructure installation and a database with the Metadata Repository schemas was created in the Application Server home during the installation, Oracle Application Server Guard will copy the database to the standby site host, but will not configure Oracle Data Guard for the database.

Usage Notes

The default command copies all the Oracle Application Server instances from all of the production site hosts to the same directories on the standby site peer hosts and then sets up the Disaster Recovery relationship between the production site instances and the standby site peer instances. You can use a policy file to exclude specific Application Server instance homes on production site hosts from the clone topology operation.

If you clone any Oracle Application Server instance installed by an Infrastructure installation and a database with the Metadata Repository schemas was created in the Application Server home during the installation, then Oracle Application Server Guard will copy the database to the standby site peer host and will configure Oracle Data Guard for the primary and standby databases.

Note:

The only type of database that the clone topology command copies and configures Oracle Data Guard for is described in the previous paragraph.

This command is not supported by Disaster Recovery configurations where production and standby peer hosts have a different number of Oracle homes.

The production instances to be cloned cannot exist on the standby site hosts.

The following are prerequisites for the clone topology command:

Install and start the Oracle Application Server Guard standalone kit in its own Oracle home on each standby site host. Do not install any other Oracle components in the Oracle home for the Oracle Application Server Guard standalone kit on the standby site host.
A Java development kit with its jar utility must be installed on each standby site host.

For Windows hosts, release 5.0.2134.1 or higher of the services kit (sc.exe) must be installed under C:\WINDOWS\system32 on the production and standby site hosts.

If you do not take this step prior to performing a cloning operation on Windows, you may see errors similar to these during a cloning operation:

stajz09: -->ASG_DUF-4040: Error executing the external program or script.
The error code is "255"
"IM.asinfra.us.oracle.com"
stajz09P: -->ASG_IAS-15689: Error running the backup script
stajz09: -->ASG_IAS-15685: Failed to backup configuration data for instance
"IM.asinfra.us.oracle.com"
stajz09: -->ASG_DUF-3027: Error while executing Clone Instance at step -
backup step.
stajz09: -->ASG_DUF-3027: Error while executing Clone Topology at step -
clone home step.

<ias-component id="dcm-daemon" status="enabled" id-matching="true">
    <process-type id="dcm-daemon" module-id="DCMDaemon">
        <start timeout="600" retry="5"/>
        <stop timeout="120"/>
        <process-set id="dcm" numprocs="1">

If you do not take this step prior to performing a cloning operation on Windows, you may see errors similar to these during a cloning operation:

stajz09: -->ASG_SYSTEM-100: Command "C:\work\im/opmn/bin/opmnctl.exe shutdown"
failed, check log file C:\work\im\dsa\bkup\log/2007-07-17_01-41-51_loha.log
for detail.
stajz09: -->ASG_SYSTEM-100: Failure : prepare failed.
stajz09: -->ASG_SYSTEM-100:
stajz09: -->ASG_SYSTEM-100: OPMN managed processes could not be stopped.
stajz09: -->ASG_SYSTEM-100: Status code:
stajz09: -->ASG_SYSTEM-100: opmnctl shutdown failed.

Use the no standby parameter with the clone topology command to clone the current configuration, but not establish the targets as a standby site. The ability to create Application Server cluster topologies was introduced in Application Server release 10.1.3.1, but the clustering attributes cannot be propagated to the target without interfering with the original cluster if the targets are on the same network. To alleviate this problem, ASG removes the topology entry [<topology>...</topology>] from the opmn.xml configuration file and leaves the resulting targets unclustered. After the clone topology command with the no standby parameter has completed, you can cluster the resulting target configurations by editing and renaming the opmn.xml_asg files in each Oracle home. When the targets are configured and maintained as a standby site, the standby cluster is automatically reconfigured during failover and switchover operations.

It is important to understand that during every asgctl clone operation the following are copied from the production site host (or hosts) to the standby site peer host (or hosts):

the Oracle home directory and files for each of the Oracle Application Server instances involved in the clone operation
the entire Oracle software registry for each production site host for which an Oracle Application Server home is copied

Be aware of the following implications of the cloning behavior described in the previous list:

You cannot successfully clone one Application Server instance from one production site host and then a second Application Server instance from a different production site host to a single standby site host. Each clone instance command will successfully copy the Oracle home directory and files for the specified Application Server instance from the production site host to the standby site host. Because the entire Central Inventory for the production site host is also copied to the standby site host during the clone operation, the Central Inventory from the production site host overwrites the Central Inventory on the standby site host.

Therefore, in this cloning scenario, during the second clone operation the Central Inventory from the second production site host is copied to the standby site host, and it overwrites the Central Inventory that was copied to the standby site host during the first clone operation. After the second clone operation, there will no longer be a Central Inventory entry at the standby site host for the first Application Server instance that was cloned, so you will not be able to use the software for the first Application Server instance that was cloned to the standby site host.

However, after the second clone operation in this scenario, you can use Oracle Universal Installer to register the Application Server home that was copied to the standby site host during the first clone operation with the Central Inventory on that host. Registering the Application Server home that was copied during the first clone operation will allow you to use that software when the standby site becomes the production site (after a switchover or failover operation). Use the -attachHome flag of Oracle Universal Installer to register the home with the Central Inventory on the standby site host. See Oracle Universal Installer and OPatch User's Guide for information on using the -attachHome flag.
If a production site host has several Application Server instances installed and you clone one of those instances to a standby site host, the clone operation will copy the Oracle home directory and files for the specified Application Server instance to the standby site host and the entire Central Inventory for the production site host. After the clone operation completes, the standby site host's Central Inventory includes references to all of the Oracle homes that were installed on the production site host. However, the home for the Application Server instance that was specified with the clone instance command is the only Oracle home that was actually copied to the standby site host. The other Oracle homes referenced in the Central Inventory on the standby site were not copied from the production site host to the standby site host.

In this scenario, after the clone operation completes, you can use Oracle Universal Installer to remove references to the Oracle homes that were not copied to the standby site host from the Central Inventory on that host. Removing a reference to an Oracle home from the Central Inventory is called detaching an Oracle home. After detaching the Oracle homes that do not exist at the standby site host, the Central Inventory for that host will have the correct Oracle home information. Use the -detachHome flag of Oracle Universal Installer to detach Oracle homes from the Central Inventory on the standby site host. See Oracle Universal Installer and OPatch User's Guide for information on using the -detachHome flag.

See Section 2.7, "Oracle Application Server Guard Operations -- Standby Site Cloning of One or More Production Instances to a Standby System" for more information.

The basic procedure consists of the following pre-clone steps and clone steps.

Pre-Clone Steps

Perform the following steps:

Log in as su - root on UNIX or as Administrator on Windows to each production site host where an Application Server instance that you want to clone is installed.
CD to the instance homes on the production site hosts for each instance that you want to clone.
On Windows, make sure that release 5.0.2134.1 or higher of the services kit (sc.exe) is installed in the C:\WINDOWS\system32 directory on the production site hosts.

Shut down the Oracle Application Server Guard server.

For 10.1.2.x and 10.1.4.x releases, this command stops OracleAS Guard on UNIX:
> <ORACLE_HOME>/opmn/bin/opmnctl stopproc ias-component=DSA

For 10.1.3.x releases, this command stops OracleAS Guard on UNIX:
> <ORACLE_HOME>/opmn/bin/opmnctl stopproc ias-component=ASG

For 10.1.2.x and 10.1.4.x releases, this command stops OracleAS Guard on Windows:
> <ORACLE_HOME>\opmn\bin\opmnctl stopproc ias-component=DSA

For 10.1.3.x releases, this command stops OracleAS Guard on Windows:
> <ORACLE_HOME>\opmn\bin\opmnctl stopproc ias-component=ASG

On UNIX, log in as root on each standby site host that an Application Server instance home will be cloned to and make sure dsaServer.sh in <ORACLE_HOME>/dsa/bin is executable by everyone. If it is not, record the permission, then change the executable permission by issuing the following command:
```
chmod +x dsaServer.sh
chmod u+x asgexec
```
On Windows, on each standby site host that an Application Server instance home will be cloned to:
1. Add the jdk\bin path to the system path on the standby site host.
2. Create a new command window.
3. In the new command window, run the jar command with no parameters to make sure the jar utility is found.
4. Make sure that release 5.0.2134.1 or higher of the services kit (sc.exe) is installed in the C:\WINDOWS\system32 directory on the standby site host.

On both the production site host or hosts and the standby site host or hosts that will be involved in the clone operation, invoke asgctl and issue the startup command.

From the <ORACLE_HOME>/dsa/bin directory on a UNIX host:
> asgctl.sh startup

From the <ORACLE_HOME>\asg\bin directory in the new command window on a Windows host:
> asgctl startup

On UNIX hosts, log out as root.

Clone Steps

Perform the following steps:

Log in as user (non root user on UNIX hosts) to the production site host or hosts where the Application Server instances that you want to clone are installed.
CD to the instance homes on the production site hosts for each Application Server instance that you want to clone.
Invoke asgctl on any of the production site hosts and run the clone topology command to clone the Application Server instances and homes for all of the production site hosts to the same directories on the standby site peer hosts. Remember that you can use a policy file to exclude specific Application Server instance homes on production site hosts from a clone topology operation.

Note:
In the command output, you will see a number of connect messages. This is normal as the Oracle Application Server Guard server is recycled during these operations.
Log out of the system.

Note:

This last step completes the cloning topology operation and brings the hosts back to where they were before you started the clone topology operation. At this point you could invoke asgctl, connect to a production site host, discover the topology, and then perform a verify operation to determine whether the production and standby topologies are valid and consistent with one another as you would expect them to be.

See Section 5.1, "Information Common to Oracle Application Server Guard asgctl Commands" and Section 5.2, "Information Specific to a Small Set of Oracle Application Server Guard Commands" for more information.

Example

The following example shows how to copy multiple Application Server instances from production site hosts to standby site peer hosts.

1. Check the prerequisites as described in the Usage Notes.
2. Perform the Pre-Clone steps as described in the Usage Notes.
3. Perform the Clone steps as described in the Usage Notes.
   a. Log in as user to all the production site hosts where an Application Server instance home you want to clone is installed.
   b. CD to the Oracle home for each Application Server instance to be cloned.
   c. Invoke asgctl on one of the production site hosts and perform the clone topology command.
> asgctl.sh

For 10.1.2.x and 10.1.4.x releases, use this command to connect to an ASG server:
ASGCTL> connect asg prodoc4j ias_admin/adminpwd
Successfully connected to prodoc4j:7890

For 10.1.3.x releases, use this command to connect to an ASG server:
ASGCTL> connect asg prodoc4j oc4jadmin/adminpwd
Successfully connected to prodoc4j:7890

ASGCTL> set primary database sys/testpwd@asdb
Checking connection to database asdb

# Command to use if you are cloning all the Application Server
# instances at all the production site hosts to the standby site
# peer hosts:
ASGCTL> clone topology to standbyinfra.oracle.com
.
.
.

# Command to use if you are using a policy file (where <file>
# is the full path and file specification of the clone policy file)
# to clone a subset of the Application Server instances at the production
# site hosts to the standby site peer hosts:
ASGCTL> clone topology to standbyinfra.oracle.com using policy <file>
.
.
.
ASGCTL> disconnect
ASGCTL> exit
>
   d. Log off the system

connect asg

Connects the Oracle Application Server Guard client to the Oracle Application Server Guard server on a system on which Oracle Application Server services are running.

Format

connect asg [<host-name>[:<port>]] <ias_administrative_account>/<password>

Parameters

host-name = <host-name>: The network hostname of the host system for the Oracle Application Server Guard server to which you want the Oracle Application Server Guard client to connect. This Oracle Application Server Guard server will be the coordinating server for all operations performed on the host systems being configured. The host name is optional if the Oracle Application Server Guard client and Oracle Application Server Guard server are on the same node.

Note:
See Section 1.2.1, "Planning and Assigning Hostnames" for more information about planning and assigning physical hostnames, network hostnames, virtual hostnames, and virtual hostname aliases for hosts in your Disaster Recovery environment.
port: The port number of the Oracle Application Server Guard server in its Oracle home.
<ias_administrative_account>/password: If this is an OracleAS 10.1.3 installation, the user name must be oc4jadmin and the password for the oc4jadmin account created during the Oracle Application Server installation. If this is an OracleAS 10.1.2.0.2 or lower installation, the user name must be the ias_admin account name and the password for the ias_admin account created during the Oracle Application Server installation.

Note:
If this is an OracleAS 10.1.3 installation, the user name must be oc4jadmin and the password for the oc4jadmin account created during the Oracle Application Server 10.1.3 installation.

Usage Notes

The Oracle Application Server Guard client system must have network access to the Oracle Application Server Guard host system specified with the host-name parameter.
The Oracle Application Server Guard host system must have network access to all systems in the OracleAS Disaster Recovery configuration.
The specified ias_admin or oc4jadmin account name must be configured with the necessary rights and privileges to permit OracleAS Disaster Recovery site operations (read and write access to all required files and directories, and so forth)
An IP address can be used in place of a host name.
If a password for the ias_admin or oc4jadmin account is not specified in the connect command, you will be prompted to enter a password.

Example

The command in the following example results in the Oracle Application Server Guard client connecting to the Oracle Application Server Guard server running on a host named prodinfra using the ias_admin username and adminpwd password, respectively.

ASGCTL> connect asg prodinfra ias_admin/adminpwd
Successfully connected to prodinfra:7890

create standby database

Copies the database files for a database at a production site host to the standby site peer host and configures Oracle Data Guard for the primary database and standby database.

Format

create standby database <database_identifier> on <remote_host>

Parameters

database_identifier: Primary database identifier used to create the standby database on the remote host sytem. If the database is a RAC database, the database identifier is the database SID. If the database is a single instance Linux database, then the database identifier is the database unique name.

remote_host

Name of the host system on which the standby database is to be created. In the Disaster Recovery environment, if this host has a physical hostname, use the physical hostname for the host.

If the host does not have a physical hostname (for example, if it is an Infrastructure host), use its network hostname.

Note:

Usage Notes

If a production site host has a single instance or RAC database that is installed outside an Application Server home and the database does not use the Oracle Managed Files (OMF) or Automatic Storage Management (ASM) database storage options, you can use the create standby database command to create a standby database on the standby site peer host and configure Oracle Data Guard for the primary and standby databases.

Note:
For more information on including databases in your OracleAS Disaster Recovery topology and configuring Oracle Data Guard for those databases, refer to Section 1.1.1.1, "Configuring Oracle Data Guard for Databases in an OracleAS Disaster Recovery Topology."
For more information about the Oracle Data Guard configuration set up by this command, refer to Section 1.1.1.2, "Understanding the Default Oracle Data Guard Configuration Set Up by Oracle Application Server Guard."
The create standby database command is designed to automate the creation of simple standby databases. It does not support some database options, such as the OMF or ASM storage options. Therefore, if you plan to use the create standby database command to create a database at the standby site, create the database instance on the primary site without specifying the OMF or ASM storage options.
The create standby database command does not work properly if a database exists in the database home on the standby site peer host when the command is executed. If a database already exists in the home on the standby site peer host, follow the instructions in Section A.1.22, "Database Already Exists Errors During Create Standby" before using the create standby database command.
Oracle software and Oracle Application Server Guard software are required to be installed on the node designated as <remote_host>.
The init.ora parameter file generated for the standby database is configured assuming a non Oracle RAC enabled standby database. If the standby database is to be Oracle RAC enabled, the following initialization parameters must be defined appropriately:
- cluster_database
- cluster_database_instances
- remote_listener
In an Oracle Clusterware environment, Oracle Clusterware is configured to bring up the database automatically upon failure. However, this automatic online feature of Oracle Clusterware must be disabled on all Oracle RAC instances during Oracle Application Server Guard operations. To guarantee the disabling of automatic startup of the database, perform the following two commands:
```
$DBHOME\bin\srvctl disable database -d ORCL
$DBHOME\bin\srvctl stop database -d ORCL
```
In addition, you must avoid shutting down the entire Oracle Clusterware daemons; otherwise, the database will not start up and the following error will be returned:
```
SQL> startup
ORA-29702: error occurred in Cluster Group Service operation
SQL> exit
```
If the asgctl create standby database command is performed in an Oracle RAC environment from one of the primary instances, for example orcl2, within a 2 node RAC instance with instances orcl1 on one node and orcl2 on another node, to the standby single node non RAC Database, a heartbeat error log will be seen in the alert logs of the other Oracle RAC instances

If the asgctl create standby database command is performed in an Oracle RAC environment from one of the primary instances to the standby single node non RAC Database, a heartbeat error log will be seen in the alert logs of the other Oracle RAC instances as follows:

----------------------------------------------------------------------------
PING[ARC0]: Heartbeat failed to connect to standby 'orcl2_remote1'. Error is 12154.
Mon Aug 28 09:53:43 2006
Error 12154 received logging on to the standby
Mon Aug 28 09:53:43 2006
Errors in file c:\oracle\product\10.2.0\admin\orcl\bdump\orcl1_arc0_2752.trc:
ORA-12154: TNS:could not resolve the connect identifier specified
----------------------------------------------------------------------------

The reason for this error is because the asgctl create standby database command did not configure the hosts. To work around this problem, you must manually configure the remaining hosts not configured by this command by appending the appropriate remote service name entry into the remaining Oracle RAC tnsnames.ora file instances. For example:

ORCL2_REMOTE1.MYCOMPANY.COM =
  (DESCRIPTION =
    (ADDRESS_LIST =
      (ADDRESS = (PROTOCOL = TCP)(HOST = 140.87.23.35)(PORT = 1521))
    )
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = orcl2.mycompany.com)
    )
  )

In an Oracle RAC environment, the create standby database command will only set up an Oracle RAC to a standalone non Oracle RAC configuration with clustering options disabled. However, if the Disaster Recovery Administrator wants the standby (new production) database to be brought up as part of a cluster following either an Oracle Application Server Guard failover or switchover operation, this can be accomplished by modifying the init.ora file parameters as follows:
- Change cluster_database=false to cluster_database=true
- Change cluster_database_instances=1 to a value n where n represents the number of instances in the cluster.
- Set up the remote_listener parameter.
Note that these changes can be set up in a script and invoked using the asgctl run command. See the run command for more information.

Example

The command in this example takes the primary database unique name named orcl and creates the standby database on the remote host system named asmid1.

ASGCTL> create standby database orcl on asmid1

disconnect

Disconnects the Oracle Application Server Guard client from the Oracle Application Server Guard server to which it is currently connected.

Format

disconnect

Usage Notes

The Oracle Application Server Guard client must be connected to a Oracle Application Server Guard server when you issue this command.

Example

The command in the following example disconnects the Oracle Application Server Guard client from the Oracle Application Server Guard server to which it is currently connected.

ASGCTL> disconnect
ASGCTL>

discover topology

Directs asgctl to query Oracle Internet Directory and determine all instances within the topology that share the same Oracle Internet Directory for a production site and generates a topology.xml file that describes the topology.

Format

discover topology [oidhost=<host>] [oidsslport=<sslport>] [oiduser=<user>] oidpassword=<pass>

Parameters

host

Name of the host system where Oracle Internet Directory is installed. In the Disaster Recovery environment, if this host has a virtual hostname or a virtual hostname alias, then the virtual hostname must be used because it is this value that is placed in the topology file. For hosts with a virtual hostname or a virtual hostname aliases, use the fully qualified virtual hostname or fully qualified virtual hostname alias (the fully qualified name includes the domain name) for the instance host. The host name is optional if you are currently connected to the Oracle Application Server Guard server on the host through the use of the asgctl connect asg command.

If the host does not have a virtual hostname or virtual hostname alias, use its fully qualified physical hostname (the fully qualified name includes the domain name).

Note:

sslport: The port number of the host system where Oracle Internet Directory and Secure Sockets Layer (SSL) is installed.

user: The Oracle Internet Directory user name.

pass: The password for the specified Oracle Internet Directory user name.

Usage Notes

You should perform a discover topology operation whenever you procure another Oracle home in a production site or change roles from a production to a standby site through a switchover or failover operation.

Discover topology creates the topology (stored in topology.xml) on which to perform all Oracle Application Server Guard operations. This command utilizes the information in Oracle Internet Directory to define the instances included in the topology. Additionally, it gathers local information about each instance. For this reason, it requires all production site instances to have OPMN running. For instances not managed using a DCM farm, the Oracle Application Server Guard service on the Oracle home has to be started. If the services are not started locally, a warning will be produced and the topology.xml file will contain only the instances discovered.

Example

The command in the following example discovers all the instances within the topology that share the same Oracle Internet Directory (OID) for a production site, and generates a topology XML file that describes the topology.

ASGCTL> connect asg prodinfra ias_admin/adminpwd
Successfully connected to prodinfra:7890
ASGCTL> discover topology oidpassword=oidpwd
Discovering topology on host "infra" with IP address "123.1.2.111" prodinfra:7890
    Connecting to the OID server on host "infra.us.oracle.com" using SSL port "636" and username "orcladmin"
    Getting the list of databases from OID
    Gathering database information for SID "asdb" from host "infra.us.oracle.com"
    Getting the list of instances from OID
    Gathering instance information for "asr1012.infra.us.oracle.com" from host "infra.us.oracle.com"
    Gathering instance information for "asmid1.asmid1.us.oracle.com" from host "asmid1.us.oracle.com"
    Gathering instance information for "asmid2.asmid2.us.oracle.com" from host "asmid2.us.oracle.com"
The topology has been discovered. A topology.xml file has been written to each home in the topology.
ASGCTL>

discover topology within farm

Directs asgctl to discover the topology within a farm at a production site for those special cases where a farm does not have Oracle Internet Directory available. For 10.1.3.x environments, Oracle recommends using the discover topology within farm command.

Format

discover topology within farm

Parameters

None.

Usage Notes

The Oracle Application Server Guard client must be connected to a Oracle Application Server Guard server when you issue this command.

See Section 5.2, "Information Specific to a Small Set of Oracle Application Server Guard Commands" for more information about topology files.

Example

The command in the following example for a special case in which Oracle Internet Directory (OID) is not available, uses OPMN to discover the application server topology within a farm of the Oracle Application Server Guard server to which the Oracle Application Server Guard client is currently connected.

ASGCTL> connect asg prodinfra ias_admin/adminpwd
Successfully connected to prodinfra:7890
ASGCTL> set primary database sys/testpwd@asdb
Checking connection to database asdb
ASGCTL> discover topology within farm
Warning: If OID is part of your environment, you should use it for discovery
Discovering topology on host "infra" with IP address "123.1.2.111"
prodinfra:7890
    Discovering instances within the topology using OPMN
    Gathering instance information for "asr1012.infra.us.oracle.com" from host "infra.us.oracle.com"
The topology has been discovered. A topology.xml file has been written to each home in the topology.
ASGCTL>

dump policies

Directs Oracle Application Server Guard Server to write detailed, default policy information in XML formatted output for the different asgctl commands to a set of policy files located on the local host at the <ORACLE_HOME>/dsa/conf directory on UNIX systems or <ORACLE_HOME>\dsa\conf directory on Windows systems.

Format

dump policies

Parameters

None.

Usage Notes

A set of XML formatted policy files are written for each of the following asgctl commands: clone topology, dump topology, failover, instantiate topology, sync topology, switchover topology, and verify topology. You can edit the respective command's policy file, then specify it in the using policy <file> clause for the appropriate command. This parameter lets you define the topology's disaster recovery policy for each of these Oracle Application Server Guard operations.

For the dump policy file, by default the success requirement attribute is set to optional for all instances (middle tier and OracleAS Metadata Repository).

For the failover policy file, by default the success requirement attribute is set to optional for all instances (middle tier and OracleAS Metadata Repository) and mandatory for the Oracle Internet Directory home.

For the instantiate policy file, by default the success requirement attribute is set to mandatory for all instances.

For the switchover policy file, by default the success requirement attribute is set to optional for all instances (middle tier and OracleAS Metadata Repository) and mandatory for the Oracle Internet Directory home.

For the sync policy file, by default the success requirement attribute is set to mandatory for all instances.

For the verify policy file, by default the success requirement attribute is set to optional for all instances (middle tier and OracleAS Metadata Repository) and mandatory for the Oracle Internet Directory home.

Example

The following example writes detailed, default policy information in XML formatted output for the different asgctl commands to a set of respective policy files located on the local host.

ASGCTL> dump policies
Generating default policy for this operation
Creating policy files on local host in directory "/private1/OraHome2/asr1012/dsa/conf/"
ASGCTL>

dump topology

Directs asgctl to write detailed information about the topology to the specified file.

Format

dump topology [to <file>] [using policy <file>]

Parameters

to <file>: Name of file on the Oracle Application Server Guard client node where the detailed output is to be written.
using policy <file>: Full path and file specification for the XML policy file.

Usage Notes

For the dump policy file, by default the success requirement attribute is set to optional for all OracleAS homes (middle tier and OracleAS Metadata Repository).

Example

The following example writes detailed information about the topology to a local file.

ASGCTL> connect asg prodinfra ias_admin/adminpwd
Successfully connected to prodinfra:7890
ASGCTL> set primary database sys/testpwd@asdb
Checking connection to database asdb
ASGCTL> dump topology to c:\dump_mid_1.txt

Contents of file c:\dump_mid_1.txt are:

Generating default policy for this operation
 
 Instance: asr1012.infra.us.oracle.com
    Type: Infrastructure
    Oracle Home Name: asr1012
    Oracle Home Path: /private1/OraHome
    Version: 10.1.2.0.2
    OidHost: infra.us.oracle.com
    OidPort: 389
    VirtualHost: infra.us.oracle.com
    Host: prodinfra
    Ip: 123.1.2.111
    Operation System Arch: sparc
    Operation System Version: 5.8
    Operation System Name: SunOS

 Instance: asmid2.asmid2.us.oracle.com
    Type: Core
    Oracle Home Name: asmid2
    Oracle Home Path: /private1/OraHome2
    Version: 10.1.2.0.2
    OidHost: infra.us.oracle.com
    OidPort: 389
    VirtualHost: asmid2.us.oracle.com
    Host: asmid2
    Ip: 123.1.2.333
    Operation System Arch: sparc
    Operation System Version: 5.8
    Operation System Name: SunOS
 
 Instance: asmid1.asmid1.us.oracle.com
    Type: Core
    Oracle Home Name: asmid1
    Oracle Home Path: /private1/OraHome
    Version: 10.1.2.0.2
    OidHost: infra.us.oracle.com
    OidPort: 389
    VirtualHost: asmid1.us.oracle.com
    Host: asmid1
    Ip: 123.1.2.334
    Operation System Arch: sparc
    Operation System Version: 5.8
    Operation System Name: SunOS
ASGCTL>

The following example writes detailed information about the topology to a local file. Any instances that you want left out of the output can be specified in the policy file.

# Command to use if you are using a policy file
ASGCTL> dump topology to c:\dump_mid_1.txt using policy <file>

exit

Disconnects from any existing connections to Oracle Application Server Guard servers and exits from the Oracle Application Server Guard client.

Format

exit

Parameters

None

Usage Notes

None.

Example

ASGCTL> exit
>

failover

During an unscheduled outage of the production site, performs the failover operation on the standby site to make it the primary site.

Format

failover [using policy <file>]

Parameters

using policy <file>: Full path and file specification for the XML policy file.

Usage Notes

Make sure OracleAS Infrastructure database is running on the standby topology before performing a failover operation. Also, the OracleAS Infrastructure database information must be set by using the set new primary database asgctl command.

The global DNS names are used to direct the failover. This will be different than the HA naming utilized in the OracleAS Disaster Recovery environment. The discovery mechanism automatically maps the topology to the corresponding peer, based off local name resolution.

For the failover policy file, by default the success requirement attribute is set to optional for all OracleAS homes (middle tier and OracleAS Metadata Repository) and mandatory for the Oracle Internet Directory home.

Example

The following example performs a failover operation to a standby site.

ASGCTL> connect asg standbyinfra ias_admin/adminpwd
Successfully connected to standbyinfra:7890
ASGCTL> set new primary database sys/testpwd@asdb
ASGCTL> failover
Generating default policy for this operation
standbyinfra:7890
    Failover each instance in the topology from standby to primary topology
standbyinfra:7890 (home /private1/OraHome2/asr1012)
    Shutting down each instance in the topology
.
.
.
    Executing opmnctl startall command
standbyinfra:7890
     HA directory exists for instance asr1012.infra.us.oracle.com
asmid2:7890
     HA directory exists for instance asmid2.asmid2.us.oracle.com
asmid1:7890
     HA directory exists for instance asmid1.asmid1.us.oracle.com
ASGCTL>

# Command to use if you are using a policy file
# failover using policy <file>

help

Displays help information.

Format

help [<command>]

Parameters

command: Name of the command for which you want help.

Usage Notes

None.

Example

The following example displays help about all commands.

ASGCTL> help
    connect asg [<host>] [<ias_administrator_account>/<password>]
    disconnect 
    exit
    quit
    add instance <instance_name> on <instance_host> [to topology]
    clone topology to <standby_topology_host> [using policy <file>] [no standby]
    clone instance <instance> to <standby_topology_host> [no standby]
    discover topology [oidhost=<host>] [oidsslport=<sslport>] [oiduser=<user>] oidpassword=<pass>
    discover topology within farm
    dump farm [to <file>]  (Deprecated)
    dump topology  [to <file>] [using policy <file>]
    dump policies
    failover [using policy <file>]
    help [<command>]
    instantiate farm to <standby_farm_host> (Deprecated)
    instantiate topology to <standby_topology_host> [using policy <file>]
    remove instance <instance_name> [from topology]
    set asg credentials <host> <ias_administrator_account>/<password> [for topology]
    set asg credentials <host> ias_admin/<password> [for farm] (Deprecated)
    set primary database <username>/<password>@<servicename> [pfile <filename> | spfile <filename>]
    set new primary database <username>/<password>@<servicename> [pfile <filename> | spfile <filename>]
    set noprompt
    set trace on|off <traceflags>
    sync farm to <standby_farm_host> [full | incr[emental]] (Deprecated)
    sync topology to <standby_topology_host> [full | incr[emental]] [using policy <file>]
    startup [asg]
    startup farm (Deprecated)
    startup topology
    shutdown [local]
    shutdown farm (Deprecated)
    shutdown topology
    show op[eration] [full] [[his]tory]
    show env
    stop op[eration] <op#>
    switchover farm to <standby_farm_host> (Deprecated)
    switchover topology to <standby_topology_host> [using policy <file>]
    verify farm [with <host>](Deprecated)
    verify topology [with <host>] [using policy <file>] 
ASGCTL>

instantiate topology

Using the primary site topology, creates the standby site topology by establishing the relationship between primary site and standby site Application Server instances, mirroring the configuration, and then synchronizing the standby site with the primary site.

Format

instantiate topology to <standby_topology_host>[:<port>] [using policy <file>]

Parameters

standby_topology_host

Name of the standby host system. This parameter is required because it directs the coordinating Oracle Application Server Guard server instance to discover the instances that make up the standby site. This host system must be a member of the standby site topology.

In the Disaster Recovery environment, if this host has a physical hostname, use the physical hostname for the host.

If the host does not have a physical hostname (for example, if it is an Infrastructure host), use its network hostname.

Note:

port

The port number of the Oracle Application Server Guard server in its Oracle home.

using policy <file>

Full path and file specification for the XML policy file.

Usage Notes

The instantiate topology command establishes the Disaster Recovery relationship between the Oracle Application Server homes at the Disaster Recovery production site hosts and the equivalent Oracle homes at the standby site peer hosts.

The OracleAS Infrastructure database with the Metadata Repository schemas must be running on the primary topology before you execute the instantiate topology command . You must also use the asgctl set primary database command to log in to and validate the connection to the OracleAS Infrastructure database before you execute the instantiate topology command.

Before you use the instantiate topology command, you must install the same Application Server instances into the same Oracle home directories on the production site hosts and the standby site peer hosts. If during an Application Server Infrastructure installation on a production site host you created a database with the Metadata Repository schemas in that Application Server home, you must perform the same installation in the equivalent directory on the standby site peer host.

For Application Server homes at the production site and standby site that include a database with the Metadata Repository schemas that was created during an Application Server Infrastructure installation, the instantiate topology command configures Oracle Data Guard for the primary database and standby database.

Note:

The only type of database that the instantiate topology command configures Oracle Data Guard for is described in the previous paragraph.

The global DNS names are used to direct the instantiation. The discovery mechanism automatically maps the topology to the corresponding peer, based off local name resolution.

The instantiate topology command performs an implicit asgctl verify command.

For the instantiate policy file, by default the success requirement attribute is set to mandatory for all instances.

Example

The following example instantiates a standby topology by attaching the coordinating Oracle Application Server Guard server and discovering the topology of the production and standby sites, performing site verification, and establishing a OracleAS Disaster Recovery environment with the topology containing the standby topology host known by DNS as standbyinfra. Note that part way through the operation you will be prompted to answer a question regarding whether you want to shut down the database. Reply by entering y or yes.

ASGCTL> connect asg prodinfra ias_admin/adminpwd
Successfully connected to prodinfra:7890
ASGCTL> set primary database sys/testpwd@asdb
Checking connection to database asdb
ASGCTL> instantiate topology to standbyinfra
Generating default policy for this operation
prodinfra:7890
    Instantiating each instance in the topology to standby topology
     HA directory exists for instance asr1012.infra.us.oracle.com
asmid2:7890
     HA directory exists for instance asmid2.asmid2.us.oracle.com
asmid1:7890
     HA directory exists for instance asmid1.asmid1.us.oracle.com
standbyinfra:7890
     HA directory exists for instance asr1012.infra.us.oracle.com
asmid2:7890
     HA directory exists for instance asmid2.asmid2.us.oracle.com
asmid1:7890
     HA directory exists for instance asmid1.asmid1.us.oracle.com
asmid2:7890
    Verifying that the topology is symmetrical in both primary and standby configuration
.
.
.
This operation requires the database to be shutdown. Do you want to continue? Yes or No
y
.
.
.
asmid2:7890 (home /private1/oracle/asr1012)
    Starting backup/synchronization of database "orcl.us.oracle.com"
    Starting restore/synchronization of database "orcl.us.oracle.com"
    Synchronizing topology completed successfully
asmid2:7890
    Synchronizing topology completed successfully

ASGCTL>

# Command to use if you are using a policy file
# instantiate topology to standbyinfra using policy <file>

quit

Instructs the Oracle Application Server Guard client to disconnect from any existing connections and exit from asgctl.

Format

quit

Parameters

None

Usage Notes

None.

Example

The following example exits from asgctl.

ASGCTL> quit
>

remove instance

Removes from the local topology file, the specified instance name, and if specified, propagates this updated topology file to all instances in the Disaster Recovery production environment.

Format

remove instance <instance_name> [from topology]

Parameters

instance_name: The name of the instance to be removed from the topology file.

from topology: A keyword, that if present in the command line, directs Oracle Application Server Guard to propagate the updated topology file to all instances in the Disaster Recovery production environment. Any Oracle Application Server Guard operation that affects the standby site, such as verify, instantiate, sync, and switchover will automatically propagate the production topology file across the standby environment.

Usage Notes

Example

The following command in the example removes from the local topology file an instance named oc4j1.

ASGCTL> remove instance oc4j1

run

Remotely executes a script or program that resides in any home where Oracle Application Server Guard is installed. The run command can be executed within a topology or at the specified instance.

Format

run [at topology [using policy <file>]] <command>

run [at instance <instance_name>] <command>

Parameters

at topology: A keyword, that if present in the command line, directs Oracle Application Server Guard to perform the run operation across the topology.
using policy <file>: Full path and file specification for the XML policy file.
command: The name as a command string of the script or binary program to be executed.
at instance: A keyword, that if present in the command line, directs Oracle Application Server Guard to perform the run operation at the specified instance.
instance_name: The name of the instance where the run command is to be executed.

Usage Notes

This command is useful for remotely executing a script or program that resides in any Oracle home where Oracle Application Server Guard is installed. The script or program must be physically located in each Oracle home across the topology or at that specified instance where it is expected to be executed. The asgctl user must first connect to the Oracle Application Server Guard server specifying the Application Server JAZN credentials (ias_admin or oc4jadmin) before invoking this asgctl run command. It is assumed that if the user knows the JAZN credentials, then the user should be allowed to execute a script or program in the home. Upon receiving a run command invocation, Oracle Application Server Guard will verify that the file specified in the command string exists in the Oracle home where the Oracle Application Server Guard server is running before executing the script or program. The output of the script is echoed back to the asgctl console.

Example

The command in this example remotely runs the script my_script.sh for the instance named asdb.

ASGCTL> run at instance asdb my_script.sh

set asg credentials

Sets the credentials used to authenticate the Oracle Application Server Guard connections to Oracle Application Server Guard servers.

Format

set asg credentials <host>[:<port>] <ias_administrative_account>/<password> [for farm] [for topology]

Parameters

host

Name of the host system to which the credentials apply. When Oracle Application Server Guard connects to that host, it will use these credentials.

Use the network hostname of the host. The host name is optional if you are currently connected to the Oracle Application Server Guard server on the host through the use of the asgctl connect asg command.

Note:

port

The port number of the Oracle Application Server Guard server in its Oracle home.

<ias_administrative_account>/password

If this is an OracleAS 10.1.3 installation, the user name must be oc4jadmin and the password for the oc4jadmin account created during the Oracle Application Server 10.1.3 installation. If this is an OracleAS 10.1.2.0.2 or lower installation, the user name must be the ias_admin account name and the password for the ias_admin account created during the Oracle Application Server installation. This account name must be the same as the account name on at least one of the Oracle Application Server homes.

for farm (deprecated)

A keyword, that if present in the command line, directs Oracle Application Server Guard to set the credentials for all of the host systems that belong to the same farm as the local host system.

for topology

A keyword, that if present in the command line, directs Oracle Application Server Guard to set the credentials for all of the host systems that belong to the same topology as the local host system.

Usage Notes

By default, the credentials used in the asgctl connect command are used whenever a Oracle Application Server Guard server needs to connect to another Oracle Application Server Guard server. However, there may be cases where you want to use different credentials for a specific server. This command enables you to use the same credentials for all nodes in a topology. For example, you may want to use a common set of credentials in the standby topology that is different from the credentials used in the primary topology.

If you set the credentials for a topology, these credentials are inherited for the entire topology. If you set the credentials for an individual host on the topology, the credentials (for this host) override the default credentials set for the topology.

For topologies that have more than one Infrastructure, such as a collocated Oracle Internet Directory+OracleAS Metadata Repository and a separate Portal OracleAS Metadata Repository, Oracle Application Server Guard requires that you set the credentials for each system on which an Infrastructure resides before performing any important Oracle Application Server Guard operations, such as instantiate, sync, switchover, and failover. This is actually a two step process in which you must first identify all OracleAS Infrastructure databases on the topology using the set the primary database command for each Infrastructure, then you must set the credentials used to authenticate the Oracle Application Server Guard connections to Oracle Application Server Guard servers on which these Infrastructures reside. The following example illustrates this concept. Assume your production topology and standby topology consists of the following systems with installed Infrastructure and middle tier software applications.

Production topology:

host01 (Identity Management+OracleAS Metadata Repository), host04 (OracleAS Metadata Repository only), host06 (J2EE), host06 (Portal & Wireless)

Standby Topology:

host02 (Identity Management+OracleAS Metadata Repository), host05 (OracleAS Metadata Repository only), host07 (J2EE), host07 (Portal & Wireless)

The following Oracle Application Server Guard set primary database and set asg credentials commands would be required to properly identify the Infrastructures and authenticate Oracle Application Server Guard connections to Oracle Application Server Guard servers prior to performing an instantiate, sync, switchover, or failover operation. Assuming that the Oracle Identity Management+OracleAS Metadata Repository Infrastructure has a service name of orcl and the separate Portal OracleAS Metadata Repository has a service name of asdb.

ASGCTL> set primary database sys/<password>@orcl.us.oracle.com
ASGCTL> set primary database sys/<password>@asdb.us.oracle.com
ASGCTL> set asg credentials host01.us.oracle.com ias_admin/<password>
ASGCTL> set asg credentials host04.us.oracle.com ias_admin/<password>

Note that for a failover operation, these steps would be carried out on the standby topology and are as follows with a change in the host system names:

ASGCTL> set primary database sys/<password>@orcl.us.oracle.com
ASGCTL> set primary database sys/<password>@asdb.us.oracle.com
ASGCTL> set asg credentials host02.us.oracle.com ias_admin/<password>
ASGCTL> set asg credentials host05.us.oracle.com ias_admin/<password>

The Oracle Application Server Guard client must be connected to a Oracle Application Server Guard server before using this command.

An IP address can be used in place of a host name.

Example

The following example sets the Oracle Application Server Guard credentials of host system standbyinfra to all host systems that belong to this topology.

ASGCTL> set asg credentials standbyinfra ias_admin/<password> for topology

set echo

Sets command-echoing on or off in an asgctl script.

Format

set echo on | off

Parameters

on | off: Specifying "on" turns on command-echoing in an asgctl script. Specifying "off" turns off command-echoing in an asgctl script.

Usage Notes

This command is useful when running large asgctl scripts. For example, if the asgctl script has error test cases with comments entered before each test case or before each asgctl command, setting echo on displays the comment before each test case or before each asgctl command that is run to give you an explanation of what the test case is or what asgctl command is about to be run.

This command also works with nested scripts.

Example

The following example is an asgctl script that turns on command-echoing, runs a test case, connects to a Oracle Application Server Guard server, displays detailed information about the topology, then turns echo off, disconnects from the Oracle Application Server Guard server, and exits from the Oracle Application Server Guard client.

> ASGCTL @myasgctltestscript.txt

# myasgctltestscript.txt
# turn on echo
set echo on

# make sure you are not connected
disconnect

# not connected, should get an error message
dump topology

# connect to an ASG server
connect asg prodinfra ias_admin/adminpwd

#display detailed info about the topology
dump topology

#disconnect
disconnect

# turn off echo
echo off
exit

set new primary database

Identifies the OracleAS Infrastructure database on the standby topology as the new primary database preceding a failover operation. This command is only used as part of a failover operation.

Format

set new primary database <username>/<password>@<servicename> [pfile <filename> | spfile <filename>]

Parameters

username/password: User name and password for the database account with sysdba privileges.
servicename: The TNS service name of the OracleAS Infrastructure database. The name must be defined on the OracleAS Infrastructure host system; it does not need to be defined on the Oracle Application Server Guard client host system.
pfile filename: The filename of the primary (OracleAS Infrastructure) database initialization file that will be used when the primary database is started.
spfile filename: The filename of the server (OracleAS Infrastructure) initialization file that will be used when the database is started.

Usage Notes

Before performing a failover operation, you are required to connect to the Infrastructure node of the standby topology and define the new primary database. Once the Oracle Infrastructure database on the standby site is identified as the new primary database, then you can proceed to begin the failover operation.

Example

The following example sets the OracleAS Infrastructure database information for the standby topology as the new primary/production topology preceding a failover operation.

ASGCTL> connect asg standbyinfra ias_admin/adminpwd
Successfully connected to standbyinfra:7890
ASGCTL> set new primary database sys/testpwd@asdb
ASGCTL> failover
.
.
.
ASGCTL>

set noprompt

Sets the noprompt state for user interaction for use in executing commands in an asgctl script.

Format

set noprompt

Parameters

None

Usage Notes

The default value, if supplied, is taken for all interactive prompts. A prompt for a user name and password returns an error message in the noprompt state.

Example

The following example is an asgctl script containing an asgctl set noprompt command part way through the script that thereafter ignores all subsequent interactive prompting.

> ASGCTL @myasgctltestscript.txt

# myasgctltestscript.txt

# connect to an ASG server
connect asg prodinfra ias_admin/adminpwd

# set the primary database
set primary database sys/testpwd@asdb

# discover the production topology
discover topology oidpassword=oidpwd

# set the noprompt state
set noprompt

#display detailed info about the topology
dump topology

#disconnect
disconnect

exit

set primary database

Identifies the OracleAS Infrastructure database on the primary topology.

Format

set primary database <username>/<password>@<servicename> [pfile <filename> | spfile <filename>]

Parameters

username/password: Username and password for the database account with sysdba privileges.
servicename: The TNS service name of the OracleAS Infrastructure database. The name must be defined on the OracleAS Infrastructure host system; it does not need to be defined on the Oracle Application Server Guard client host system.
pfile filename: The filename of the primary (OracleAS Infrastructure) database initialization file that will be used when the primary database is started.
spfile filename: The filename of the server (OracleAS Infrastructure) initialization file that will be used when the database is started.

Usage Notes

You must always set the primary database before performing an instantiate, sync, or switchover operation.

When you set the primary database, Oracle Application Server Guard server logs into and validates the connection to the database.

If a production or standby site has multiple OracleAS Metadata Repository instances installed and you are performing an instantiate, sync, switchover, or failover operation, you must identify all of the OracleAS Metadata Repository instances by performing a set primary database command for each and every OracleAS Metadata Repository instance prior to performing either an instantiate, sync, switchover, or failover operation. In addition, for topologies that have more than one Infrastructure, such as a collocated Oracle Internet Directory+OracleAS Metadata Repository and a separate Portal OracleAS Metadata Repository, Oracle Application Server Guard requires that you set the credentials for each system on which an Infrastructure resides before performing any important Oracle Application Server Guard operations, such as instantiate, sync, switchover, and failover. See set asg credentials for an example.

Oracle Application Server Guard requires the database to have password file authentication. If the database does not have a password file, you must use the orapwd utility to create a password file. Also, set the REMOTE_LOGIN_PASSWORDFILE initialization parameter to EXCLUSIVE.

Example

The following example sets the OracleAS Infrastructure database information for the primary or production topology.

ASGCTL> connect asg prodinfra ias_admin/adminpwd
Successfully connected to prodinfra:7890
ASGCTL> set primary database sys/testpwd@asdb
Checking connection to database asdb
ASGCTL>

The following example sets OracleAS Infrastructure database information for each OracleAS Metadata Repository installed for the primary/production topology prior to a switchover operation.

ASGCTL> connect asg prodinfra ias_admin/adminpwd
Successfully connected to prodinfra:7890
ASGCTL> set primary database sys/testpwd@portal_1
Checking connection to database portal_1
ASGCTL> set primary database sys/testpwd@portal_2
Checking connection to database portal_2
ASGCTL> set primary database sys/testpwd@asdb
Checking connection to database asdb
ASGCTL> discover topology oidpassword=oidpwd
ASGCTL> switchover topology to standbyinfra
.
.
.

set trace

Sets a trace flag on or off to log output to the Oracle Application Server Guard log files.

Format

set trace on | off <traceflags>

Parameters

on | off

Specifying "on" enables tracing. Specifying "off" disables tracing.

traceflags

The traceflags to be enabled. Two or more specified traceflags entries must be separated by a comma (,). The traceflags are as follows:

ALL -- the most extensive tracing information available
DB -- trace information regarding processing in the Oracle Database environment
CLIPBOARD -- trace information regarding clipboard processing
COPY -- trace information regarding file copy processing
FLOW -- trace information regarding work flow processing
HOME -- trace information with regard to Oracle homes
IAS -- trace information regarding processing in Oracle Application Server
IP -- trace information regarding network access and address translation
NET -- trace information regarding network processing
OPMN -- trace information regarding access to OracleAS OPMN calls
RUNCMD -- trace information regarding the running of external commands
SESSION -- trace information regarding session management
TOPOLOGY -- trace information regarding processing of topology information

Usage Notes

This command applies to all hosts that might be involved in an asgctl command during the lifetime of the connection.

The Oracle Application Server Guard client must be connected to a Oracle Application Server Guard server before using this command.

Example

The following example turns on trace for database operations.

ASGCTL> set trace on db

show env

Shows the current environment for the Oracle Application Server Guard server to which the Oracle Application Server Guard client is connected.

Format

show env

Parameters

None.

Usage Notes

None.

Example

The following examples show the environment of the Oracle Application Server Guard server to which the Oracle Application Server Guard client is connected. In the first example, the primary database and new primary database are not yet set on host prodinfra and in the second example, the primary database has already been set on host standbyinfra.

Example 1.

ASGCTL> show env

     ASG Server Connection:
        Host: prodinfra
        Port: 7890

     Primary database: <not set>
     New primary database:  <not set>

Example 2.

ASGCTL> ASGCTL> show env

     ASG Server Connection:
        Host: standbyinfra
        Port: 7890

Gathering information from the database orcl

     Primary database: :
        User: sys
        Service: orcl
        Role: The database role is 
               PHYSICAL STANDBY
            

     New primary database:  <not set>

show operation

Shows all operations on all nodes of the topology to which the Oracle Application Server Guard client is connected for the current session.

Format

show op[eration] [full] [[his]tory]

Parameters

full: For all operations, shows the operation number, the job name, the job owner's user name, the job ID, the time the operation began, the time the operation ended, the elapsed time for the operation, and all tasks belonging to this job.
history: For only operations that are not running, shows the operation number and the job name.

Usage Notes

None.

Example

The following examples show the status of the current operation.

ASGCTL> show operation
*************************************
OPERATION: 19
  Status: running
  Elapsed Time: 0 days, 0 hours, 0 minutes, 28 secs
  TASK: syncFarm
    TASK: backupFarm
      TASK: fileCopyRemote
      TASK: fileCopyRemote
    TASK: restoreFarm
      TASK: fileCopyLocal

The following example shows the history of all operations.

ASGCTL> show op his
*************************************
OPERATION: 7
  Status: success
  Elapsed Time: 0 days, 0 hours, 0 minutes, 0 secs
  TASK: getTopology
    TASK: getInstance
*************************************
OPERATION: 16
  Status: success  Elapsed Time: 0
 days, 0 hours, 0 minutes, 0 secs  TASK: getTopology
    TASK: getInstance
*************************************
OPERATION: 19
  Status: success
  Elapsed Time: 0 days, 0 hours, 1 minutes, 55 secs
  TASK: syncFarm
    TASK: backupFarm
      TASK: fileCopyRemote
      TASK: fileCopyRemote
    TASK: restoreFarm
      TASK: fileCopyLocall

shutdown

Shuts down a running Oracle Application Server Guard server to which the Oracle Application Server Guard client is connected. Use this command only on a host system where OPMN is not running and you are following the procedure to clone an instance or clone a topology.

Format

shutdown [local]

Parameters

local: When specified shuts down the Oracle Application Server Guard server of the local Oracle home of asgctl.

Usage Notes

The Oracle Application Server Guard server must have been started using the asgctl startup command and not the OPMN opmnctl command startproc.

Example

The following example shuts down the Oracle Application Server Guard server on a host system in which OPMN is not running.

> asgctl.sh shutdown

shutdown topology

Shuts down the OracleAS component services across the topology, while Oracle Application Server Guard server and OPMN will continue to run.

Format

shutdown topology

Parameters

None.

Usage Notes

This is a convenient command for shutting down the entire topology. Use the startup topology command to start it up again.

This command will shutdown OracleAS services such as OID, OC4J, WebCache, and so forth.

Example

The following example shuts down the prodinfra production topology.

ASGCTL> shutdown topology
Generating default policy for this operation

prodinfra:7890
    Shutting down each instance in the topology

asmid2:7890 (home /private1/OraHome2/asmid2)
    Shutting down component HTTP_Server
    Shutting down component OC4J
    Shutting down component dcm-daemon
    Shutting down component LogLoader

asmid1:7890 (home /private1/OraHome/asmid1)
    Shutting down component HTTP_Server
    Shutting down component OC4J
    Shutting down component dcm-daemon
    Shutting down component LogLoader

prodinfra:7890 (home /private1/OraHome2/asr1012)
    Shutting down component OID
    Shutting down component HTTP_Server
    Shutting down component OC4J
    Shutting down component dcm-daemon
    Shutting down component LogLoader
ASGCTL>

startup

Starts up an Oracle Application Server Guard server from the asgctl prompt. Use this command only on a host system where OPMN is not running and you are following the procedure to clone an instance or clone a topology.

Format

startup [asg]

Parameters

asg: Optional keyword acronym for Application Server Guard. This parameter has no other meaning other than to show a format similar to the connect asg and set asg credentials commands.

Usage Notes

None.

Example

The following example starts up the Oracle Application Server Guard server on a host system in which OPMN is not running.

> asgctl.sh startup

startup topology

Starts up a shutdown topology by starting up the OracleAS component services across the topology.

Format

startup topology

Parameters

none

Usage Notes

This is a convenient command for starting up the entire topology after it was shut down using the shutdown topology command.

This command will start up OracleAS services such as OID, OC4J, WebCache, and so forth. The startup topology command will perform the equivalent of an opmnctl startup command across each instance of the topology.

Example

The following example starts up the production topology.

ASGCTL> startup topology
Generating default policy for this operation

profinfra:7890
    Starting each instance in the topology

prodinfra:7890 (home /private1/OraHome2/asr1012)
    Executing opmnctl startall command

asmid1:7890 (home /private1/OraHome/asmid1)
    Executing opmnctl startall command

asmid2:7890 (home /private1/OraHome2/asmid2)
    Executing opmnctl startall command
ASGCTL>

stop operation

Stops a specific operation that is running on the server.

Format

stop op[eration] <op #>

Parameters

op #: The number of the operation.

Usage Notes

The number of the operation that is running on the server can be determined from a show operation command.

Example

The following example first shows the running operation (15) on the server and then the stop operation command stops this operation.

ASGCTL> show operation
*************************************
OPERATION: 15
  Status: running
  Elapsed Time: 0 days, 0 hours, 1 minutes, 35 secs
  TASK: instantiateFarm
    TASK: verifyFarm

ASGCTL> stop operation 15

switchover topology

During a scheduled outage of the production site, performs the switchover operation from the production site to the standby site.

Format

switchover topology to <standby_topology_host>[:<port>] [using policy <file>]

Parameters

standby_topology_host

In the Disaster Recovery environment, if this host has a physical hostname, use the physical hostname for the host.

If the host does not have a physical hostname (for example, if it is an Infrastructure host), use its network hostname.

Note:

port

The port number of the standby host system for the Oracle Application Server Guard server in its Oracle home.

using policy <file>

Full path and file specification for the XML policy file.

Usage Notes

On the primary infrastructure system, make sure the emagent process is stopped. Otherwise, you may run into the following error when doing a switchover operation because the emagent process has a connection to the database:

prodinfra: -->ASG_DGA-13051: Error performing a physical standby switchover.
prodinfra: -->ASG_DGA-13052: The primary database is not in the proper state to perform a switchover.  State is "SESSIONS ACTIVE"

On UNIX systems, to stop the emagent process, stop the Application Server Control, which is called iasconsole, as follows:

> <ORACLE_HOME>/bin/emctl stop iasconsole

On UNIX systems, to check to see if there is an emagent process running, do the following:

> ps -ef | grep emagent

On UNIX systems, if after performing the stop iasconsole operation, the emagent process is still running, get its process ID (PID) as determined from the previous ps command and stop it as follows:

> kill -9 <emagent-pid>

On Windows systems, open the Services control panel. Locate the OracleAS10gASControl service and stop this service.

Make sure OracleAS Infrastructure database is running on the primary topology before performing a switchover operation. Also, the OracleAS Infrastructure database information must be set by using the set primary database asgctl command.

The global DNS names are used to direct the switchover. This will be different than the HA naming utilized in the OracleAS Disaster Recovery environment. The discovery mechanism automatically maps the topology to the corresponding peer, based off local name resolution.

As part of the Oracle Application Server Guard switchover operation, an implicit sync topology operation is performed to make sure the topologies are identical. In addition OPMN automatically starts the Oracle Application Server Guard server on the "new" standby Infrastructure node and this server will run indefinitely, and in turn, starts the Oracle Application Server Guard server on the other nodes in the "new" standby topology and each of these is a transient server.

During a switchover operation, the opmn.xml file is copied from the primary site to the standby site. For this reason, the value of the TMP variable must be defined the same in the opmn.xml file on both the primary and standby sites, otherwise this switchover operation will fail with a message that it could not find a directory. Therefore, make sure the TMP variable is defined identically and resolves to the same directory structure on both sites before attempting a switchover operation.

When performing a switchover operation from a primary site with two Oracle Identity Management instances running (im.systemA.us.oracle.com and im.systemB.us.oracle.com) to a standby site representing an asymmetric topology with only one Oracle Identity Management instance running (im.systemA.us.oracle.com), meaning that the other node (im.systemB.us.oracle.com) is to be ignored on the switchover site, the system administrator must not only edit the switchover_policy.xml policy file to indicate that this other node is to be set to Ignore, but the system administrator must also shut down all processes running on that node (im.systemB.us.oracle.com) in order for the switchover operation to be successful.

When performing a switchover operation from a primary site with two middle tiers, for example core1 and core2 instances registered in the Oracle Internet Directory, to a standby site representing an asymmetric topology with only one middle tier core1, the standby site actually has both core1 and core2 middle tiers registered in the Oracle Internet Directory. The switchover_policy.xml policy file is edited to ignore the core2 middle tier that does not exist on the standby site during the switchover operation. However, it should be noted that the Oracle Internet Directory, which is stored in an Oracle database, is identical for both the production site topology and the standby site topology and therefore a core2 middle tier is also shown to be registered in the Oracle Internet Directory on the standby site topology. For this reason, you cannot install to that standby site topology the same core2 middle tier with the hope of making this into a symmetric topology again. This is a strict limitation for switchover operations using asymmetric standby topologies.

When the discover topology command is issued following a switchover operation and the asymmetric standby site topology originally had one or more fewer middle tiers (for example, instA and instB) than there were in the original production site topology (instA, instB, and instC), a warning error message displays for each missing instance of a middle tier (instC, in this case). This warning error message is expected and can be ignored. When a discover topology command is issued following a switchover operation, OracleAS Server Guard reads the Oracle Internet Directory information, which is an exact copy of the original primary site Oracle Internet Directory information on this new primary site (former standby site). Because this Oracle Internet Directory information is identical to the original primary site Oracle Internet Directory information, when OracleAS Server Guard visits the host/home of each instance of these middle tiers to verify their existence, it finds that some do not exist, and issues the warning.

Example

The following example performs a switchover operation to a standby site known by DNS as standbyinfra.

ASGCTL> connect asg prodinfra ias_admin/adminpwd
Successfully connected to prodinfra:7890
ASGCTL> set primary database sys/testpwd@asdb
ASGCTL> switchover topology to standbyinfra
Generating default policy for this operation
prodinfra:7890
    Switchover each instance in the topology to standby topology
prodinfra:7890 (home /private1/OraHome2/asr1012)
    Connecting to the primary database asdb.us.oracle.com
    Gathering information from the primary database asdb.us.oracle.com
    Shutting down each instance in the topology
.
.
.
prodinfra:7890     HA directory exists for instance asr1012.infra.us.oracle.com
asmid2:7890
     HA directory exists for instance asmid2.asmid2.us.oracle.com
asmid1:7890
     HA directory exists for instance asmid1.asmid1.us.oracle.com
standbyinfra:7890
     HA directory exists for instance asr1012.infra.us.oracle.com
asmid2:7890
     HA directory exists for instance asmid2.asmid2.us.oracle.com
asmid1:7890
     HA directory exists for instance asmid1.asmid1.us.oracle.com
prodinfra:7890
    Verifying that the topology is symmetrical in both primary and standby configuration
ASGCTL>

# Command to use if you are using a policy file
# switchover topology to standbyinfra using policy <file>

sync topology

Synchronizes the standby site with the primary site to ensure that the two sites are consistent. The sync topology operation applies database redo logs for OracleAS Infrastructures to the standby site in conjunction with synchronizing external configuration files across the topology.

Format

sync topology to <standby_topology_host>[:<port>] [full | incr[emental]] [using policy <file>]

Parameters

standby_topology_host

In the Disaster Recovery environment, if this host has a physical hostname, use the physical hostname for the host.

If the host does not have a physical hostname (for example, if it is an Infrastructure host), use its network hostname.

Note:

port: The port number of the standby host system for the Oracle Application Server Guard server in its Oracle home.

full | incremental: The synchronization of the standby site with the primary site to make the standby site consistent can be either "full" or "incremental". The default is "incremental". By default, if a full backup has not been performed, an incremental backup operation will not be performed. Instead, a full backup operation will be performed.

using policy <file>: Full path and file specification for the XML policy file.

Usage Notes

By default an incremental synchronization is performed to make the standby site consistent with the primary site, which offers the best performance. However, there may be three circumstances when specifying a full synchronization should be used.

When you want to force a full synchronization to happen, such as synchronizing the standby site completely at a specific point in time (currently) with the primary site.
When you know there are many transactional changes over a short period of time on the primary site that must be synchronized with the secondary site.
When you know that there are a large accumulation of transactional changes over a long period of time on the primary site that must be synchronized with the secondary site.

The sync operation performs an implicit verify operation.

For the sync policy file, by default the success requirement attribute is set to mandatory for all instances.

Example

The following example synchronizes the specified standby site with the coordinating Oracle Application Server Guard server (the primary site). By default the sync mode is incremental.

ASGCTL> connect asg prodinfra ias_admin/adminpwd
Successfully connected to prodinfra:7890
ASGCTL> set primary database sys/testpwd@asdb
Checking connection to database asdb
ASGCTL> sync topology to standbyinfra
Generating default policy for this operation
prodinfra:7890
    Synchronizing each instance in the topology to standby topology
prodinfra:7890 (home /private1/OraHome2/asr1012)
    Starting backup of topology ""
       Backing up and copying data to the standby topology
    Backing up each instance in the topology
    Starting backup of instance "asr1012.infra.us.oracle.com"
    Configuring the backup script
asmid1:7890 (home /private1/OraHome/asmid1)
    Starting backup of instance "asmid1.asmid1.us.oracle.com"
asmid2:7891 (home /private1/OraHome/asmid2)
    Starting backup of instance "asmid2.asmid2.us.oracle.com"
.
.
.
asmid2:7890 (home /private1/OraHome2/asr1012)
    Starting backup/synchronization of database "asdb.us.oracle.com"
    Starting restore/synchronization of database "asdb.us.oracle.com"
    Synchronizing topology completed successfully
ASGCTL>

# Command to use if you are using a policy file
# sync topology to standbyinfra using policy <file>

verify topology

Validates that the primary topology is running and the configuration is valid. If a standby topology is specified, compares the primary topology to which the local host system is a member with the standby topology to validate that they are consistent with one another and conform to the requirements for OracleAS Disaster Recovery.

Format

verify topology [with <host>[:<port>]] [using policy <file>]

Parameters

host

Name of the standby host system. This host system must be a member of the standby topology.

In the Disaster Recovery environment, if this host has a physical hostname, use the physical hostname for the host.

If the host does not have a physical hostname (for example, if it is an Infrastructure host), use its network hostname.

Note:

port

The port number of the host system for the Oracle Application Server Guard server in its Oracle home.

using policy <file>

Full path and file specification for the XML policy file.

Usage Notes

If the host system name is not specified, the topology in which the local host system participates will be verified for local OracleAS Disaster Recovery rules.

If the standby host system name is specified, the topology at the standby site will be verified along with the production topology for both local rules and distributed OracleAS Disaster Recovery rules, and the symmetry between the primary and standby sites is also checked.

For the verify policy file, by default the success requirement attribute is set to optional for all OracleAS homes (middle tier and OracleAS Metadata Repository) and mandatory for the Oracle Internet Directory home.

Example

The following example validates that the primary topology is running and the configuration is valid.

ASGCTL> connect asg ias_admin/iastest2
Successfully connected to prodinfra:7890
ASGCTL> verify topology
Generating default policy for this operation
prodinfra:7890
     HA directory exists for instance asr1012.infra.us.oracle.com
asmid2:7890
     HA directory exists for instance asmid2.asmid2.us.oracle.com
asmid1:7890
     HA directory exists for instance asmid1.asmid1.us.oracle.com
ASGCTL>

The following example validates that the topology to which the local host system is a member is consistent with the standby topology to which the host system standbyinfra is a member.

ASGCTL> connect asg prodinfra ias_admin/adminpwd
Successfully connected to prodinfra:7890
ASGCTL> set primary database sys/testpwd@asdb
Checking connection to database asdb
ASGCTL> verify topology with standbyinfra
Generating default policy for this operation
prodinfra:7890
     HA directory exists for instance asr1012.infra.us.oracle.com
asmid2:7890
     HA directory exists for instance asmid2.asmid2.us.oracle.com
asmid1:7890
     HA directory exists for instance asmid1.asmid1.us.oracle.com
standbyinfra:7890
     HA directory exists for instance asr1012.infra.us.oracle.com
asmid2:7890
     HA directory exists for instance asmid2.asmid2.us.oracle.com
asmid1:7890
     HA directory exists for instance asmid1.asmid1.us.oracle.com
prodinfra:7890
    Verifying that the topology is symmetrical in both primary and standby configuration
ASGCTL>

# Command to use if you are using a policy file
# verify topology using policy <file>

dump farm (Deprecated)

Directs asgctl to write detailed information about the farm to the specified file.

Note:

The dump farm command is deprecated beginning with OracleAS release 10.1.2.0.2. Use the dump topology command, which supports the OracleAS Disaster Recovery topology concept in current and future OracleAS releases.

Format

dump farm [to <file>]

Parameters

to <file>: Name of file on the Oracle Application Server Guard client node where the detailed output is to be written.

Usage Notes

None.

Example

See the dump topology command for an example.

instantiate farm (Deprecated)

Instantiates a farm to a standby site by discovering the current farm definition at the production and standby sites, verifying that each complies with the OracleAS Disaster Recovery rules and restrictions of the current OracleAS software deployed on these systems prior to creation. Also synchronizes the standby site with the primary site so that the primary and standby sites are consistent.

Note:

The instantiate farm to command is deprecated beginning with OracleAS release 10.1.2.0.2. Use the instantiate topology command, which supports the OracleAS Disaster Recovery topology concept in current and future OracleAS releases.

Format

instantiate farm to <standby_farm_host>[:<port>]

Parameters

standby_farm_host

In the Disaster Recovery environment, if this host has a physical hostname, use the physical hostname for the host.

If the host does not have a physical hostname (for example, if it is an Infrastructure host), use its network hostname.

Note:

port

The port number of the Oracle Application Server Guard server in its Oracle home.

Usage Notes

The production local system must be part of an Oracle Notification Server (ONS) farm for the site.

The standby host must be part of an ONS farm for the standby site and must be symmetrical to the farm of the production farm.

Make sure OracleAS Infrastructure database is running on the primary farm before performing an instantiating farm operation. Also, the OracleAS Infrastructure database information must be set by using the set primary database asgctl command.

The global DNS names are used to direct the instantiation. This will be different than the HA naming utilized in the OracleAS Disaster Recovery environment. The discovery mechanism automatically maps the farm to the corresponding peer, based off local name resolution.

Example

See the instantiate topology command for an example.

shutdown farm (Deprecated)

Shuts down a running farm.

Note:

The shutdown farm command is deprecated beginning with OracleAS release 10.1.2.0.2. Use the shutdown topology command, which supports the OracleAS Disaster Recovery topology concept in current and future OracleAS releases.

Format

shutdown farm

Parameters

None.

Usage Notes

This is a convenient command for shutting down the entire farm. Use the startup farm command to start it up again.

Example

See the shutdown topology command for an example.

startup farm (Deprecated)

Starts up a shutdown farm.

Note:

The startup farm command is deprecated beginning with OracleAS release 10.1.2.0.2. Use the startup topology command, which supports the OracleAS Disaster Recovery topology concept in current and future OracleAS releases.

Format

startup farm

Parameters

None

Usage Notes

This is a convenient command for starting up the entire farm after it was shut down using the shutdown farm command.

Example

See the startup topology command for an example.

switchover farm (Deprecated)

During a scheduled outage of the production site, performs the switchover operation from the production site to the standby site.

Note:

The switchover farm to command is deprecated beginning with OracleAS release 10.1.2.0.2. Use the switchover topology command, which supports the OracleAS Disaster Recovery topology concept in current and future OracleAS releases.

Format

switchover farm to <standby_farm_host>[:<port>]

Parameters

standby_farm_host

Name of the farm host system. This parameter is required because it directs the coordinating Oracle Application Server Guard server instance to discover the instances that make up the standby site. This host system must be a member of the standby farm.

In the Disaster Recovery environment, if this host has a physical hostname, use the physical hostname for the host.

If the host does not have a physical hostname (for example, if it is an Infrastructure host), use its network hostname.

Note:

port

The port number of the standby host system for the Oracle Application Server Guard server in its Oracle home.

Usage Notes

On the primary Infrastructure system, make sure the emagent process is stopped. Otherwise, you may run into the following error when doing a switchover operation because the emagent process has a connection to the database:

prodinfra: -->ASG_DGA-13051: Error performing a physical standby switchover.
prodinfra: -->ASG_DGA-13052: The primary database is not in the proper state to perform a switchover.  State is "SESSIONS ACTIVE"

On UNIX systems, to stop the emagent process, stop the Application Server Control, which is called iasconsole, as follows:

> <ORACLE_HOME>/bin/emctl stop iasconsole

On UNIX systems, to check to see if there is an emagent process running, do the following:

> ps -ef | grep emagent

On UNIX systems, if after performing the stop iasconsole operation, the emagent process is still running, get its process ID (PID) as determined from the previous ps command and stop it as follows:

> kill -9 <emagent-pid>

On Windows systems, open the Services control panel. Locate the OracleAS10gASControl service and stop this service.

The production local system must be part of an Oracle Notification Server (ONS) farm for the site.

The standby host must be part of an ONS farm for the standby site and must be symmetrical to the farm of the production farm.

Make sure OracleAS Infrastructure database is running on the primary farm before performing a switchover operation. Also, the OracleAS Infrastructure database information must be set by using the set primary database asgctl command.

The global DNS names are used to direct the switchover. This will be different than the HA naming utilized in the OracleAS Disaster Recovery environment. The discovery mechanism automatically maps the farm to the corresponding peer, based off local name resolution.

As part of the Oracle Application Server Guard switchover operation, an implicit sync farm operation is performed to make sure the farms are identical. In addition, OPMN automatically starts the Oracle Application Server Guard server on the "new" standby Infrastructure node and this server will run indefinitely. In turn, it starts the Oracle Application Server Guard server on the other nodes in the "new" standby farm and each of these is a transient server.

Example

See the switchover topology command for an example.

sync farm (Deprecated)

Note:

The sync farm to command is deprecated beginning with OracleAS release 10.1.2.0.2. Use the sync topology command, which supports the OracleAS Disaster Recovery topology concept in current and future OracleAS releases.

Format

sync farm to <standby_farm_host>[:<port>] [full | incr[emental]]

Parameters

standby_farm_host

Name of the standby site host system. This parameter is required because it directs the coordinating Oracle Application Server Guard server instance to discover the instances that make up the standby site. This host system must be a member of the standby farm.

In the Disaster Recovery environment, if this host has a physical hostname, use the physical hostname for the host.

If the host does not have a physical hostname (for example, if it is an Infrastructure host), use its network hostname.

Note:

port: The port number of the standby host system for the Oracle Application Server Guard server in its Oracle home.

full | incremental: The synchronization of the standby site with the primary site to make the standby site consistent can be either "full" or "incremental". The default is "incremental". By default, if a full backup has not been performed, an incremental backup operation will not be performed. Instead, a full backup operation will be performed.

Usage Notes

By default sync_mode is incremental and offers the best performance. However, there may be three circumstances when specifying a sync_mode of full should be used.

When you want to force a full synchronization to happen, such as synchronizing the standby site completely at a specific point in time (currently) with the primary site.
When you know there are many transactional changes over a short period of time on the primary site that must be synchronized with the secondary site.
When you know that there is a large accumulation of transactional changes over a long period of time on the primary site that must be synchronized with the secondary site.

Example

See the sync topology command for an example.

verify farm (Deprecated)

Validates that the primary farm is running and the configuration is valid. If a standby farm is specified, compares the primary farm to which the local host system is a member with the standby farm to validate that they are consistent with one another and conform to the requirements for OracleAS Disaster Recovery.

Note:

The verify farm command is deprecated beginning with OracleAS release 10.1.2.0.2. Use the verify topology command, which supports the OracleAS Disaster Recovery topology concept in current and future OracleAS releases.

Format

verify farm [with <host>[:<port>]]

Parameters

host

Name of the standby host system. This host system must be a member of the standby farm.

In the Disaster Recovery environment, if this host has a physical hostname, use the physical hostname for the host.

If the host does not have a physical hostname (for example, if it is an Infrastructure host), use its network hostname.

Note:

port

The port number of the Oracle Application Server Guard server in its Oracle home.

Usage Notes

If the host system name is not specified, the farm in which the local host system participates will be verified for local OracleAS Disaster Recovery rules.

If the standby host system name is specified, the farm at the standby site will be verified along with the production farm for both local rules and distributed OracleAS Disaster Recovery rules, and the symmetry between the primary and standby sites is also checked.

Example

See the verify topology command for an example.