Oracle® Application Server High Availability Guide 10g Release 3 (10.1.3.2.0) Part Number B32201-01 |
|
|
View PDF |
This chapter contains reference information describing the asgctl commands. Table 6-1 summarizes all the asgctl commands. Table 6-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 6-1 Summary of asgctl Commands
Command | Description |
---|---|
|
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. |
|
Invokes the OracleAS Guard client command-line utility asgctl. On UNIX systems, |
|
Clones a single production instance to a standby system. |
|
Clones two or more production middle tier instances to standby middle tier systems. |
|
Connects the OracleAS Guard client to the OracleAS Guard server. |
|
Creates the standby database on the remote host system. |
|
Disconnects the OracleAS Guard client from the OracleAS Guard server. |
|
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. |
|
Discovers the topology within the farm for a site when Oracle Internet Directory is not available; in this case, OracleAS Guard server uses OPMN to discover the topology within the farm. |
|
Directs OracleAS 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. |
|
Directs the OracleAS Guard server to write detailed information about the topology to the screen or if specified, to a file. |
|
Disconnects the OracleAS Guard client from any existing connections and exits the OracleAS Guard client. This has the same effect as the quit command. |
|
During an unscheduled outage of the production site, the standby site becomes the production site. |
|
Displays help information at the command line. |
|
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. |
|
Disconnects the OracleAS Guard client from any existing connections and exits the OracleAS Guard client. This has the same effect as the exit command. |
|
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. |
|
Remotely executes a script or program that resides in any home where OracleAS Guard is installed. |
|
Sets the credentials used to authenticate the OracleAS Guard client connections to OracleAS Guard servers and connections between OracleAS Guard servers to a specific host. |
|
Sets command-echoing on or off in an asgctl script. |
|
Identifies the OracleAS Infrastructure database on the standby topology as the new primary OracleAS Infrastructure database. |
|
Sets the noprompt state in an asgctl script in which all interactive prompts are thereafter ignored. |
|
Identifies the OracleAS Infrastructure database on the primary topology. |
|
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 OracleAS Guard log files. |
|
Shows the current environment of the OracleAS Guard server to which the OracleAS Guard clients is connected. |
|
Shows the current operation. |
|
Shuts down the OracleAS 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. |
|
Shuts down a running topology. |
|
Starts up the OracleAS 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. |
|
Starts up a shutdown topology. |
|
Stops the specified operation. |
|
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. |
|
Synchronizes the standby site with the primary site so that the primary and standby sites are consistent. |
|
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 6-2 Summary of Deprecated asgctl Commands
Command | Description |
---|---|
|
Directs the OracleAS Guard server to write detailed information about the farm to the screen or if specified, to a file. |
|
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. |
|
Shuts down a running farm. |
|
Starts up a shutdown farm. |
|
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. |
|
Synchronizes the standby site with the primary site so that the primary and standby sites are consistent. |
|
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. |
This section describes information that is common to OracleAS 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 OracleAS Guard client must be connected to an OracleAS Guard server when you issue any asgctl command with the exception of startup and shutdown commands.
The OracleAS 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.
OracleAS Guard Server Information
The OracleAS Guard server must be started on the standby host system (<standby_topology_host>
. The OracleAS Guard server can be stopped and started using the opmnctl command-line Utility as follows:
On UNIX systems: <ORACLE_HOME>/opmn/bin/opmnctl startproc ias-component=ASG On Windows systems: <ORACLE_HOME>\opmn\bin\opmnctl stopproc ias-component=ASG
This section describes information that is specific to a small set of OracleAS Guard operations, such as instantiate, sync, failover, switchover, dump topology, discover topology, clone topology, verify topology, setting the primary database, and setting asg credentials.
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.
Before performing any OracleAS Guard operations, you must shut down the emagents. This operation is required for OracleAS 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 OracleAS 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 OracleAS Guard operations as previously described.
OracleAS Guard requires that you set the credentials for any OracleAS Guard server system in the topology that has different credentials from the OracleAS Guard server to which you are connected before performing any important OracleAS 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.
OracleAS 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 OracleAS Guard 10.1.2 server (from either an OracleAS 10.1.2 or 10.1.3 home) and perform a discover topology command. OracleAS 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 OracleAS 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 OracleAS 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, OracleAS 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.xm
l, 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 5.7, "Dumping Policy Files and Using Policy Files With Some asgctl Commands" for more information and an example of an XML policy file.
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 6.2.1.1, "Special Considerations for Running Instantiate and Failover Operations in CFC Environments" and Section 6.2.1.3, "Special Considerations for Running a Switchover Operations 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, switchover, or failover operation.
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 an 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 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.
When performing an instantiate operation, OracleAS 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 OracleAS 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 OracleAS 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.
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.
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 an 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 instantiate, switchover, or failover operation completes).
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.
See Section 5.18, "Special Considerations for Some OracleAS Metadata Repository Configurations" and Section 5.19, "Special Considerations for OracleAS Disaster Recovery Environments" for information describing some additional special considerations for OracleAS Disaster Recovery environments.
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.
Format
add instance <instance_name> on <instance_host> [to topology]
Parameters
The name of the instance to be added to the topology file.
The name of the host on which this instance is installed. In the DR environment, if this host has an alias name or has a virtual hostname, then the virtual hostname must be used because it is this value that is placed in the topology file.
A keyword, that if present in the command line, directs OracleAS Guard to propagate the updated topology file to all instances in the Disaster Recovery production environment. Any OracleAS 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 OracleAS Guard server to which the OracleAS 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 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 6.2, "Information Specific to a Small Set of OracleAS 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 5.9, "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.2.0.2 Topology" for a use case. See Section 6.2, "Information Specific to a Small Set of OracleAS Guard Commands" for more information about topology files.
This command is also useful for supporting mixed topologies for any OracleAS release from Release 9.0.4 upwards through Release 10.1.3. The only requirement is that the Release 10.1.3 OracleAS Guard standalone kit must be installed on all systems in your Release 9.0.4 Disaster Recovery environment. See Chapter 8, "OracleAS Disaster Recovery Site Upgrade Procedure" for more information.
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
Invokes the OracleAS 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
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>
Clones a single production instance to a standby system.
Format
clone instance <instance> to <standby_topology_host> [no standby]
Parameters
The name of the instance.
The name of the standby topology host to which the instance is to be cloned.
A keyword, that if present in the command-line, directs OracleAS Guard to clone the instance without setting up the instances in Disaster Recovery (no Data Guard). In a MR home only, an instantiate operation would normally be done, but in this case it is not performed.
Usage Notes
This command is useful for cloning a production instance on a middle tier to a standby middle tier host system. The clone instance operation eliminates the task of having to install the Oracle instance on the standby middle tier system and perform an instantiate operation.
The production instance to be cloned cannot exist on the standby system.
The following are prerequisites for performing the clone instance operation to the standby site system
The OracleAS Guard standalone kit must be installed on the standby system.
Backup and Restore must be installed in the OracleAS Guard home on the standby system
A Java development kit with its jar utility must be installed on the standby system
For Windows systems, the services kit (sc.exe
) must be installed on the standby system
When the no standby
keyword is specified in the command-line, the topology entry (<topology> </topology>) containing the entries <nodes list = "nodes"/>, <discover list = "nodes"/>, and <gateway list = "nodes"/> is removed from the opmn.xml
file so as not to conflict with the primary configuration. Normally, a switchover or failover operation rewrites this topology entry back into the opmn.xml
file; but because neither operation occurred, the opmn.xml
file on the standby site will be missing this information.
See Section 5.10, "OracleAS 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 (UNIX systems only) and clone steps.
Note:
For OracleAS Disaster Recovery release 10.1.2.0.2 on Windows systems, see the pre-clone and post-clone steps in this same section in the Oracle Application Server High Availability Guide in the OracleAS Release 10.1.2.0.2 documentation set.Pre-Clone Steps (For UNIX Systems Only)
For each instance on the production and standby sites, perform the following steps:
Log in as su - root.
CD to the instance home.
Shut down any OracleAS Guard servers.
> <ORACLE HOME>/opmn/bin/opmnctl stopproc ias-component=ASG
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
Invoke asgctl and issue the startup command.
> asgctl.sh startup
Log out as root on UNIX systems.
Clone Steps
From any instance on the production site, perform the following steps:
Log in as user (non root user on UNIX systems).
CD to the production instance home.
Invoke asgctl and run the clone instance command to clone the instance to the standby topology host system.
Note:
In the command output, you will see a number of connect messages. This is normal as the OracleAS Guard server is recycled during these operations.Log out of the system.
Note:
If OracleAS Guard does not run as root on UNIX systems, the user will be prompted by the OracleAS 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 systems back to where they were before you started the clone instance operation. At this point you could invoke asgctl, connect to a production system, discover the topology, and then perform a verify operation to determine whether the production and standby topologies were 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 topology host system 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 any production system. b. CD to any production instance home. c. Invoke asgctl and perform the clone instance command. > asgctl.sh Application Server Guard: Release 10.1.3.0.0(c) Copyright 2004, 2005 Oracle Corporation. All rights reserved 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 prodoc4j2 to asmid2 Generating default policy for this operation . . . ASGCTL> disconnect ASGCTL> exit > d. Log off the system
Clones two or more production middle tier instances to standby middle tier systems.
Format
clone topology to <standby_topology_host> [using policy <file>] [no standby]
Parameters
The name of the standby topology host system.
Full path and file specification for the XML policy file.
A keyword, that if present in the command-line, directs OracleAS Guard to clone the instance without setting up the instances in Disaster Recovery (no Data Guard). In a MR home only, an instantiate operation would normally be done, but in this case it is not performed.
Usage Notes
This command is useful for cloning two or more production instances on middle tier systems to a standby middle tier host system. The clone topology operation eliminates the task of having to install these Oracle instances on the standby middle tier systems and perform an instantiate operation.
As part of the clone topology operation, the instances are cloned and the OracleAS Metadata Repository is instantiated; however for a OracleAS Metadata Repository configuration created using OracleAS Metadata Repository Creation Assistant, no instantiate operation is performed.
The production instances to be cloned cannot exist on the standby systems.
The following are prerequisites for performing the clone topology operation to standby site systems.
The OracleAS Guard standalone kit must be installed on each standby system
Backup and Restore must be installed on each OracleAS Guard home on each standby system
A Java development kit with its jar utility must be installed on each standby system
For Windows systems only, the services kit (sc.exe
) must be installed on each standby system
When the no standby
keyword is specified in the command-line, the topology entry (<topology> </topology>) containing the entries <nodes list = "nodes"/>, <discover list = "nodes"/>, and <gateway list = "nodes"/> is removed from the opmn.xml
file so as not to conflict with the primary configuration. Normally, a switchover or failover operation rewrites this topology entry back into the opmn.xml
file; but because neither operation occurred, the opmn.xml
file on the standby site will be missing this information.
See Section 5.10, "OracleAS 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 (UNIX systems only) and clone steps.
Note:
For OracleAS Disaster Recovery release 10.1.2.0.2 on Windows systems, see the pre-clone and post-clone steps in this same section in the Oracle Application Server High Availability Guide in the OracleAS Release 10.1.2.0.2 documentation set.Pre-Clone Steps (For UNIX Systems Only)
For each instance on the production and standby sites, perform the following steps:
Log in as su - root.
CD to the instance home.
Shut down any OracleAS Guard servers.
> <ORACLE HOME>/opmn/bin/opmnctl stopproc ias-component=ASG
On UNIX systems only: 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
Invoke asgctl and issue the startup command.
> asgctl.sh startup
Log out as root on UNIX systems.
Clone Steps
From any instance on the production site, perform the following steps:
Log in as user (non root user on UNIX systems).
CD to any production instance home.
Invoke asgctl and run the clone topology command to clone the topology to the standby topology host system.
Note:
In the command output, you will see a number of connect messages. This is normal as the OracleAS Guard server is recycled during these operations.Log out of the system.
Note:
If OracleAS Guard does not run as root on UNIX systems, the user will be prompted by the OracleAS 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 topology operation and brings the systems back to where they were before you started the clone topology operation. At this point you could invoke asgctl, connect to a production system, discover the topology, and then perform a verify operation to determine whether the production and standby topologies were valid and consistent with one another as you would expect them to be.
See Section 6.1, "Information Common to OracleAS Guard asgctl Commands" and Section 6.2, "Information Specific to a Small Set of OracleAS Guard Commands" for more information.
Example
The command in the following example results in the OracleAS Guard client cloning the topology to the standby topology host system standbyinfra.
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 any production system. b. CD to any production instance Oracle home. c. Invoke asgctl and perform the clone instance command. > asgctl.sh Application Server Guard: Release 10.1.3.0.0(c) Copyright 2004, 2005 Oracle Corporation. All rights reserved 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 topology to standbyinfra Generating default policy for this operation . . . # Command to use if you are using a policy file # clone topology to standbyinfra using policy <file> . . . ASGCTL> disconnect ASGCTL> exit > d. Log off the system
Connects the OracleAS Guard client to the OracleAS Guard server on a system on which Oracle Application Server services are running.
Format
connect asg [<host-name>[:<port>]] <ias_administrative_account>/<password>
Parameters
Name of the host system for the OracleAS Guard server to which you want the OracleAS Guard client to connect. This OracleAS Guard server will be the coordinating server for all operations performed on the systems being configured. The host name is optional if the OracleAS Guard client and OracleAS Guard server are on the same node.
The port number of the OracleAS Guard server in its Oracle home.
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 beoc4jadmin
and the password for the oc4jadmin
account created during the Oracle Application Server 10.1.3 installation.Usage Notes
The OracleAS Guard client system must have network access to the OracleAS Guard host system specified with the host-name parameter.
The OracleAS 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 OracleAS Guard client connecting to the OracleAS Guard server running on a host named prodinfra using the user name and password ias_admin
and adminpwd, respectively.
ASGCTL> connect asg prodinfra ias_admin/adminpwd Successfully connected to prodinfra:7890
Creates the standby database on the remote host system.
Format
create standby database <database_name> on <remote_host>
Parameters
Primary database unique name used to create the standby database on the remote host system.
Name of the host system on which the standby database is to be created.
Usage Notes
Oracle software and OracleAS 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
Users should use this command sparingly and only as needed.
Oracle recommends that you shut down the database on the standby site if it is up and running before issuing the asgctl create standby database
command; otherwise, the following error is returned:
ASG_DGA-12500: Standby database instance "<instance_name>" already exists on host "<hostname>"
For Windows only, Oracle recommends that you run the following command on the standby database site before executing the create standby database command:
$ORACLE_HOME\bin\oradim -delete -sid <Oracle DB SID>
In a CRS environment, CRS is configured to bring up the database automatically upon failure. However, this automatic online feature of CRS must be disabled on all Oracle RAC instances during Oracle AS 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 CRS 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 = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = 140.87.23.35)(PORT = 1521)) ) (CONNECT_DATA = (SERVER = DEDICATED) (SERVICE_NAME = orcl2) ) )
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 OracleAS 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
Disconnects the OracleAS Guard client from the OracleAS Guard server to which it is currently connected.
Format
disconnect
Usage Notes
The OracleAS Guard client must be connected to a OracleAS Guard server when you issue this command.
Example
The command in the following example disconnects the OracleAS Guard client from the OracleAS Guard server to which it is currently connected.
ASGCTL> disconnect ASGCTL>
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
Name of the host system where Oracle Internet Directory is installed.
The port number of the host system where Oracle Internet Directory and Secure Sockets Layer (SSL) is installed.
The Oracle Internet Directory user name.
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 OracleAS 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 OracleAS 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.
See Section 6.1, "Information Common to OracleAS Guard asgctl Commands" and Section 6.2, "Information Specific to a Small Set of OracleAS Guard Commands" for more information.
Example
The command in the following example discovers all the 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.
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>
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 OracleAS Guard client must be connected to a OracleAS Guard server when you issue this command.
See Section 6.2, "Information Specific to a Small Set of OracleAS Guard Commands" for more information about topology files.
Example
The command in the following example for a special case in which Oracle Internet Directory is not available, uses OPMN to discover the application server topology within a farm of the OracleAS Guard server to which the OracleAS 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>
Directs OracleAS 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 OracleAS 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>
Directs asgctl to write detailed information about the topology to the specified file.
Format
dump topology [to <file>] [using policy <file>]
Parameters
Name of file on the OracleAS Guard client node where the detailed output is to be written.
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>
Disconnects from any existing connections to OracleAS Guard servers and exits from the OracleAS Guard client.
Format
exit
Parameters
Usage Notes
None.
Example
ASGCTL> exit >
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
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.
See Section 6.1, "Information Common to OracleAS Guard asgctl Commands" and Section 6.2, "Information Specific to a Small Set of OracleAS Guard Commands" for more information.
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>
Displays help information.
Format
help [<command>]
Parameters
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>
Instantiates a topology to a standby site by establishing the relationship between standby and production instances, mirroring the configuration, creating the standby Infrastructure, and then synchronizing the standby site with the primary site.
Format
instantiate topology to <standby_topology_host>[:<port>] [with cloning] [using policy <file>]
Parameters
Name of the standby host system. This parameter is required because it directs the coordinating OracleAS Guard server instance to discover the instances that make up the standby site. This host system must be a member of the standby topology.
The port number of the OracleAS Guard server in its Oracle home.
A directive to perform an instantiation operation using cloning.
Full path and file specification for the XML policy file.
Usage Notes
Make sure OracleAS Infrastructure database is running on the primary topology before performing an instantiate topology 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 topology to the corresponding peer, based off local name resolution.
The instantiate operation performs an implicit verify operation.
For the instantiate policy file, by default the success requirement attribute is set to mandatory for all instances.
See Section 6.1, "Information Common to OracleAS Guard asgctl Commands" and Section 6.2, "Information Specific to a Small Set of OracleAS Guard Commands" for more information.
Example
The following example instantiates a standby topology by attaching the coordinating OracleAS 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>
Instructs the OracleAS Guard client to disconnect from any existing connections and exit from asgctl.
Format
quit
Parameters
Usage Notes
None.
Example
The following example exits from asgctl.
ASGCTL> quit >
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
The name of the instance to be removed from the topology file.
A keyword, that if present in the command line, directs OracleAS Guard to propagate the updated topology file to all instances in the Disaster Recovery production environment. Any OracleAS 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 OracleAS Guard server to which the OracleAS 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 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 6.2, "Information Specific to a Small Set of OracleAS 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 5.9, "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.2.0.2 Topology" for a use case. See Section 6.2, "Information Specific to a Small Set of OracleAS Guard Commands" for more information about topology files.
This command is also useful for supporting mixed topologies for any OracleAS release from Release 9.0.4 upwards through Release 10.1.3. The only requirement is that the Release 10.1.3 OracleAS Guard standalone kit must be installed on all systems in your Release 9.0.4 Disaster Recovery environment. See Chapter 8, "OracleAS Disaster Recovery Site Upgrade Procedure" for more information.
Example
The following command in the example removes from the local topology file an instance named oc4j1.
ASGCTL> remove instance oc4j1
Remotely executes a script or program that resides in any home where OracleAS 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
A keyword, that if present in the command line, directs OracleAS Guard to perform the run operation across the topology.
Full path and file specification for the XML policy file.
The name as a command string of the script or binary program to be executed.
A keyword, that if present in the command line, directs OracleAS Guard to perform the run operation at the specified instance.
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 OracleAS 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 OracleAS 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, OracleAS Guard will verify that the file specified in the command string exists in the Oracle home where the OracleAS Guard server is running before executing the script or program. The output of the script is echoed back to the asgctl console.
Example
For Oracle RAC Disaster Recovery deployments, shutdown all instances prior to the switchover operation. To do this, create a script and then execute the script using the run command. See Section 5.12.1.1, "Scheduled Outages", step 5 for details. The following command in this example assumes a script is written and then remotely runs the script shutdown_asdb_instance.sh
for the instance named asdb. This script utilizes the ASG distributed ASG scripting capabilities and allows a system administrator to perform the switchover operation from within the asgctl utility.
ASGCTL> run at instance asdb shutdown_asdb_instance.sh
Sets the credentials used to authenticate the OracleAS Guard connections to OracleAS Guard servers.
Format
set asg credentials <host>[:<port>] <ias_administrative_account>/<password> [for farm] [for topology]
Parameters
Name of the host system to which the credentials apply. When OracleAS Guard connects to that host, it will use these credentials.
The port number of the OracleAS Guard server in its Oracle home.
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.
A keyword, that if present in the command line, directs OracleAS Guard to set the credentials for all of the host systems that belong to the same farm as the local host system.
A keyword, that if present in the command line, directs OracleAS 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 OracleAS Guard server needs to connect to another OracleAS Guard server. However, there may be cases where you want to use different credentials for a specific server. This command allows 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, OracleAS Guard requires that you set the credentials for each system on which an Infrastructure resides before performing any important OracleAS 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 OracleAS Guard connections to OracleAS 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 OracleAS Guard set primary database and set asg credentials commands would be required to properly identify the Infrastructures and authenticate OracleAS Guard connections to OracleAS 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 OracleAS Guard client must be connected to a OracleAS Guard server before using this command.
An IP address can be used in place of a host name.
See Section 6.1, "Information Common to OracleAS Guard asgctl Commands" and Section 6.2, "Information Specific to a Small Set of OracleAS Guard Commands" for more information.
Example
The following example sets the OracleAS 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
Sets command-echoing on or off in a asgctl script.
Format
set echo on | off
Parameters
Specifying "on" turns on command-echoing in a asgctl script. Specifying "off" turns off command-echoing in a 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 a asgctl script that turns on command-echoing, runs a test case, connects to a OracleAS Guard server, displays detailed information about the topology, then turns echo off, disconnects from the OracleAS Guard server, and exits from the OracleAS 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
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
User name and password for the database account with sysdba privileges.
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 OracleAS Guard client host system.
The filename of the primary (OracleAS Infrastructure) database initialization file that will be used when the primary database is started.
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>
Sets the noprompt state for user interaction for use in executing commands in an asgctl script.
Format
set noprompt
Parameters
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
Identifies the OracleAS Infrastructure database on the primary topology.
Format
set primary database <username>/<password>@<servicename> [pfile <filename> | spfile <filename>]
Parameters
User name and password for the database account with sysdba privileges.
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 OracleAS Guard client host system.
The filename of the primary (OracleAS Infrastructure) database initialization file that will be used when the primary database is started.
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, OracleAS 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, OracleAS Guard requires that you set the credentials for each system on which an Infrastructure resides before performing any important OracleAS Guard operations, such as instantiate, sync, switchover, and failover. See set asg credentials for an example.
OracleAS 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
.
See Section 6.1, "Information Common to OracleAS Guard asgctl Commands" and Section 6.2, "Information Specific to a Small Set of OracleAS Guard Commands" for more information.
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 . . .
Sets a trace flag on or off to log output to the OracleAS Guard log files.
Format
set trace on | off <traceflags>
Parameters
Specifying "on" enables tracing. Specifying "off" disables tracing.
The traceflags to be enabled. Two or more specified traceflags entries must be separated by a comma (,). The traceflags are as follows:
DB -- trace information regarding processing in the Oracle Database environment
HOME -- trace information with regard to Oracle homes
IAS -- trace information regarding processing in Oracle Application Server
OPMN -- trace information regarding access to OracleAS OPMN calls
IP -- trace information regarding network access and address translation
CLIPBOARD -- trace information regarding clipboard processing
COPY -- trace information regarding file copy processing
FLOW -- trace information regarding work flow processing
NET -- trace information regarding network processing
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 a asgctl command during the lifetime of the connection.
The OracleAS Guard client must be connected to a OracleAS Guard server before using this command.
Example
The following example turns on trace for database operations.
ASGCTL> set trace on db
Shows the current environment for the OracleAS Guard server to which the OracleAS Guard client is connected.
Format
show env
Parameters
None.
Usage Notes
None.
Example
The following examples show the environment of the OracleAS Guard server to which the OracleAS 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>
Shows all operations on all nodes of the topology to which the OracleAS Guard client is connected for the current session.
Format
show op[eration] [full] [[his]tory]
Parameters
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.
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
Shuts down a running OracleAS Guard server to which the OracleAS 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
When specified shuts down the OracleAS Guard server of the local Oracle home of asgctl.
Usage Notes
The OracleAS 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 OracleAS Guard server on a host system in which OPMN is not running.
> asgctl.sh shutdown
Shuts down the OracleAS component services across the topology, while OracleAS 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>
Starts up an OracleAS 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
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 shuts down the OracleAS Guard server on a host system in which OPMN is not running.
> asgctl.sh startup
Starts up a shutdown topology by starting up the OracleAS component services across the topology.
Format
startup topology
Parameters
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>
Stops a specific operation that is running on the server.
Format
stop op[eration] <op #>
Parameters
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
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
Name of the standby host system. This parameter is required because it directs the coordinating OracleAS Guard server instance to discover the instances that make up the standby site. This host system must be a member of the standby topology.
The port number of the standby host system for the OracleAS Guard server in its Oracle home.
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 OracleAS Guard switchover operation, an implicit sync topology operation is performed to make sure the topologies are identical. In addition OPMN automatically starts the OracleAS Guard server on the "new" standby Infrastructure node and this server will run indefinitely, and in turn, starts the OracleAS Guard server on the other nodes in the "new" standby topology and each of these is a transient server.
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.
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.machineA.us.oracle.com and im.machineB.us.oracle.com) to a standby site representing an asymmetric topology with only one Oracle Identity Management instance running (im.machineA.us.oracle.com), meaning that the other node (im.machineB.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.machineB.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 to 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.
See Section 6.1, "Information Common to OracleAS Guard asgctl Commands" and Section 6.2, "Information Specific to a Small Set of OracleAS Guard Commands" for more information.
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>
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
Name of the standby site host system. This parameter is required because it directs the coordinating OracleAS Guard server instance to discover the instances that make up the standby site. This host system must be a member of the standby topology.
The port number of the standby host system for the OracleAS Guard server in its Oracle home.
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.
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.
See Section 6.1, "Information Common to OracleAS Guard asgctl Commands" and Section 6.2, "Information Specific to a Small Set of OracleAS Guard Commands" for more information.
Example
The following example synchronizes the specified standby site with the coordinating OracleAS 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>
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
Name of the standby host system. This host system must be a member of the standby topology.
The port number of the host system for the OracleAS Guard server in its Oracle home.
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.
See Section 6.1, "Information Common to OracleAS Guard asgctl Commands" and Section 6.2, "Information Specific to a Small Set of OracleAS Guard Commands" for more information.
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>
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
Name of file on the OracleAS Guard client node where the detailed output is to be written.
Usage Notes
None.
Example
See the dump topology command for an example.
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
Name of the standby host system. This parameter is required because it directs the coordinating OracleAS Guard server instance to discover the instances that make up the standby site. This host system must be a member of the standby farm.
The port number of the OracleAS 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.
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.
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.
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
Name of the farm host system. This parameter is required because it directs the coordinating OracleAS Guard server instance to discover the instances that make up the standby site. This host system must be a member of the standby farm.
The port number of the standby host system for the OracleAS 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 OracleAS Guard switchover operation, an implicit sync farm operation is performed to make sure the farms are identical. In addition, OPMN automatically starts the OracleAS Guard server on the "new" standby Infrastructure node and this server will run indefinitely. In turn, it starts the OracleAS 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.
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.
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
Name of the standby site host system. This parameter is required because it directs the coordinating OracleAS Guard server instance to discover the instances that make up the standby site. This host system must be a member of the standby farm.
The port number of the standby host system for the OracleAS Guard server in its Oracle home.
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.
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
Name of the standby host system. This host system must be a member of the standby farm.
The port number of the OracleAS 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.