| Oracle® Application Server High Availability Guide 10g (10.1.4.0.1) Part Number B28186-01 |
|
|
View PDF |
| Oracle® Application Server High Availability Guide 10g (10.1.4.0.1) Part Number B28186-01 |
|
|
View PDF |
This chapter contains reference information describing the asgctl commands. Table 12-1 summarizes all the asgctl commands. Table 12-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 12-1 Summary of asgctl Commands
| Command | Description |
|---|---|
|
|
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. |
|
|
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. |
|
|
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 12-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
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=DSA On Windows systems: <ORACLE_HOME>\opmn\bin\opmnctl stopproc ias-component=DSA
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.
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.
If you want to use a policy file, edit the contents of the XML policy file to define by instance the domain of execution operations that are permitted for any one of these asgctl commands (clone topology, dump topology, failover, instantiate topology, switchover topology, sync topology, and verify topology). Each instance list entry in this XML policy file (clone_policy.xml, dump_policy.xml, failover_policy.xml, instantiate_policy.xml, switchover_policy.xml, sync_policy.xml, and verify_policy.xml) logically tags a production-standby peer combination with a particular attribute that defines the success requirement for the commands successful operation. See Section 11.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 Oracle Backup and Recovery Tool 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 12.2.1.1, "Special Considerations for Running Instantiate and Failover Operations in CFC Environments" and Section 12.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 Oracle Backup and Recovery Tool 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 Oracle Backup and Recovery Tool 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 11.14, "Special Considerations for Some OracleAS Metadata Repository Configurations" and Section 11.15, "Special Considerations for OracleAS Disaster Recovery Environments" for information describing some additional special considerations for OracleAS Disaster Recovery environments.
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.2.0.2(c) Copyright 2004, 2005 Oracle Corporation. All rights reserved ASGCTL>
Clones a single production instance to a standby system.
Format
clone instance <instance> to <standby_topology_host>
Parameters
The name of the instance.
The name of the standby topology host to which the instance is to be cloned.
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
See Section 11.8, "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, clone, and post-clone steps.
Pre-Clone Steps
For each instance on the production and standby sites, perform the following steps:
Log in as su - root on UNIX systems or as Administrator on Windows systems.
CD to the instance home.
Shut down any OracleAS Guard servers.
On UNIX systems: > <ORACLE HOME>/opmn/bin/opmnctl stopproc ias-component=DSA On Windows systems: C:\<ORACLE HOME>\opmn\bin\opmnctl stopproc ias-component=DSA
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.
>On UNIX systems from the <ORACLE_HOME>/dsa/bin directory > asgctl.sh startup On Windows systems fom the <ORACLE_HOME>\dsa\bin directory C:\> asgctl 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.
Log out of the system.
Post-Clone Steps
For the instance on the production and standby sites, perform the following steps:
Log in as su - root on UNIX systems or as Administrator on Windows systems.
CD to the instance home.
On the production site systems, CD to the instance home.
On the standby site systems, CD to the OracleAS Guard standalone home.
Perform an asgctl shutdown command.
>On UNIX systems from the <ORACLE_HOME>/dsa/bin directory > asgctl.sh shutdown On Windows systems fom the <ORACLE_HOME>\dsa\bin directory C:\> asgctl shutdown
Log out as root on UNIX systems.
On UNIX systems only: Restore the permission for dsaServer.sh to what you recorded it as in Pre-Clone Step 4.
On the standby site only, CD to the newly cloned home.
Start up OracleAS Guard using the following opmnctl command:
On Unix systems: > <ORACLE HOME>/opmn/bin/opmnctl startproc ias-component=DSA On Windows systems: C:\<ORACLE HOME>\opmn\bin\opmnctl startproc ias-component=DSA
|
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.2.0.2(c) Copyright 2004, 2005 Oracle Corporation. All rights reserved 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> clone instance portal_2 to asmid2 Generating default policy for this operation . . . ASGCTL> disconnect ASGCTL> exit > d. Log off the system 4. Perform Post-Clone steps as described in the Usage Notes.
Clones two or more production middle tier instances to standby middle tier systems.
Format
clone topology to <standby_topology_host> [using policy <file>]
Parameters
The name of the standby topology host system.
Full path and file specification for the XML policy file.
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 middle tiers 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
See Section 11.8, "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, clone, and post-clone steps.
Pre-Clone Steps
For each instance on the production and standby sites, perform the following steps:
Log in as su - root on UNIX systems or as Administrator on Windows systems.
CD to the instance home.
Shut down any OracleAS Guard servers.
On UNIX systems: > <ORACLE HOME>/opmn/bin/opmnctl stopproc ias-component=DSA On Windows systems: C:\<ORACLE HOME>\opmn\bin\opmnctl stopproc ias-component=DSA
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.
>On UNIX systems from the <ORACLE_HOME>/dsa/bin directory > asgctl.sh startup On Windows systems fom the <ORACLE_HOME>\dsa\bin directory C:\> asgctl 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.
Log out of the system.
Post-Clone Steps
For each instance on the production and standby sites, perform the following steps:
Log in as su - root on UNIX systems or as Administrator on Windows systems.
CD to the instance home.
On the production site systems, CD to the instance home.
On the standby site systems, CD to the OracleAS Guard standalone home.
Perform an asgctl shutdown command.
>On UNIX systems from the <ORACLE_HOME>/dsa/bin directory > asgctl.sh shutdown On Windows systems fom the <ORACLE_HOME>\dsa\bin directory C:\> asgctl shutdown
Log out as root on UNIX systems.
On UNIX systems only: Restore the permission for dsaServer.sh to what you recorded it as in Pre-Clone Step 4.
On the standby site only, CD to the newly cloned homes.
Start up OracleAS Guard using the following opmnctl command:
On Unix systems: > <ORACLE HOME>/opmn/bin/opmnctl startproc ias-component=DSA On Windows systems: C:\<ORACLE HOME>\opmn\bin\opmnctl startproc ias-component=DSA
|
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 12.1, "Information Common to OracleAS Guard asgctl Commands" and Section 12.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.2.0.2(c) Copyright 2004, 2005 Oracle Corporation. All rights reserved 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> 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 4. Perform Post-Clone steps as described in the Usage Notes.
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_admin/<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.
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.
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 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 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
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 12.1, "Information Common to OracleAS Guard asgctl Commands" and Section 12.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.
|
Note: You should always use the discover topology command for discovering the topology for a site because this command uses Oracle Internet Directory to discover all instances in the topology. The discover topology within farm command is useful only in those special cases where Oracle Internet Directory is not available; in this special case OracleAS Guard uses OPMN to discover the topology within a farm. |
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.
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 12.1, "Information Common to OracleAS Guard asgctl Commands" and Section 12.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_admin/<password>]
disconnect
exit
quit
clone topology to <standby_topology_host> [using policy <file>]
clone instance <instance> to <standby_topology_host>
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>]
set asg credentials <host> ias_admin/<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
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 12.1, "Information Common to OracleAS Guard asgctl Commands" and Section 12.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 >
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 DisasterRecovery deployments, shut down all instances prior to the switchover operation. To do this, create a script and then execute the script using the run command. See Section 11.10.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_admin/<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.
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 12.1, "Information Common to OracleAS Guard asgctl Commands" and Section 12.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 a DSA 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 a DSA 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 12.1, "Information Common to OracleAS Guard asgctl Commands" and Section 12.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
Parameters
None.
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 12.1, "Information Common to OracleAS Guard asgctl Commands" and Section 12.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 12.1, "Information Common to OracleAS Guard asgctl Commands" and Section 12.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 12.1, "Information Common to OracleAS Guard asgctl Commands" and Section 12.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 examples.
