8 Cloning an Application Server Instance

8.1.1 Installation Types Supported

In this release, you can clone the following types of middle-tier installations:

• J2EE and Web Cache middle tier

• Portal and Wireless middle tier

• Business Intelligence and Forms middle tier

Note the following:

• You cannot clone the OracleAS Infrastructure itself. However, you can clone a middle tier that is connected to OracleAS Infrastructure, including OracleAS Metadata Repository and Oracle Identity Management.

• You cannot clone OracleAS Integration B2B, Oracle BPEL Process Analytics, or Oracle BPEL Process Manager.

• The cloned instance must have a different instance name than the source instance. You specify the instance name when you clone the instance, as described in Section 8.2.3.

• You can clone a middle-tier instance that is a member of an OracleAS Cluster or farm. However, you must remove the instance from an OracleAS Cluster.

8.1.2 General Considerations and Limitations for Cloning

For this release, you cannot clone the following:

• OracleAS Infrastructure components (Oracle Identity Management and OracleAS Metadata Repository)

• Developer Kits, including Oracle Content Management SDK (Oracle CM SDK)

• Installations that include Oracle Application Server Integration B2B, Oracle BPEL Process Analytics, or Oracle BPEL Process Manager.

• Installations that include Oracle Application Server Integration InterConnect

• Adapters, including Oracle Application Server Adapters and Oracle Application Server Integration InterConnect Adapters

• Installations that include Oracle Workflow

Note the following important additional considerations about cloning:

• The user may need to update the security certificates to match the new host name.

• If an instance is part of an OracleAS Cluster, you must remove the instance from the cluster before performing the cloning operation.

• Cloning an Oracle Application Server middle tier that is connected to an OracleAS Infrastructure will result in a new Oracle Application Server middle tier connected to the same OracleAS Infrastructure as the source instance. To join a different OracleAS Infrastructure, you can reassociate the middle tier with a different OracleAS Infrastructure.

• If you have changed the default file permissions for configuration files, then those file permissions are not preserved by cloning.

• User customizations for the following components are not preserved. The status of these components are reset to the default:

  • Log Loader

  • Oracle Application Development Framework

  • Port tunneling

  • UIX

  • XDK

• Cloning does not carry over all the dependencies of the source Oracle home, such as loadable modules or application-specific libraries to the cloned home, because cloning proceeds by copying the entire source Oracle home to the destination Oracle home. Any files outside the source Oracle home are not automatically copied. Hence, any applications that refer to files outside the source Oracle home may not work properly in the cloned home.

• If you created symbolic links to files or applications outside the source Oracle home (for example, to Oracle Wallet files that are not stored in the default location), then you must re-create the link manually in the cloned home for your applications to work properly.

• The cloning operation generates default ports for the cloned instance. To specify other ports, you can use the staticports.ini file. If you specify ports less than 1024 on UNIX, then the cloned instance will not start during the cloning operation. After the cloning process is completed, you must run the root.sh script with root privileges, then start the processes.

• The cloning process does not configure a Load Balancing Router to recognize the cloned instance. If you use a Load Balancing Router in your environment, then you must manually configure the Load Balancing Router, including any invalidation port.

• If a cloning operation fails, but it results in the Oracle home being registered with Oracle Inventory, you cannot use the same Oracle home in subsequent cloning operations. Either use another directory and name for the Oracle home in subsequent cloning operations or deinstall the Oracle home before attempting another cloning operation.

For important considerations for cloning individual components, see Chapter 10, "Cloning Application Server Instances" of the Oracle Application Server Administrator's Guide.

8.2.1 Prerequisites for Cloning

For cloning, Perl 5.6.1 or higher must be installed on your system. Before running the cloning Perl scripts, you must set the PERL5LIB environment variable to the path of the Perl directory in the Oracle home. This path must be the first one listed in the variable definition. For example:

setenv PERL5LIB $Oracle_Home/perl/lib/5.6.1:$Oracle_Home/perl/lib/site_perl/5.6.1:$PERL5LIB

On Windows:

set PERL5LIB=%Oracle_Home%\perl\5.6.1\lib;%OH%\perl\
5.6.1\lib\MsWin32-x86;%Oracle_Home%\perl\site\5.6.1\lib;%PERL5LIB%

8.2.2 Preparing the Source

To prepare the source Oracle home to be cloned, take the following steps at the source instance:

1. Change to the following directory:

   • On UNIX systems:

     Oracle_Home/clone/bin

   • On Windows systems:

     Oracle_Home\clone\bin

2. Run the script prepare_clone.pl. This script prepares the source to be cloned.

   The command line for the script has the following format:

   perl prepare_clone.pl [ORACLE_HOME=OH_dir]
                         [-oid_password OIDPassword] 
                         [-oid_admin OIDadmin]
                         [-silent]
                         [-debug]
                         [-help]
   
   

   Table 8-1 describes the parameters and options for the prepare_clone.pl script.

   Table 8-1 Parameters and Options for the prepare_clone.pl Script

   Parameter or Option	Description
   ORACLE_HOME	The complete directory specification for the source Oracle home. If you do not supply this parameter, the script uses the ORACLE_HOME environment variable, if it exists. If the environment variable does not exist, the script assumes that ORACLE_HOME is the directory from which the script is being run. Use the value that was provided during installation; do not use symbolic links. If ORACLE_HOME is invalid, then the script exits and logs an error to the errortimestamp.log file.
   -oid_password	The Oracle Internet Directory password. If the original installation required that the user specify an Oracle Internet Directory password (such as an instance connected to Oracle Identity Management), this option is required. If you do not supply the option, but one is needed, the script prompts the user for the password.
   -oid_admin	The Oracle Internet Directory admin value. If you do not specify this option, the script uses a default value of cn=orcladmin.
   -silent	Runs the script in silent mode. If the command line does not contain the required password-related options, the script exits.
   -debug	Runs the script in debug mode.
   -help	Prints the usage for the script.

   
   

3. Archive and compress the source Oracle home, using your preferred tool for archiving. For example, you can use WinZip on Windows and tar and gzip on UNIX. Ensure that the tool you are using preserves the permissions and timestamps of the files. The following example shows how to archive and compress the source on UNIX:

   cd Source_Oracle_Home 
   tar cf - * | gzip > oracleas.tar.gz
   
   

   Note that you should not use the jar utility to archive and compress the Oracle home.

8.2.3 Cloning the Instance

At the destination, to clone the source instance, take the following steps:

1. Copy the compressed Oracle home from the source machine to the destination machine.

2. Extract the compressed Oracle home into a directory, which will become the new Oracle home at the destination location. Use your preferred tool to extract the compressed files. For example, you can use WinZip on Windows and tar and gunzip on UNIX. Ensure that the tool you are using preserves the permissions and timestamps of the files. The following example shows how to extract the files on UNIX:

   mkdir -p Destination_Oracle_Home 
   gunzip  <  Dir_Containing_Tar/oracleas.tar.gz | tar xf -
   

   
   

   Note: Ensure that the tar and gzip/gunzip versions on the source and destination machines are compatible. You may encounter problems unzipping the archive if these versions differ.

   
   

3. Change to the following directory:

   • On UNIX systems:

     Oracle_Home/clone/bin

   • On Windows systems:

     Oracle_Home\clone\bin

4. Run the clone.pl script. You must have write permission to the directory containing the Oracle inventory file. (See Section 8.2.4 for information about the location of the Oracle inventory directory.

   The command line for the script has the following format:

   perl clone.pl ORACLE_HOME=OH_dir
                 ORACLE_HOME_NAME=OH_Name
                 -instance Instance_Name
                 [-ias_admin_old_pwd Old_Ias_Admin_Password]
                 [-ias_admin_new_pwd New_Ias_Admin_Password]
                 [-oid_password OIDPassword]
                 [-dcm_schema_pwd DCMPassword]
                 [-lbr {true|false}]
                 [-O string]
                 [-silent]
                 [-debug]
                 [-help]
   
   

   Table 8-2 describes the parameters and options for the clone.pl script.

   Table 8-2 Parameters and Options for the clone.pl Script

   Parameter or Option	Description
   ORACLE_HOME	Required. The complete directory specification for the destination Oracle home. This parameter is required. If you do not supply this parameter, or if the value is invalid, the script exits.
   ORACLE_HOME_NAME	Required. The name for the destination Oracle home (the Oracle home of the clone.)
   -instance	Required. The instance name for the clone. The instance name must be different from the source instance and any other instances that use the same OracleAS Infrastructure or that are part of the same OracleAS Cluster or farm.
   -ias_admin_old_pwd	Required. The administrator password for Oracle Application Server for the source instance. If you do not supply this option and the script is not running in silent mode, the script prompts the user for the password.
   -ias_admin_new_pwd	Required. A new password for administrator for Oracle Application Server for the cloned instance. If you do not supply this option and the script is not running in silent mode, the script prompts the user for the password.
   -oid_password	The Oracle Internet Directory password. If the original installation required that the user specify an Oracle Internet Directory password (such as an instance connected to Oracle Identity Management), then this option is required. If you do not supply this option, but one is needed, the script prompts the user for the password.
   -dcm_schema_pwd	The Distributed Configuration Management (DCM) schema password. If the original installation required that the user specify a DCM schema password (such as a J2EE instance connected to a OracleAS Metadata Repository, but not to Oracle Identity Management), then this option is required. If you do not supply this option, but one is needed, the script prompts the user for the password.
   -lbr	Whether or not a load balancer is used. The default is true. If you are cloning a Portal and Wireless instance and you specify false, the cloning process overwrites the configuration entries for the source instance, which are stored in the OracleAS Metadata Repository.
   -O	Specifies that any text following the option is passed to the Oracle Universal Installer command line. For example, you can use this option to pass the location of the oraparam.ini file to be used by Oracle Universal Installer, by using the following code: '-O-paramFile C:\OraHome_1\oui\oraparam.ini' Note that if the text you want to pass contains spaces or other delimiting characters, you must enclose the option in double quotation marks (").
   -silent	Runs the script in silent mode. If the command line does not contain the required password-related options, the script exits.
   -debug	Runs the script in debug mode.
   -help	Prints the usage for the script.

   
   

   For example:

   perl clone.pl ORACLE_HOME=/opt/oracle/Ora_1012_B
                  ORACLE_HOME_NAME=OH_1012_B
                  -instance Portal_B
                  -ias_admin_old_pwd my_old_ias_pass
                  -ias_admin_new_pwd my_new_ias_pass
                  -oid_password my_oidpwd
                  -dcm_schema_pwd my_DCM_pass]
                  -lbr true
                  '-O-paramFile /var/opt/oracle/oui/oraparam.ini'
                  -silent
   
   

5. On UNIX, run the root.sh script in the cloned Oracle home so that the cloned instance works properly. The script is located in the cloned instance's Oracle home directory.

   For example:

   $ORACLE_HOME/root.sh
   
   

Now, the cloned instance's configuration is identical to that of the source instance. Application Server Control Console and OPMN are able to start and stop all processes in the cloned instance, including any OC4J custom instances. All applications deployed should be visible and able to run as expected.

8.2.4 Locating and Viewing Log Files

The cloning script invokes multiple tools, each of which generates its own log files. However, the following log files, which are generated by Oracle Universal Installer and the cloning scripts, are the key ones of interest for diagnostic purposes:

• Oracle_inventory/logs/cloneActionstimestamp.log: Contains a detailed log of the actions that occur during the Oracle Universal Installer part of the cloning.

• Oracle_inventory/logs/oraInstalltimestamp.err: Contains information about errors that occur when Oracle Universal Installer is running.

• Oracle_inventory/logs/oraInstalltimestamp.out: Contains other miscellaneous messages generated by Oracle Universal Installer.

• Oracle_Home/clone/logs/clonetimestamp.log: Contains a detailed log of the actions that occur during the precloning and cloning operations.

• Oracle_Home/clone/logs/errortimestamp.log: Contains information about errors that occur during the precloning and cloning operations. In addition, it contains all messages written to standard error (STDERR) by the multiple tools that are invoked by the cloning script. Depending upon the tool, some of these messages may be informational messages or error messages.

The format of the path is shown in UNIX format. For Windows, invert the slashes.

After the clone.pl script finishes running, consult these log files to get more information about the cloning process. To view the log files from Application Server Control Console, take the following steps:

1. Select Logs from the Home page.

2. In the View Logs page, select ASClone from the Available Components box. Click Move to move the selection to the Selected Components box.

3. Click Search.

   The log files are displayed in the Results table.

4. To view the log, click the log name in the Log File column.