10 Cloning Application Server Instances

10.3.1 Source Preparation Phase

At the source, you run the script called prepare_clone.pl. This is a Perl script that prepares the source for cloning. It takes a snapshot of the information required for cloning.

During this phase, prepare_clone.pl parses files in the source Oracle home to extract and store required values. It also creates an archive using Distributed Configuration Management (DCM), backs up required files, and runs the OracleAS Wireless clone assistant, if OracleAS Wireless is installed.

Then, you tar the Oracle home directories.

See Section 10.4.1, "Preparing the Source" for specific instructions for preparing the source instance.

10.3.2 Cloning Phases

At the destination, you extract the Oracle home from the tar file. Then, you run the script called clone.pl. This is a Perl script that performs all parts of the cloning operation automatically, calling various other utilities and Oracle Universal Installer, as needed. This script makes use of the cloning functionality in Oracle Universal Installer. When you invoke the clone.pl script, it goes through the following three phases:

1. Pre-cloning phase

   During this phase, the clone.pl script lays the groundwork necessary to ensure that cloning can be done. It ensures that the destination inventory has all necessary non-Oracle home components for the cloning to succeed.

2. Cloning phase

   During this phase, the clone.pl script invokes Oracle Universal Installer in clone mode with the necessary arguments to perform the Oracle Universal Installer home cloning. This re-instantiates all files (after creating backups of the existing instantiated files), sets environment variables, updates links, and so on. In other words, it repeats all actions that were performed at installation time, with the exception of the file copying.

3. Post-cloning phase

   The postinstallation configuration assistants are not designed to be run again at clone time. Consequently, some of the instance-specific configuration files that should be updated by the configuration assistants are not updated at the end of the Oracle Universal Installer cloning session. Instead, Oracle has created a set of post-cloning scripts that will update those files to bring the cloned home to a working state.

   The post-cloning steps performed by the script are:

   1. Sets the new Oracle home in DCM.

   2. Updates configuration files. In this step, many configuration files that have been re-instantiated by Oracle Universal Installer during the cloning phase are restored from their backups. Those files are then updated with the new values that reflect the new environment, if needed. For example, if a file has a reference to the source Oracle home, that reference is updated to reflect the destination Oracle home.

   3. Calls the home's chgiphost utility to change the host name and IP number information in the cloned home. Before calling chgiphost, the script must collect the following required information to invoke chgiphost in silent mode:

      • Source host name

      • Source IP address

      • Destination host name

      • Destination IP address

   4. If the source instance is connected to Oracle Internet Directory, adds information about the clone to Oracle Internet Directory.

   5. After the chgiphost utility runs successfully, starts services, as well as the Application Server Control Console, to verify the success of the cloning operation.

Note that you do not need to perform each of these phases manually, because the clone.pl script takes care of all three phases automatically. The information is provided only for conceptual understanding.

See Section 10.4.2, "Cloning the Instance" for specific instructions on the tasks you do at the destination.

Files Updated During the Post-Cloning Phase

During the post-cloning phase, a set of important configuration files are restored from their backup versions and updated. Typical changes made to the files include updating environment-specific variables such as host name, Oracle home, and port numbers to their new values.

The following list shows some of the key files that are updated. Note that this is not an exhaustive list of the files being updated.

• Oracle_Home/config/ias.properties

• Oracle_Home/sysman/emd/targets.xml

• Oracle_Home/sysman/j2ee/application-deployments/em/emd/orion-web.xml

• Oracle_Home/diagnostics/config/dcmPlugins.xml

• Oracle_Home/Apache/Apache/conf/httpd.conf

• Oracle_Home/Apache/Apache/conf/mod_oc4j.conf

• Oracle_Home/Apache/Apache/conf/oracle_apache.conf

• Oracle_Home/Apache/modplsql/conf/dads.conf

• Oracle_Home/Apache/modplsql/conf/plsql.conf

• Oracle_Home/Apache/modplsql/conf/cache.conf

• Oracle_Home/Apache/oradav/conf/moddav.conf

• Oracle_Home/opmn/conf/opmn.xml

10.4.1 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 10-1 describes the parameters and options for the prepare_clone.pl script.

   Table 10-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. If ORACLE_HOME is invalid, 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. Make sure 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.

10.4.2 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. Make sure 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: Make sure 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 10.4.3 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 10-2 describes the parameters and options for the clone.pl script.

   Table 10-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	The administrator password for Oracle Application Server for the source instance. This option is required. 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	A new password for administrator for Oracle Application Server for the cloned instance. This option is required. 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), 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), this option is required. If you do not supply this option, but one is needed, the script prompts the user for the password. The password is generated randomly during installation. To change the random password to a known value, use the ALTER USER command in SQL*Plus, as shown in the following example: sqlplus "sys/sys_password as sysdba" SQL> ALTER USER dcm IDENTIFIED BY new_password; To find the current password, use the following command: SELECT password FROM dba_users WHERE username='DCM';
   -lbr	Whether or not a Load Balancing Router 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. See Section 10.5.7 and Section 10.7.2 for more information.
   -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.

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

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.

10.4.4 Cloning Instances That Are Members of a Farm or OracleAS Cluster

You can clone a middle-tier instance that is a member of a farm or OracleAS Cluster.

The following information describes how cloning works with file-based repositories and with OracleAS Infrastructure (OracleAS Metadata Repository and Oracle Identity Management):

• File-based repository

  If the source instance is a member of a farm or OracleAS Cluster and is connected to a file-based repository (either in the same instance or a separate instance), you must remove the source instance from the farm and OracleAS Cluster before beginning the cloning operation.

• File-base repository and Oracle Identity Management

  If the source instance is connected to a file-based repository (either in the same instance or a separate instance) and Oracle Identity Management (either in the same instance or a separate instance), you must remove the source instance from the farm and OracleAS Cluster before beginning the cloning operation. The cloned instance will be connected to the same Oracle Identity Management as the source instance.

• OracleAS Metadata Repository

  If the source instance is connected to OracleAS Metadata Repository, the cloned instance will be connected to the same OracleAS Metadata Repository. The cloned instance will be a member of the same farm as the source instance.

• OracleAS Metadata Repository and Oracle Identity Management

  If the source instance is connected to OracleAS Metadata Repository and Oracle Identity Management, the cloned instance will be connected to the same OracleAS Metadata Repository and Oracle Identity Management. The cloned instance will be a member of the same farm as the source instance.

  One example of this scenario is a Portal and Wireless installation, which requires OracleAS Metadata Repository and Oracle Identity Management.

• No repository, but Oracle Identity Management

  If the source instance is not connected to a repository, but is connected to Oracle Identity Management in a separate instance, the cloned instance will be connected to that same Oracle Identity Management.

If you remove an instance from a farm or OracleAS Cluster, you can add it, and the cloned instance, to the farm or OracleAS Cluster after you complete the cloning operation.

10.5.1 General Considerations and Limitations for Cloning

For this release, you cannot clone the following:

• Installations that are configured for SSL.

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

• A middle-tier instance that is associated with an instance of OracleAS Infrastructure or Oracle Internet Directory that is installed on the same host as the source middle-tier instance. (You can clone a middle-tier instance that is associated with an instance of OracleAS Infrastructure or Oracle Internet Directory that is installed on a different host than the source middle-tier instance.)

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

• Installations that include Oracle Application Server Integration B2B.

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

• If an instance is part of a farm or OracleAS Cluster and is connected to a file-based repository, you must remove the instance from the farm or cluster before performing the cloning operation. If an instance is part of a farm and is connected to OracleAS Metadata Repository, you do not need to remove the instance from the farm before performing the cloning operation. However, you must remove the instance from the OracleAS Cluster before performing the cloning operation.

  See Section 10.4.4 for more information.

• If you have changed the default file permissions for configuration files, 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:

  • LogLoader

  • 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), 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 as described in Section 10.6.2. If you specify ports less than 1024 on UNIX, 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, you must manually configure the Load Balancing Router, including any invalidation port.

10.5.2 Considerations for Cloning Oracle HTTP Server

The following describes important information about cloning Oracle HTTP Server:

• All configuration information in the following files is updated:

  • Oracle_Home/Apache/Apache/conf/httpd.conf

  • Oracle_Home/Apache/Apache/conf/oracle_apache.conf

  • Oracle_Home/Apache/Apache/conf/mod_oc4j.conf

  • Oracle_Home/Apache/modplsql/conf/dads.conf

  • Oracle_Home/Apache/modplsql/conf/plsql.conf

  • Oracle_Home/Apache/modplsql/conf/cache.conf

  • Oracle_Home/Apache/oradav/conf/moddav.conf

  The cloning script preserves the source settings and updates these files with new environment parameters.

  Note that cloning only updates the files it knows about, that is, files that are part of the original installation. In particular, cloning does not update configuration files that the user added to the "include" list in files such as httpd.conf, oracle_apache.conf, dads.conf, plsql.conf, olap.conf, or moddav.conf. You can, however, explicitly add the "include" files to the list of files that cloning will update. See Section 10.6.3 for details on how to update custom settings.

• Cloning preserves all VirtualHost directives in httpd.conf. It replaces any references to the source home inside these directives. However, cloning does not change the IP numbers or port numbers that these virtual hosts listen to.

  If these values are not valid for the destination environment, then you must do one of the following:

  • Register these changes with the clone script to be updated during cloning. See Section 10.6.3 for more information.

  • Update them manually in httpd.conf after cloning.

• If you changed the port number in httpd.conf to use the Load Balancing Router port rather than the local Oracle HTTP Server or OracleAS Web Cache port, that change is lost after cloning. You must edit the httpd.conf file in the cloned home to change the port number to the Load Balancing Router port.

• Cloning is not supported if you are using Oracle HTTP Server based on Apache 1.3 or Apache 2.0. (These are not installed by default, but are included in the companion CD-ROM.)

10.5.3 Considerations for Cloning Oracle Application Server Containers for J2EE (OC4J)

The following describes which OC4J components are preserved and lists considerations in cloning OC4J:

• All default OC4J instances are preserved.

• Custom OC4J instances that you created, as well as applications deployed in them, are preserved. However, external dependencies for these applications that are not in the Oracle home are not copied to the cloned home and will be lost.

• If the OC4J instance uses an Oracle HTTP Server instance that is not part of the source Oracle home, the cloning procedure does not update the mod_oc4j.conf file for the Oracle HTTP Server. You must manually add the instance to the mod_oc4j.conf file.

• OPMN can manage all default and custom cloned OC4J instances.

• Data source information in data-sources.xml is preserved.

• User configurations in jms.xml, java2.policy, jazn.xml, jazn-data.xml, global-web-application.xml, and application.xml are preserved.

• You must manually register files that contain environment-specific information in custom OC4J instances so that those files are updated during cloning. An example of such a file is oc4j.properties. See Section 10.3 for details.

10.5.4 Considerations for Cloning OracleAS Web Cache

The following describes important information about cloning OracleAS Web Cache:

• Settings in webcache.xml and internal.xml are preserved. Only the Oracle home location, host name, instance name, and port numbers are updated to reflect the new environment.

• If the source OracleAS Web Cache instance is a cache cluster member, you must reconfigure the cache cluster after cloning. The cloned home contains the reference to the other nodes in the cache cluster whereas the other nodes do not know about the new instance. After cloning, you need to either add the cloned instance to the cache cluster or remove the cloned cache from the cluster. See the Oracle Application Server Web Cache Administrator's Guide for information about adding caches to a cache cluster.

• Cloning is not supported if the source OracleAS Web Cache instance is configured for HTTPS requests.

• If the source OracleAS Web Cache instance is configured to forward requests to more than one origin server (application Web server or proxy server) on the same host as the source OracleAS Web Cache instance, the cloning process will fail.

  To work around this limitation, remove all but one of the origin servers from the source OracleAS Web Cache configuration, using OracleAS Web Cache administration tools. See Oracle Application Server Web Cache Administrator's Guide for information about removing the origin server.

  Note that because the cloning process does not modify definitions of origin servers on remote hosts, you do not need to remove references to those origin servers from the OracleAS Web Cache configuration.

10.5.5 Considerations for Cloning Application Server Control

The Application Server Control Console can manage the same instances that were managed at the source.

10.5.6 Considerations for Cloning Instances Connected to Oracle Identity Management

If the source instance is connected to Oracle Identity Management services, you must rename the following file at the target before running the clone.pl script:

• On UNIX systems:

  Oracle_Home/Apache/Apache/conf/osso/osso.conf

• On Windows systems:

  Oracle_Home\Apache\Apache\conf\osso\osso.conf

For example, rename the file to osso.conf.BAK.

If you do not rename the file at the target, the source instance will be deregistered from OracleAS Single Sign-On. In this case, to restore the source instance, perform the following steps (at the source instance):

1. Rename the osso.conf file to osso.conf.BAK.

   If you do not rename the file, the registration script will generate a new partner registration record, but the previous existing partner will be removed.

2. Reregister mod_osso. See the section "Registering mod_osso" in the Oracle Application Server Single Sign-On Administrator's Guide.

10.5.7 Considerations for Cloning OracleAS Portal

The following describes important considerations about cloning OracleAS Portal:

• If the cache for OracleAS Portal is located outside the Oracle home, you must manually specify the cache location in the cache.conf file. (Any files used by the source instance that are located outside the source Oracle home's directory structure are not moved to the destination location.) The cache.conf file is located in the following directory:

  • UNIX systems:

    Oracle_Home/Apache/modplsql/conf

  • On Windows systems:

    Oracle_Home\Apache\modplsql\conf

  In this file, make sure that the location for the PlsqlCacheDirectory directive is valid.

• OracleAS Portal does not support two instances connected to the same infrastructure unless they are front-ended by a Load Balancing Router.

  Because OracleAS Portal stores only a single set of configuration information, the cloning process overwrites the configuration entries stored in the repository if you do not specify that there is a Load Balancing Router. If you specify that there is a Load Balancing Router, the cloning process does not perform any configuration steps, and therefore it does not overwrite the configuration settings stored in the Portal schemas in the OracleAS Metadata Repository. See Section 10.7.2 for information about cloning a Portal and Wireless instance that is front-ended by a Load Balancing Router.

  Note that you can reconfigure OracleAS Portal by using the ptlconfig command, as shown in the following example:

  $Oracle_Home/portal/config/ptlconfig -dad portal
  
  

• When you are cloning a Portal and Wireless instance in an environment where the instances are front-ended by a Load Balancing Router, you must make sure that the cloned instance uses the same ports as the other existing instances. To guarantee that the cloning process will assign the same ports for the cloned instance, you can use the staticports.ini file, as described in Section 10.6.2.

• OracleAS Portal creates Oracle Internet Directory users only once, during the first installation of OracleAS Portal. If you clone a Portal and Wireless installation, you use the original password of the ias_admin user of the first OracleAS Portal instance associated with the OracleAS Metadata Repository. This is true even if you changed the password of the ias_admin user of the cloned instance. The password used when Portal users and groups are created in Oracle Internet Directory remains the same even if multiple instances are later connected to this infrastructure.

• Any external applications are stored in the OracleAS Single Sign-On server. If OracleAS Portal is not front-ended by a Load Balancing Router and if there is any change in the URL of an external application, you must update it manually in the external application. To do this, log in directly to the OracleAS Single Sign-On server as a user who has single sign-on Administrator privileges:

  http://SSO_host:SSO_port/pls/orasso/
  
  

  Then, select the Administer External Applications link, select the application, and update the Login URL. Alternatively, you can use the Administer External Applications link in the SSO Administration portlet in the portal. This portlet requires the same privileges as the OracleAS Single Sign-On Server.

  For more information, see the chapter "Configuring and Administering External Applications" in the Oracle Application Server Single Sign-On Administrator's Guide.

• If OracleAS Portal is not front-ended by a Load Balancing Router, you must manually update the registration URL of custom-built Web providers and provider groups that are local to the source instance. A custom-built provider or provider group is any Web provider or provider group that is not seeded by the OracleAS Portal installation. To update the registration, take the following steps:

  For a Web provider:

  1. Click Edit Registration for the provider on the Providers tab of the Navigator, under Registered Providers.

  2. Select the Connection tab, and change the host and port part of the provider registration URL from the source host and port to the cloned instance host and port. For example:

     http://clone_host:clone_port
     
     

  3. Verify that the custom-built provider works properly on the cloned instance, by using the test pages at the URL:

      http://clone_host:clone_port/webApp/providers/providerName
     
     

  For a provider group:

  1. Click Edit Registration for the provider group on the Providers tab of the Navigator, under Providers Groups.

  2. Change the host and port part of the URL from the source host and port to the cloned instance host and port. For example:

     http://clone_host:clone_port
     

10.5.8 Considerations for Cloning OracleAS Wireless

The following describes important information about cloning OracleAS Wireless:

• If the Portal and Wireless middle tier is not front-ended by a Load Balancing Router and you do not specify the -lbr option when cloning, you must reconfigure the OracleAS Portal and OracleAS Wireless integration as described in "Manually Reconfiguring the Mobile Setup" section of the Oracle Application Server Portal Configuration Guide.

10.5.9 Considerations for Cloning Business Intelligence

The following describes important information about cloning a Business Intelligence instance:

• You can clone the Business Intelligence middle tier, only if it is not connected to OracleAS Infrastructure components (Oracle Identity Management and the OracleAS Metadata Repository).

10.6.1 Specifying Oracle Universal Installer Parameters

When cloning an instance, you do not directly invoke Oracle Universal Installer. However, you can still pass information to Oracle Universal Installer indirectly, by specifying any Oracle Universal Installer parameters that you normally specify on the command line in the configuration file cs.properties. This file is located in the following directory:

• On UNIX systems:

  Oracle_Home/clone/ias/config

• On Windows systems:

  Oracle_Home\clone\ias\config

For example, to specify a nondefault location for the Oracle inventory file on UNIX, you can add the following line to the cs.properties file:

clone_command_line= -invptrloc /private/oracle/oraInst.loc

To specify multiple arguments, separate each argument with a space.

10.6.2 Assigning Custom Ports

By default, the cloning script automatically assigns free ports and lists them in the file portlist.ini. The algorithm for assigning default ports when cloning is the same as that used when installing Oracle Application Server.

When installing a new Oracle Application Server instance, you can specify the ports to be used by listing them in a staticports.ini file. Then, this file is passed as the value of a parameter when calling Oracle Universal Installer. For more information on how ports are assigned and on using the staticports.ini file, please refer to the Oracle Application Server Installation Guide for your platform.

When cloning an instance, you do not directly invoke Oracle Universal Installer. Hence, you cannot assign custom ports by specifying a staticports.ini file on the command line. However, you can still pass port information to Oracle Universal Installer indirectly, by specifying the location of the staticports.ini file in the configuration file cs.properties.

For example, if you want to use ports less than 1024, you can specify them in the staticports.ini file and specify the location of the staticports.ini file in the cs.properties file.

To assign custom ports during cloning:

1. List the port numbers in the staticports.ini file, as explained in the Oracle Application Server Installation Guide for your platform.

2. Specify the location of the staticports.ini file by adding the following line to the cs.properties file:

   clone_command_line = 
   oracle.iappserver.iapptop:szl_PortListSelect="{\"YES\", \"/tmp/staticports.ini\"}" 
   
   

The ports listed in the staticports.ini file are read during cloning, and Oracle Universal Installer assigns the port numbers accordingly.

If you specify ports less than 1024 on UNIX, 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.

oracle.iappserver.iapptop:szl_PortListSelect="{\"NO\", \"\"}" 

10.6.3 Updating Custom Data

By default, the cloning scripts update key configuration files in the Oracle home so they contain the correct information for the destination environment. Section 10.4.2 contains a partial listing of the files that are updated.

You can modify the default cloning process to update custom data that is not updated by default. Information about which files to update during cloning and which entries to update in those files is contained in another set of files, which are read by the cloning scripts. By editing these files, you can:

• Preserve changes you have made to files present in the source Oracle home that are not updated by default during cloning

• Preserve changes you have made to files that are updated by default during cloning, but which are not normally preserved by the cloning process

These changes are made by a Java utility called FileFixer, which searches for specific text strings in a file by matching regular expressions, and updates them to their new values. Note that FileFixer searches for patterns one line at a time. It cannot match patterns across lines.

The changes that you can make include the following:

• Change the host name in a file

  To do this, add the full path name for the file in which the host name needs to be changed to the following file:

  Oracle_Home/chgip/config/hostname.lst
  
  

• Update all occurrences of the Oracle home in a file from the old to the new value

  To do this, add a replace tag in the XML configuration file, fixup_script.xml.tmpl. This file is located in the following directory:

  • On UNIX systems:

    Oracle_Home/clone/ias/config

  • On Windows systems:

    Oracle_Home\clone\ias\config

  The value of the file_name attribute specifies the name and location of the file in which the replacement should occur. For example, the following tag updates the Oracle home value in the file dcmPlugins.xml.

  <cfw:operation>
     <replace file_name="%NEW_HOME%/sysman/config/dcmPlugins.xml">
           <cfw:replaceCommand>
              <cfw:pattern>(%OLD_HOME%)</cfw:pattern>
              <cfw:value_ref>1</cfw:value_ref>
              <cfw:new_value>%NEW_HOME%</cfw:new_value>
           </cfw:replaceCommand>
     </replace>
  </cfw:operation>
  
  

• Extract a value from file1 and use it to replace a value in file2

  To do this, add an alter tag in fixup_script.xml.tmpl. For example, adding the following tag will extract the new HTTP port number from the portlist.ini file in the cloned home and use it to replace the old port number in targets.xml, as shown in the following example:

  <cfw:operation>
      <alter cluster="false" alter_file_name="%NEW_HOME%/sysman/emd/targets.xml" 
  reference_file_name="%NEW_HOME%/install/portlist.ini">
         <cfw:alterCommand>
            <cfw:pattern>(Oracle HTTP Server port)([ ]*)(=)([ ]*)([0-9]*)
           </cfw:pattern>
            <cfw:value_ref>5</cfw:value_ref>
            <cfw:subst>(Property NAME=&quot;HTTPPort&quot;
                        VALUE=&quot;)([0-9]*)(&quot;)</cfw:subst>
            <cfw:subst_ref>2</cfw:subst_ref>
         </cfw:alterCommand>
      </alter>
  </cfw:operation>
  

10.7.1 Using Cloning to Expand an OracleAS Cluster

A common use of cloning is to expand the size of an OracleAS Cluster. Consider a OracleAS Cluster consisting of multiple J2EE and Web Cache middle tiers, with identical configuration and application deployment. To expand the OracleAS Cluster, you want to create a new middle-tier instance that has the same configuration as the other instances and add it to the cluster. This example assumes that the source instance is connected to a file-based repository and is a member of a farm and OracleAS Cluster.

The strategy for expanding an OracleAS Cluster consists of the following steps:

1. Remove the source instance from the OracleAS Cluster and farm. Because the instance is a member of a farm and cluster and is connected to a file-based repository, you must remove the instance from both the cluster and farm.

   To do this, issue the following commands at the source instance:

   dcmctl leaveCluster
   dcmctl leaveFarm
   
   

2. Prepare the source instance for cloning, using the steps described in Section 10.4.1:

   1. Perform Step 1 as described in Section 10.4.1.

   2. Perform Step 2 of Section 10.4.1.

      In that step, use a command similar to the following:

      perl prepare_clone.pl ORACLE_HOME=/opt/oracle/Ora_1012
      
      

   3. Perform Step 3 as described in Section 10.4.1.

3. Clone the source instance to create a new instance, using the steps described in Section 10.4.2:

   1. Perform Steps 1, 2, and 3 as described in Section 10.4.2.

   2. Perform Step 4 of Section 10.4.2.

      In that step, you must change the name of the cloned instance, by specifying it on the command line, as shown in the following example:

      perl clone.pl ORACLE_HOME=/opt/oracle/Ora_1012_B
                    ORACLE_HOME_NAME=OH_1012_B
                    -instance J2EE_B
                    -ias_admin_old_pwd my_old_ias_pass
                    -ias_admin_new_pwd my_new_ias_pass
      
      

      In this example, the instance name for the cloned instance is J2EE_B.

4. Add the source instance to the farm and the OracleAS Cluster, using the following commands:

   dcmctl joinFarm
   dcmctl joinCluster
   
   

5. Add the cloned instance to the farm and the OracleAS Cluster, using the following commands:

   dcmctl joinFarm
   dcmctl joinCluster
   

10.7.2 Cloning a Portal and Wireless Instance Front-Ended by a Load Balancing Router

Consider an environment where you have configured a Portal and Wireless middle-tier instance to be front-ended by a Load Balancing Router. Now, you want to add more instances with identical configuration and application deployment. The source instance is connected to OracleAS Infrastructure (Oracle Identity Management and OracleAS Metadata Repository). You want the new instances to be connected to the same OracleAS Infrastructure as the source instance and the same farm as the source instance.

Before you start the cloning, note the following:

• Make sure that the source instance is configured to work with a Load Balancing Router. See "Configuring Multiple Middle-Tiers with a Load Balancing Router" in the Oracle Application Server Portal Configuration Guide for more information.

• Review the limitations and considerations listed in Section 10.5, especially those in Section 10.5.2, Section 10.5.4, and Section 10.5.7.

• You must use the same port numbers for the cloned instance as for the source instance. To review the port numbers used by the source instance, navigate to the Application Server Control Console home page for the source instance and click Ports. To guarantee that the cloning process will assign the same ports for the cloned instance, you can use the staticports.ini file, as described in Section 10.6.2.

The strategy for cloning a Portal and Wireless middle tier connected to OracleAS Infrastructure and configured with a Load Balancing Router consists of the following steps:

1. Prepare the source instance for cloning, using the steps described in Section 10.4.1:

   1. Perform Step 1 as described in Section 10.4.1.

   2. Perform Step 2 of Section 10.4.1.

      In this scenario, you must specify the Oracle Internet Directory password on the command line, as shown in the following example:

      perl prepare_clone.pl ORACLE_HOME=/opt/oracle/Ora_1012
                            -oid_password my_oidpwd
      
      

   3. Perform Step 3 as described in Section 10.4.1.

2. To use the same ports as the source instance, use the staticports.ini file to specify the port numbers for the cloned instance. See Section D.1.2 for a list of the default ports used by a Portal and Wireless instance.

   See Section 10.6.2 for details on using the staticports.ini file.

3. Clone the source instance to create a new instance using the steps described in Section 10.4.2:

   1. Perform Steps 1, 2, and 3 as described in Section 10.4.2.

   2. On the cloned instance, rename the osso.conf file. See Section 10.5.6 for more information. You must perform this step before you run the clone.pl script if the source instance is connected to Oracle Identity Management.

   3. Perform Step 4 of Section 10.4.2. However, note the following:

      • You must specify the Oracle Application Server administration password and the Oracle Internet Directory password on the command line.

      • Because OracleAS Portal stores only a single set of configuration information, the cloning process overwrites the configuration entries stored in the repository if you do not specify that there is a Load Balancing Router. If you specify that there is a Load Balancing Router, the cloning process does not perform any configuration steps, and therefore it does not overwrite the configuration settings stored in the Portal schemas in the OracleAS Metadata Repository. To specify that there is a Load Balancing Router, use the -lbr option with the value of true in the clone.pl command line.

      The following example clones a Portal and Wireless instance and names the cloned instance as Portal_B:

      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
                    -lbr true
      
      

   When the cloning process is finished, both the source instance and the cloned instance are part of the farm.

   Note that when you log in to OracleAS Portal on the cloned instance, you use the original ias_admin password of the first OracleAS Portal instance associated with the OracleAS Metadata Repository. See Section 10.5.7 for more information.

4. The cloning process does not configure the Load Balancing Router to recognize the cloned instance. You must manually configure the Load Balancing Router. To configure OracleAS Portal with a Load Balancing Router, see the section, "Configuring Multiple Middle-Tiers with a Load Balancing Router" in Oracle Application Server Portal Configuration Guide.

5. From the source instance, using either Application Server Control Console or OracleAS Web Cache Manager, take the following steps:

   1. Add the cloned instance to the OracleAS Web Cache cluster.

   2. Add the cloned origin server as an origin server for the cluster.

   3. Save the OracleAS Web Cache changes and propagate the changes to the cluster.

   See the Oracle Application Server Web Cache Administrator's Guide for information configuring OracleAS Web Cache, particularly Chapter 10 about adding caches to a cache cluster and Chapter 8 for information about specifying origin servers. See the section "Configuring Multiple Middle-Tiers with a Load Balancing Router" in the Oracle Application Server Portal Configuration Guide for an example of these tasks in an OracleAS Portal environment with a Load Balancing Router.

6. Configure the Load Balancing Router to accept invalidation requests from OracleAS Metadata Repository on a separate port, so that requests are forwarded to OracleAS Web Cache. See the section, "Configuring Multiple Middle-Tiers with a Load Balancing Router" in the Oracle Application Server Portal Configuration Guide for more information.

7. Configure the Load Balancing Router to balance the load between the OracleAS Web Cache cluster members.

8. Re-register mod_osso for the source instance with the Load Balancing Router. See the section, "Configuring Multiple Middle-Tiers with a Load Balancing Router" in the Oracle Application Server Portal Configuration Guide.

9. Edit the httpd.conf file to change the port number to use the Load Balancing Router port rather than the local Oracle HTTP Server port.

10.7.3 Cloning a Business Intelligence Instance

Consider an environment where you have one Business Intelligence middle-tier instance and you want to add more instances with identical configuration and application deployment. The source instance is not (and cannot be) connected to OracleAS Infrastructure.

The strategy for cloning a Business Intelligence instance consists of the following steps:

1. Prepare the source instance for cloning, using the steps described in Section 10.4.1:

   1. Perform Step 1 as described in Section 10.4.1.

   2. Perform Step 2 of Section 10.4.1.

      In that step, use a command similar to the following:

      perl prepare_clone.pl ORACLE_HOME=/opt/oracle/Ora_1012_BI
      
      

   3. Perform Step 3 as described in Section 10.4.1.

2. Clone the source instance to create a new instance using the steps described in Section 10.4.2:

   1. Perform Steps 1, 2, and 3 as described in Section 10.4.2.

   2. Perform Step 4 of Section 10.4.2.

      In that step, you must change the name of the cloned instance, by specifying it on the command line, as shown in the following example:

      perl clone.pl ORACLE_HOME=/opt/oracle/Ora_1012_BI2
                    ORACLE_HOME_NAME=OH_1012_BI2
                    -instance BI2
                    -ias_admin_old_pwd my_old_ias_pass
                    -ias_admin_new_pwd my_new_ias_pass
      
      

      In this example, the instance name for the cloned instance is BI2.