Skip Headers

Oracle® Application Server High Availability Guide 10g Release 3 (10.1.3) B15977-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 6 OracleAS Guard asgctl Command-line Reference

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

Table 6-2 Summary of Deprecated asgctl Commands

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

## 6.1 Information Common to OracleAS Guard asgctl Commands

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=ASG

    On Windows systems:
    <ORACLE_HOME>\opmn\bin\opmnctl  stopproc  ias-component=ASG

## 6.2 Information Specific to a Small Set of OracleAS Guard Commands

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.

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.

### 6.2.1 Special Considerations for OracleAS Disaster Recovery Configurations in CFC Environments

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

For example, in the Windows CFC environment, Oracle Fail Safe performs database polling and restarts the database if it is down. Hence, every time before the administrator performs a clone, instantiate, switchover, or failover operation, the administrator must disable database polling in Oracle Fail Safe and re-enable it after the backup/restore operation (after the clone, instantiate, switchover, or failover operation completes). The steps to perform this sequence of operations are described in a note in Section 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".

#### 6.2.1.1 Special Considerations for Running Instantiate and Failover 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:

1. 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.

2. Using Windows Service Control Manager, start the following services in this order: Fail Safe Listener, then the Oracle Database service.

3. From a Windows command prompt, use the sqlplus command-line Utility to startup the database.

4. Using Windows Service Control Manager, start the Oracle Process Manager.

5. Perform the asgctl commands, including the clone, instantiate, switchover, or failover operation.

6. 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.

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

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.

#### 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 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:

1. 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.

2. Using Windows Service Control Manager, start the following services in this order: Fail Safe Listener, then the Oracle Database service.

3. From a Windows command prompt, use sqlplus to start up the database.

4. Perform the asgctl commands, including the instantiate topology, switchover topology, or failover command.

5. 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.

### 6.2.2 Other Special Considerations for OracleAS Disaster Recovery Environments

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

## add instance

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

Format

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

Parameters

instance_name

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

instance_host

  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.

to topology

  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 OracleAS 10.1.3 Instances to Redundant Single OracleAS 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

## asgctl

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

filename = <file-path>

  The path to a file that contains asgctl commands that you want to run as a script.

Usage Notes

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

Example

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

## clone instance

Clones a single production instance to a standby system.

Format

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

Parameters

instance

  The name of the instance.

standby_topology_host

  The name of the standby topology host to which the instance is to be cloned.

no standby

  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:

1. Log in as su - root.

2. CD to the instance home.

3. Shut down any OracleAS Guard servers.

       > <ORACLE HOME>/opmn/bin/opmnctl stopproc ias-component=ASG

4. 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

5. Invoke asgctl and issue the startup command.

       > asgctl.sh startup

6. Log out as root on UNIX systems.

Clone Steps

From any instance on the production site, perform the following steps:

1. Log in as user (non root user on UNIX systems).

2. CD to the production instance home.

3. 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.

4. 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

## clone topology

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

standby_topology_host

  The name of the standby topology host system.

using policy <file>

  Full path and file specification for the XML policy file.

no standby

  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:

1. Log in as su - root.

2. CD to the instance home.

3. Shut down any OracleAS Guard servers.

       > <ORACLE HOME>/opmn/bin/opmnctl stopproc ias-component=ASG

4. 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

5. Invoke asgctl and issue the startup command.

       > asgctl.sh startup

6. Log out as root on UNIX systems.

Clone Steps

From any instance on the production site, perform the following steps:

1. Log in as user (non root user on UNIX systems).

2. CD to any production instance home.

3. 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.

4. 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

## connect asg

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

host-name = <host-name>

  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.

port

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

<ias_administrative_account>/password

  If this is an OracleAS 10.1.3 installation, the user name must be `oc4jadmin` and the password for the `oc4jadmin` account created during the Oracle Application Server installation. If this is an OracleAS 10.1.2.0.2 or lower installation, the user name must be the `ias_admin` account name and the password for the `ias_admin` account created during the Oracle Application Server installation.

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

Usage Notes

- The 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

## disconnect

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>

## discover topology

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

Format

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

Parameters

host

  Name of the host system where Oracle Internet Directory is installed.

sslport

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

user

  The Oracle Internet Directory user name.

pass

  The password for the specified Oracle Internet Directory user name.

Usage Notes

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

Discover topology creates the topology (stored in `topology.xml`) on which to perform all 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>

## discover topology within farm

Directs asgctl to discover the topology within a farm at a production site for those special cases where a farm does not have Oracle Internet Directory available.

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.

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>

## dump policies

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>

## dump topology

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

Format

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

Parameters

to <file>

  Name of file on the OracleAS Guard client node where the detailed output is to be written.

using policy <file>

  Full path and file specification for the XML policy file.

Usage Notes

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

Example

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

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

    Contents of file c:\dump_mid_1.txt are:

    Generating default policy for this operation

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

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

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

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

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

## exit

Disconnects from any existing connections to OracleAS Guard servers and exits from the OracleAS Guard client.

Format

exit

Parameters

None

Usage Notes

None.

Example

    ASGCTL> exit
    >

## failover

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

Format

failover [using policy <file>]

Parameters

using policy <file>

  Full path and file specification for the XML policy file.

Usage Notes

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

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

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

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>

## help

Displays help information.

Format

help [<command>]

Parameters

command

  Name of the command for which you want help.

Usage Notes

None.

Example

The following example displays help about all commands.

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

## instantiate topology

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

standby_topology_host

  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.

port

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

with cloning

  A directive to perform an instantiation operation using cloning.

using policy <file>

  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>

## quit

Instructs the OracleAS Guard client to disconnect from any existing connections and exit from asgctl.

Format

quit

Parameters

None

Usage Notes

None.

Example

The following example exits from asgctl.

    ASGCTL> quit
    >

## remove instance

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

Format

remove instance <instance_name> [from topology]

Parameters

instance_name

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

from topology

  A keyword, that if present in the command line, directs 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 OracleAS 10.1.3 Instances to Redundant Single OracleAS 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

## set asg credentials

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

host

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

port

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

<ias_administrative_account>/password

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

for farm (deprecated)

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

for topology

  A keyword, that if present in the command line, directs 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

## set echo

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

Format

set echo on | off

Parameters

on | off

  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

## set new primary database

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

Format

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

Parameters

username/password

  User name and password for the database account with sysdba privileges.

servicename

  The TNS service name of the OracleAS Infrastructure database. The name must be defined on the OracleAS Infrastructure host system; it does not need to be defined on the OracleAS Guard client host system.

pfile filename

  The filename of the primary (OracleAS Infrastructure) database initialization file that will be used when the primary database is started.

spfile filename

  The filename of the server (OracleAS Infrastructure) initialization file that will be used when the database is started.

Usage Notes

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

Example

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

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

## set noprompt

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

Format

set noprompt

Parameters

None

Usage Notes

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

Example

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

    > ASGCTL @myasgctltestscript.txt

    # myasgctltestscript.txt

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

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

    # discover the production topology
    discover topology oidpassword=oidpwd

    # set the noprompt state
    set noprompt

    #display detailed info about the topology
    dump topology

    #disconnect
    disconnect

    exit

## set primary database

Identifies the OracleAS Infrastructure database on the primary topology.

Format

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

Parameters

username/password

  User name and password for the database account with sysdba privileges.

servicename

  The TNS service name of the OracleAS Infrastructure database. The name must be defined on the OracleAS Infrastructure host system; it does not need to be defined on the OracleAS Guard client host system.

pfile filename

  The filename of the primary (OracleAS Infrastructure) database initialization file that will be used when the primary database is started.

spfile filename

  The filename of the server (OracleAS Infrastructure) initialization file that will be used when the database is started.

Usage Notes

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

When you set the primary database, 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
    .
    .
    .

## set trace

Sets a trace flag on or off to log output to the OracleAS Guard log files.

Format

set trace on | off <traceflags>

Parameters

on | off

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

traceflags

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

  - 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

## show env

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>

## show operation

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

full

  For all operations, shows the operation number, the job name, the job owner's user name, the job ID, the time the operation began, the time the operation ended, the elapsed time for the operation, and all tasks belonging to this job.

history

  For only operations that are not running, shows the operation number and the job name.

Usage Notes

None.

Example

The following examples show the status of the current operation.

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

The following example shows the history of all operations.

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

## shutdown

Shuts down a running 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

local

  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

## shutdown topology

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>

## startup

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

asg

  Optional keyword acronym for application server guard. This parameter has no other meaning other than to show a format similar to the connect asg and set asg credentials commands.

Usage Notes

None.

Example

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

    > asgctl.sh startup

## startup topology

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

Format

startup topology

Parameters

none

Usage Notes

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

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

Example

The following example starts up the production topology.

    ASGCTL> startup topology
    Generating default policy for this operation

    profinfra:7890
        Starting each instance in the topology

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

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

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

## stop operation

Stops a specific operation that is running on the server.

Format

stop op[eration] <op #>

Parameters

op #

  The number of the operation.

Usage Notes

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

Example

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

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

    ASGCTL> stop operation 15

## switchover topology

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

Format

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

Parameters

standby_topology_host

  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.

port

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

using policy <file>

  Full path and file specification for the XML policy file.

Usage Notes

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

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

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

    > <ORACLE_HOME>/bin/emctl stop iasconsole

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

    > ps -ef | grep emagent

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

    > kill -9 <emagent-pid>

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

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

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

As part of the 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 core1 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>

## sync topology

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

Format

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

Parameters

standby_topology_host

  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.

port

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

full | incremental

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

using policy <file>

  Full path and file specification for the XML policy file.

Usage Notes

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

- When you want to force a full synchronization to happen, such as synchronizing the standby site completely at a specific point in time (currently) with the primary site.

- When you know there are many transactional changes over a short period of time on the primary site that must be synchronized with the secondary site.

- When you know that there are a large accumulation of transactional changes over a long period of time on the primary site that must be synchronized with the secondary site.

The sync operation performs an implicit verify operation.

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

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>

## verify topology

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

Format

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

Parameters

host

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

port

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

using policy <file>

  Full path and file specification for the XML policy file.

Usage Notes

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

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

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

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>

## dump farm (Deprecated)

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

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

Format

dump farm [to <file>]

Parameters

to <file>

  Name of file on the OracleAS Guard client node where the detailed output is to be written.

Usage Notes

None.

Example

See the dump topology command for an example.

## instantiate farm (Deprecated)

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

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

Format

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

Parameters

standby_farm_host

  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.

port

  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.

## shutdown farm (Deprecated)

Shuts down a running farm.

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

Format

shutdown farm

Parameters

None.

Usage Notes

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

Example

See the shutdown topology command for an example.

## startup farm (Deprecated)

Starts up a shutdown farm.

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

Format

startup farm

Parameters

None

Usage Notes

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

Example

See the startup topology command for an example.

## switchover farm (Deprecated)

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

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

Format

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

Parameters

standby_farm_host

  Name of the farm host system. This parameter is required because it directs the coordinating 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.

port

  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.

## sync farm (Deprecated)

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

standby_farm_host

  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.

port

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

full | incremental

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

Usage Notes

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

- When you want to force a full synchronization to happen, such as synchronizing the standby site completely at a specific point in time (currently) with the primary site.

- When you know there are many transactional changes over a short period of time on the primary site that must be synchronized with the secondary site.

- When you know that there is a large accumulation of transactional changes over a long period of time on the primary site that must be synchronized with the secondary site.

Example

See the sync topology command for an example.

## verify farm (Deprecated)

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

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

Format

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

Parameters

host

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

port

  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.