Skip Headers
Oracle® Beehive Installation Guide
Release 1 (1.4) for Solaris Operating System (SPARC 64-Bit)

Part Number E13793-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

30 Cloning Oracle Beehive Application Tiers and Sites

This module covers the follwing topics:

This module also covers the following topics about customizing and troubleshooting the cloning process:

Introduction to Cloning

Cloning is the process of copying an existing installation to a different location while preserving its configuration.

Cloning enables you to safely modify an existing Oracle Beehive instance in production, such as installing a new patch or making changes to the database. Clone your existing Oracle Beehive instance and apply your changes to the clone. Once you have verified and certified that your changes work as expected, you may safely apply those changes to your Oracle Beehive instance in production.

A cloned installation behaves the same as the source installation. For example, you can uninstall or patch the cloned instance with the Oracle Beehive Install Wizard. You can also use a cloned installation as the source for another cloning operation.

The cloning process works by copying all files from the source Oracle home to the destination Oracle home. Hence, the cloning process does not copy any files used by the source instance that are located outside the source Oracle home's directory structure. After the files are copied, a set of beectl commands are used to update the information in key configuration files.

Note:

A wallet (if one has been configured in the source Oracle home) will be copied to the destination Oracle home. However, the clone will deliberately stop referring to the location of the wallet in the cloned application tier. You will have to manually reconfigure the wallet for the cloned application tier.

Do not overwrite the wallet in the cloned application tier.

Oracle Beehive services deployed in the source instance are also copied to the cloned instance and automatically deployed.

This module describes three cloning procedures: "Application Tier Cloning", "Site Cloning" and "OC4J Instance Cloning".

Application Tier Cloning

Application tier cloning involves the following steps:

  1. Preparing the source: This step involves creating an image of the application tier to clone, calling the beectl clone_preparation command, and archiving the required files in the Oracle home in a zip file. The cloned application tier is called the source instance or source image, and the zip file is called the clone image.

  2. Cloning the application tier: This step involves creating a new application tier. It involves unzipping the clone image and calling the beectl clone_midtier command. The new application tier is called the cloned application tier or target application tier.

The following image illustrates where a cloned application tier is located in relation to the database and the source application tier:

Figure 30-1 Application Tier Cloning

Description of Figure 30-1 follows
Description of "Figure 30-1 Application Tier Cloning"

Site Cloning

Site cloning involves the following steps:

  1. Cloning the information in the database: Oracle Beehive stores its centralized configuration information and business data in Oracle Database. This step involves cloning this data using standard database backup-recovery procedures (such as RMAN and export-import) into a new instance of Oracle Database. This ensures no overlap or sharing between the existing deployment (the cloned instance) and the new site (the new instance).

  2. Preparing the source: This step is the same as the one described in "Application Tier Cloning".

  3. Cloning the application tier instance in the new site: This step creates an application tier in the new site. It involves unzipping the image created during the preparing the source step, and calling the beectl clone_site command.

The following image illustrates where a cloned site (a cloned application tier and its database) is located in relation to the source database instance and source application tiers:

Note:

As Figure 30-2, "Site Cloning" illustrates, site cloning will create a single application tier in the cloned site irrespective of the number of application tiers in the source site.

To create multiple application tiers in the cloned site, follow the procedures for application tier cloning for each application tier.

Note that the cloned application tier will not be SSL enabled if the source application tier was. For more information, refer to "Cloned Application Tiers Are Not Automatically SSL or AJPS Enabled".

OC4J Instance Cloning

OC4J instance cloning enables you to clone Oracle Beehive's managed components. When you clone an Oracle Beehive managed component, a new OC4J instance is created and all the services in the source managed component are deployed in the newly cloned OC4J instance.

Oracle Beehive Integration for Zimbra Cloning

You may clone an instance of Oracle Beehive Integration for Zimbra. Refer to "Oracle Beehive Integration for Zimbra Cloning" for more information.

Preparing Source Application Tier Instance

Follow these steps to create a source image of the application tier you want to clone:

Step 1: Verify Requirements

Ensure that the chipset and the operating system version of the source computer is the same as the destination computer. (The source computer contains the installation of Oracle Beehive you want to clone.)

Windows

You must have administrator privileges to clone an installation of Oracle Beehive.

Step 2: Clear or Activate Any Pending Configuration Changes to the Central Configuration Repository

The cloning commands update the central configuration repository (the database tables of the Oracle Beehive schema).

If you have made any changes to the central configuration repository (for example, by running the beectl modify_property command), activate those changes by running beectl activate_configuration or clear them by running beectl clear_proposed_configuration.

Not activating or clearing any pending configuration changes may hinder the cloning process.

Step 3: Unset Environment Variables

Unset the environment variables ORACLE_HOME, ORACLE_SID, and LD_LIBRARY_PATH (if they have been set or defined in your system).

Oracle application scripts invoked by beectl cloning commands may fail if you do not unset these environment variables.

Step 4: Shut Down All Processes On the Application Tier

Call the command beectl stop --all to shut down all processes running in the source Oracle home.

Note:

Shutting down all processes in the application tier is not strictly required but it is advisable. This ensures that none of the files in the Oracle home are in use. You will later archive the Oracle home into a zip file. You may receive warnings or errors from your zip tool if some files are in use.

Step 5: Call beectl clone_preparation Command

The beectl clone_preparation command calls the Oracle Application Server prepare_clone.pl script, which creates local copies of several files that contain information useful for the cloning process. For example, this command creates a file in the Oracle home that contains the current host name and Oracle home path. The cloning process uses this information to search for and replace various strings in local configuration files on the target application tier.

This command also outputs a list of files (relative to the location of Oracle home) required to be zipped up to create the clone image.

The cloning commands (beectl clone_midtier and beectl clone_site) will fail if you have not called the beectl clone_preparation command previously:

beectl clone_preparation --file <fully qualified file name>

The following table describes the options for the beectl clone_preparation command:

Table 30-1 beectl clone_preparation Options

Option Mandatory/ Optional Description

--file

Mandatory

The name of the text file that will be created by the beectl clone_preparation command. This text file will contain the names of files in the source Oracle home to be copied for cloning to the target location.

All the files in source Oracle home need not be copied because log files, cache data, and other security files specific to the Oracle home will not be useful on the cloned Oracle home and may present a security concern.

Note: This text file must not be located in the Oracle home because you may receive warnings or errors from some zip tools about zipping an open file.


Step 6: Zip Files to Create Clone Image

First, verify that the command <Oracle home>/beehive/bin/hasbind is owned by the user who installed your Oracle Beehive instance; change the owner of the command if this is not the case.

Archive and compress the files listed in the file generated by the beectl clone_preparation command. Use a file archiver tool that can archive and compress a list of files that total at least 2 Gb in size. Also, make sure that the tool preserves the permissions and timestamps of the files. For example, you may use the tool 7-Zip, which you may download from http://www.7-zip.org/.

Use the following command to archive the Oracle Beehive home with the 7-Zip tool:

C:\7-zip\7z.exe a C:\clone_beehive.7z @C:\clone_prepare.txt

C:\clone_prepare.txt is the file generated by the beectl clone_preparation command. C:\clone_beehive.7z is the name of the file that contains the archived Oracle Beehive home.

WARNING:

Only archive and compress those files listed in the file generated by the beectl clone_preparation command, not the entire Oracle home you want to clone.

Alternatively, you may use the tar and gzip commands.

The following example shows how to archive and compress the source on Solaris:

cd <source Oracle home>
tar -cf - -I <file created by beectl clone_preparation command> | gzip >
  clone_image.tar.gz

Notes:

In some Solaris environments, because of stdout limitations, the gzip command may not be able to create a tar file of the Oracle home properly. In this case, use two commands to archive and compress the Oracle home:
  1. Create a tar file:

    cd $ORACLE_HOME
    tar cf /tmp/clone_beehive.tar -I /tmp/clone_prepare.txt
    
  2. Compress the tar file with gzip:

    gzip /tmp/clone_beehive.tar
    

The tar command may issue warnings if the sticky bit is set on some files. You can safely ignore these warnings.

Ensure that the file created by the tar command (in the previous example, this would be clone_image.tar.gz) is not located in the Oracle home; the tar command may fail.

You may receive an error message similar to the following when using this tar command:

tar: sqljdbc.dll: Cannot stat: No such file or directory
tar: instjdbc.sql: Cannot stat: No such file or directory
tar: sqljdbc.dll: Cannot stat: No such file or directory
tar: instjdbc.sql: Cannot stat: No such file or directory
tar: pool.jar: Cannot stat: No such file or directory
tar: Error exit delayed from previous errors

If you encounter this error, shutdown all processes on your Oracle Beehive application tier with the beectl stop --all command before creating the clone image again.

Do not use the jar utility to archive and compress the Oracle home. This avoids warnings or errors from the zip tool about zipping open files (for example, the <Oracle home>/jdk files).

Application Tier Cloning

Cloning the application tier consists of the following steps:

Step 1: Unzip Compressed Oracle Home

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

  2. Extract the compressed Oracle home into a directory, which will become the new Oracle home at the destination location.

    If you are using 7-Zip as your file archiver tool, extract the compressed Oracle home with the following commands:

    cd C:\new_oracle_home
    C:\7-zip\7z.exe x -r C:\clone_beehive.7z
    

    If you are using tar and gunzip, extract the compressed Oracle home with the following commands:

    mkdir -p <destination Oracle home>
    cd <destination Oracle home>
    gunzip < <directory containing tar file>/clone_image.tar.gz | tar xf -
    

    Notes:

    Make sure that the tar and gzip/gunzip versions on the source and destination computers are compatible. You may encounter problems unzipping the archive if these versions differ.

    The OS (operating system) user doing this must have permission to create and update the Oracle inventory. The Oracle inventory is a repository for all Oracle products installed on a host. This is typically a directory named oraInventory. The clone operations (described in the sections "Application Tier Cloning" and "Site Cloning") will try to create or update the existing Oracle inventory. If the OS user does not have permission, then cloning will fail, and it is not possible to recover from such failure. You will have to retry the cloning procedure.

    To determine with OS group has permission to update the Oracle inventory on Linux, see the file /etc/oraInst.loc. For Solaris, see the file /var/opt/oracle/oraInst.loc. For example:

    prompt> cat /etc/oraInst.loc/var/opt/oracle/oraInst.loc 
    inventory_loc=/private/beehive/oraInventory
    inst_group=g900
    

    In this example, OS users that belong to group g900 have permission to update the Oracle inventory, which is located in /private/beehive/oraInventory.

Step 2: Set PERL5LIB Environment Variable

You must have Perl 5.8.3 or later installed on your system.

Before running the cloning Perl scripts, 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.8.3/sun4-solaris-thread-multi:
  $ORACLE_HOME/perl/lib/5.8.3:
  $ORACLE_HOME/perl/lib/site_perl/5.8.3/sun4-solaris-thread-multi/

Step 3: Modify Oracle Home Path

Note:

This step applies only to UNIX-based operating systems.

The beectl command is a Perl script that has the path to Oracle home embedded in it. Modify this path to the new Oracle home. Execute the following beectl command to update the embedded Oracle home path. Note that in this case you must add the Perl executable path to the command:

$ORACLE_HOME/perl/bin/perl $ORACLE_HOME/beehive/bin/beectl modify_beectl
  --new_oracle_home <fully qualified path to new Oracle home>

The following table describes the options for the beectl modify_beectl command:

Table 30-2 beectl modify_beectl Options

Option Mandatory/ Optional Description

--new_oracle_home

Mandatory

Path of the new Oracle home.

Specify only a fully qualified path without trailing slashes. For example:

/app/oracle

Step 4: Execute beectl clone_midtier Command

The clone_midtier command creates a new application tier and configures it:

beectl clone_midtier [options]

Note:

If cloning fails during this step, you must restart the Oracle Beehive cloning process.

Delete the new Oracle home, and ensure that references to this Oracle home from the Oracle Universal Installer inventory are deleted.

Start the Oracle Beehive cloning process once again, preferably in a different directory Oracle home location.

Note that the beehive clone_midtier does not affect the application tier you are trying to clone. Therefore, you do not need to restore this application tier if cloning fails during this step.

The following table describes the options for the beectl clone_midtier command:

Table 30-3 beectl clone_midtier Options

Option Mandatory/ Optional Description

--ias_instance_name

Mandatory

The instance name for the clone.

Notes: The instance name should not contain the period (.) character nor the host name itself.

The instance name must be different from the source instance and any other instances that use the same Oracle Application Server infrastructure or that are part of the same cluster topology.

--host_name

Mandatory

The hostname of the computer on which the clone is being created. This must be the fully qualified hostname (with the domain appended). For example, hostB.example.com.

--db_schema_password

Mandatory

Database password for the BEE_CODE schema.

The password must be the same as the one used during the installation of the source application tier. This is the password of the Oracle Beehive database schema (typically BEE_CODE).

Note: If you are not in shell mode, you must obfuscate the database password and add the --obfuscated option to the beectl clone_midtier command.

To obfuscate a password, use the beectl obfuscate command:

beectl obfuscate
  --expiration_time_in_minutes 0
Enter value for password:
 
Successfully obfuscated the string.

--oui_inv_ptr_loc

Optional

Do not specify if it does not exist on the computer from which you are running this command; in this case, the Oracle inventory will be created in the user's home directory.

Oracle Universal Installer inventory location.

For more information, refer to "Oracle Inventory Location Option of Clone Commands on UNIX-Based Systems".

The Oracle Beehive cloning process internally uses the Oracle Universal Installer to update the Oracle inventory.

The value of this option specifies the Oracle Universal Installer inventory location. For example:

--oui_inv_ptr_loc "/var/opt/oracle/oraInst.loc"

Note: This value is platform-dependent. On Solaris it is /var/opt/oracle/oraInst.loc.

--oracle_home_name

Optional

Oracle home name. The default value is the value for the --ias_instance_name option.

--do_not_start_at_end

Optional

If true, Oracle Beehive will not start components after cloning. Permitted value is a boolean value.

Setting this option to true will prevent the cloned site from contacting external resources (such as LDAP, virus scanner, voicemail gateway, or Oracle Collaboration Coexistence Gateway (Windows only) of the source site.

If you run beectl clone_site for the first time from a source site that has an external source enabled, you will receive a warning message similar to the following:

WARNING : Processing UserDirectoryService : _UserDirectoryService
WARNING : UserDirectoryService is configured with following ENABLED directory profiles
WARNING :
WARNING : Directory profile id : 880c0691-0d10-4e07-9da0-6d23ab972105
WARNING : LDAP server id : AUTO_DTE_LDAP_example.com
WARNING : LDAP server name : example.com
WARNING : LDAP server port : 389
WARNING :  LDAP server SSL port : 636 

For this example, you would disable your directory profile before continuing.


Step 5: Perform Miscellaneous Operations

Note:

This step applies only to UNIX-based platforms.
  1. Run the root.sh script in the new Oracle home so that the cloned instance works properly. You must log in as the root user to run the script. The script is located in the cloned instance's Oracle home directory, for example: $ORACLE_HOME/root.sh.

  2. If this is the first Oracle installation on the host, run the orainstRoot.sh script as the root user to register the Oracle inventory directory. The script is located in the oraInventory directory.

Site Cloning

Run all the steps described in "Application Tier Cloning", except call the beectl clone_site command (instead of beectl clone_midtier).

Step 1: Unzip Compressed Oracle Home

This step is the same as "Step 1: Unzip Compressed Oracle Home".

Step 2: Set PERL5LIB Environment Variable

This step is the same as "Step 2: Set PERL5LIB Environment Variable".

Step 3: Modify Oracle Home Path

This step is the same as "Step 3: Modify Oracle Home Path"

Step 4: Execute beectl clone_site Command

Note:

If cloning fails during this step, you must restart the Oracle Beehive cloning process.

Delete the new Oracle home, and ensure that references to this Oracle home from the Oracle Universal Installer inventory are deleted.

Start the Oracle Beehive cloning process once again, preferably in a different directory Oracle home location.

The beectl clone_site command creates the first application tier in a site and configures it. This command clears the application tier topology of the old site from the central configuration repository (stored in the database) and creates a new topology for the new site with this as the first and only application tier. It then reconfigures the files on the new Oracle home to work against the new site.

This command is designed and tested so that none of the processes in the new site ever connect to the old site (and vice versa; the old site is ignorant of the new site).

Note:

The beectl clone_site also performs the following:
  • It clears the configuration of Oracle RAC nodes in the central configuration repository. In particular, it clears the properties XaServiceNames and OnsNodeConfiguration in the database configuration object. Because a new database has been created for the new site, the Oracle RAC configuration for the old database will not be needed.

  • It deletes the configuration of UnmanagedBeehiveInstance from the central configuration repository. In particular, the DMZ application tiers and their configurations are deleted.

  • UnmanagedOc4j is not deleted.

  • The site name is not changed. You may change the site name with the beectl modify_property command.

The following table describes the options of the beectl clone_site command:

Table 30-4 beectl clone_site Options

Option Mandatory/ Optional Description

--ias_instance_name

Mandatory

The instance name for the clone.

Notes: The instance name should not contain the period (.) character nor the host name itself.

The instance name must be different from the source instance and any other instances that use the same Oracle Application Server infrastructure or that are part of the same cluster topology.

--host_name

Mandatory

The hostname of the computer on which the clone is being created. This must be the fully qualified hostname (with the domain appended). For example, hostB.example.com.

--db_connect_string

Mandatory

Database connect string for the new site. This would be the connect string for the cloned database.

--db_schema_password

Mandatory

Database password for the schema.

Note: If you are not in shell mode, you must obfuscate the database password and add the --obfuscated option to the beectl clone_site command.

To obfuscate a password, use the beectl obfuscate command:

beectl obfuscate
  --expiration_time_in_minutes 0
Enter value for password:
 
Successfully obfuscated the string.

--db_schema_name

Optional

New database schema name. Typically, this would be the same schema as the old site, which is usually BEE_CODE.

--db_rac_node_information

Optional

New values for the host:port of Oracle RAC nodes.

The host name should not be the VIP hostname. Specify the actual computer name instead.

The port should be the ONS remote port, which is also known as the CRS port. This port number is specified in the file <Oracle RAC database home>/opmn/conf/ons.config.

This option is required to configure ONS properly for Fast Connection Failover, which provides failover for a JDBC connection to a RAC database.

This option can be specified more than once and values will form an array in the given order. For example:

--db_rac_node_information "hostnode1.example.com:1521"

--db_rac_node_information "hostnode2.example.com:1521"

--db_rac_node_information "hostnode3.example.com:1525"

--db_xa_service_name

Optional

New values for the service names of Oracle RAC nodes. This option can be specified more than once and values will form an array in the given order. For example:

--db_xa_service_name node1_service_name

--db_xa_service_name node2_service_name

--db_xa_service_name node3_service_name

--retain_rac_node_information

Optional

Retain existing values for db_xa_service_name and db_rac_node_information. This option cannot be specified with --db_xa_service_name and --db_rac_node_information.

--oracle_home_name

Optional

Oracle home name. The default value is the value provided for the --ias_instance_name option.

--oui_inv_ptr_loc

Optional.

Do not specify if it does not exist on the computer from which you are running this command; in this case, the Oracle inventory will be created in the user's home directory.

Oracle Universal Installer inventory location.

For more information, refer to "Oracle Inventory Location Option of Clone Commands on UNIX-Based Systems".

The Oracle Beehive cloning process internally uses the Oracle Universal Installer to update the Oracle inventory.

The value of this option specifies the Oracle Universal Installer inventory location. For example:

--oui_inv_ptr_loc "/var/opt/oracle/oraInst.loc"

Note: This value is platform-dependent. On Solaris, it is /var/opt/oracle/oraInst.loc.

--do_not_start_at_end

Optional

If true, Oracle Beehive will not start components after cloning. Permitted value is a boolean value.

Setting this option to true will prevent the cloned site from contacting external resources (such as LDAP, virus scanner, voicemail gateway, or Oracle Collaboration Coexistence Gateway (Windows only) of the source site.

If you run beectl clone_site for the first time from a source site that has an external source enabled, you will receive a warning message similar to the following:

WARNING : Processing UserDirectoryService : _UserDirectoryService
WARNING : UserDirectoryService is configured with following ENABLED directory profiles
WARNING :
WARNING : Directory profile id : 880c0691-0d10-4e07-9da0-6d23ab972105
WARNING : LDAP server id : AUTO_DTE_LDAP_example.com
WARNING : LDAP server name : example.com
WARNING : LDAP server port : 389
WARNING :  LDAP server SSL port : 636 

For this example, you would disable your directory profile before continuing.

--site_name

Optional (Oracle Beehive Release 1 (1.3) and later)

If you specify this option, the site cloning process will clone Oracle Beehive on the target application tier with this new name as the site name of the cloned application tier.

--ignore_validation_warnings

Optional

If you specify this option, the site cloning process will proceed regardless of warnings about target application tiers referring to external resources. Refer to "Step 5: Prevent Services from Target Application Tiers from Referring to External Resources" for more information about external resources.


Step 5: Prevent Services from Target Application Tiers from Referring to External Resources

In a typical Oracle Beehive installation, Oracle Beehive services may refer to some external resources such as an LDAP server or a virus scan engine. If you perform a site clone of such an installation, the target application tier may also refer to the same external resources.

After running the command beectl clone_site, prevent any Oracle Beehive services of the target application tier from referring to the external resources of the source site. Afterwards, you may configure the target application tier to refer to a new set of external resources.

The beectl clone_site command will return warning or error messages if the target application tier refers to any external resources. If you do not receive any warning or error messages, proceed to the next step.

If you do receive any warning or error messages from beectl clone_site about external resources, stop any Oracle Beehive service from referring to an external resource by following one or more of these steps:

Notes:

Only perform these steps on the target application tier; do not perform these steps on the source site.

These steps are only applicable for cloning a site; do not perform these steps if you are cloning an application tier.

The target application tier may not work as expected during the time between the completion of site cloning process and the modification of Oracle Beehive services to refer to a new set of external resources.

Stopping User Directory Service from Referring to LDAP Server

If you have synchronized User Directory Service (UDS) with an external LDAP server (as described in "Integrating and Synchronizing LDAP with Oracle Beehive"), then disable all the directory profiles from your target application tier:

  1. Retrieve a list of all directory profile objects in your target application tier:

    beectl list_components --type  "UserDirectoryService\$DirectoryProfile"
    
  2. For each directory profile ID, run the following command:

    beectl modify_property
      --component <directory profile ID>
      --name ProfileState
      --value DISABLE
      --activate_configuration 
    

Stopping Authentication Service from Referring to LDAP Server

If you have followed the steps described in "Configuring Authentication Service to Use LDAP Server", change the authentication mode to use the database instead in your target application tier:

  1. Retrieve the Authentication Service ID of your target application tier:

    beectl list_components --type AuthenticationService
    
  2. Change the property AuthStoreType to db:

    beectl modify_property
      --component <Authentication Service ID>
      --name AuthStoreType
      --value db
      --activate_configuration
    

Stopping Virus Scanner Process from Referring to External Virus Scan Engine

To stop the virus scanner process from referring to an external virus scan engine, remove the reference of VirusScannerCluster from _CURRENT_SITE of your target application tier with the following command:

beectl  modify_property
  --component _CURRENT_SITE
  --name VirusScanEngineCluster
  --revert_to_default

Step 6: Perform Miscellaneous Operations

Perform the steps described in "Step 5: Perform Miscellaneous Operations". Afterwards, ensure that the cloned database has the same name as the original database name. (This is required so that Change Data Capture works properly.) If the cloned database name is different from the original database name, change GLOBAL_NAME with the command ALTER DATABASE RENAME GLOBAL_NAME. Refer to Oracle Database SQL Reference for more information.

OC4J Instance Cloning

OC4J instance cloning enables you to clone Oracle Beehive's managed components, in particular, the OC4J managed components BEEAPP, oc4j_soa, and BEECORE. You may not clone BEEMGMT.

The beectl clone_oc4j_instance command clones an Oracle Beehive managed component by creating a new OC4J instance and deploying all the services in the source managed component in the newly cloned OC4J instance. You may only clone Oracle Beehive managed components with this command; you may not clone non-Oracle Beehive OC4J instances.

Note:

If you are cloning the BEEAPP managed component, you must backup Oracle Beehive before and after creating the clone.

The BEEAPP clone makes changes to the application tier's configuration files that the beectl modify_local_configuration_files command cannot update when restoring Oracle Beehive from a previous backup.

The following table describes the options of the beectl clone_oc4j_instance command:

Table 30-5 beectl clone_oc4j_instance Options

Option Mandatory/ Optional Description

--source_oc4j_instance_id

Either this option or --source_oc4j_instance_name is required

ID of the managed component to be cloned, for example, BEEAPP_instance1.example.com

--source_oc4j_instance_name

Either this option or --source_oc4j_instance_id is required

Prefix of the managed component to be cloned, for example BEEAPP, oc4j_soa, or BEECORE

--target_oc4j_instance_name

Mandatory

Name of the new OC4J instance to be created. The application tier instance name and the host name will be appended to this name to create the ID of the new OC4J instance.

For example, if you specify BEEAPP_CLONE, its ID will be similar to BEEAPP_CLONE_instance1.example.com.

--exclusion_list

Optional

List of services to exclude from the newly created OC4J instance

--working_list

Optional

List of services that will only be deployed on the newly created OC4J instance.


The following example clones BEEAPP_instance1.example.com, which creates a new OC4J instance with the ID BEEAPP_CLONE_instance1.example.com and deploys all the services in BEEAPP in BEEAPP_CLONE except for ClientManagementService:

beectl clone_oc4j_instance
  --source_oc4j_instance_name BEEAPP
  --target_oc4j_instance_name BEEAPP_SOURCE
  --exclusion_list ClientManagementService

Oracle Beehive Integration for Zimbra Cloning

Oracle Beehive Integration for Zimbra is available for Oracle Beehive Release 1 (1.3) and later.

You may clone an instance of Oracle Beehive Integration for Zimbra; follow the steps described in "Application Tier Cloning" and apply them to the Oracle Beehive Integration for Zimbra home.

Note:

Site cloning is only possible for a server application tier, such as Oracle Beehive; it is not possible for a client application tier, such as Oracle Beehive Integration for Zimbra.

Customizing Files or Directories in a Cloned Image

The beectl clone_preparation command controls which files or directories are packaged in the clone image, which you may customize.

The beectl clone_preparation command refers to the file <Oracle home>/beehive/conf/scripts/exclude_while_cloning.txt to obtain the list of files and directories that will be excluded from the clone image.

You may customize this file before executing the beectl clone_preparation command.

The comments section in this file describes how to customize it.

Customizing Ports in a Cloned Instance

The beectl clone_midtier and clone_site commands retain the port values from the source application tier configuration. That is, the cloned application tier will listen on the same ports as the source application tier.

You may customize the ports before executing the beectl clone_midtier and clone_site commands by updating the file <Oracle home>/beehive/conf/scripts/clone_ports.ini. The comments section in this file describes how to override port values.

This file is just an overriding mechanism and does not contain the existing ports, in particular, the ports on which source application tier instance is listening. You may call the beectl list_ports command on the source application tier instance to view the existing port assignments, which will also be the port assignments for the cloned application tier instance.

Cloning Application Tiers and Sites with Ports Less Than 1024

If the source application tier or site has been configured with ports less than 1024, and you want to retain the same ports in the cloned application tier or site, follow these steps during the cloning process:

  1. Perform "Step 6: Zip Files to Create Clone Image" as the root user. Certain files, such as <Oracle home>/beehive/bin/hasbind and <Oracle home>/Apache/Apache/bin/.apachectl, require more permissions to be archived properly.

  2. Run the beectl clone_midtier or beectl clone_site commands with the option --do_not_start_at_end to ensure that no Oracle Beehive processes are started after a successful cloning. This will prevent some processes from failing because they still have to be configured for privileged ports (less than 1024).

  3. Configure the cloned application tier or site by following the steps described in "Configuring Oracle Beehive to Listen on Ports Less Than 1024".

If you cloned an application tier or a site with ports less than 1024, and you want to reconfigure the ports of the cloned application tier or site to use non-privileged ports (greater than 1024), then follow the steps described in "Customizing Ports in a Cloned Instance".

Oracle Inventory Location Option of Clone Commands on UNIX-Based Systems

Typically, information about Oracle products on a UNIX-based host are stored in a single location, the Oracle inventory. The location of the Oracle inventory is defined in the Oracle inventory location pointer file. For Solaris, the Oracle inventory location pointer file is /var/opt/oracle/oraInst.loc:

prompt>cat /var/opt/oracle/oraInst.loc
inventory_loc=/private/beehive/oraInventory
inst_group=g900

The beectl clone_midtier and clone_site commands (with the aid of Oracle Application Server scripts) use the Oracle inventory location pointer from its default location (/var/opt/oracle/oraInst.loc on Solaris) to determine the location of the Oracle inventory. The Oracle inventory is updated with any new Oracle Beehive application tier instance information so that the standard Oracle install and upgrade tools such as Oracle Universal Installer and Opatch will work seamlessly on the cloned application tier instance.

The Oracle inventory location pointer file can be located elsewhere. If this file is not located in the platform default location (/var/opt/oracle/oraInst.loc on Solaris), then you must specify its location when executing the beectl clone_midtier and clone_site commands.

Cloned Application Tiers Are Not Automatically SSL or AJPS Enabled

Cloned application tiers are not SSL or AJPS enabled even if the source image is SSL or AJPS enabled.

Enabling SSL and AJPS is a post-install configuration step. Currently, the Oracle Beehive cloning process deliberately does not preserve the SSL and AJPS settings of the source image because the process of enabling them is specific to each application tier and requires administrator input (such as the generation of new certificates).

You must individually enable SSL and AJPS for each of your cloned application tiers. Note that the source application tier is not affected and will remain SSL and AJPS enabled.

For more information about configuring SSL, or more specifically TLS (Transport Layer Security), which is the successor of SSL, and AJPS, refer to the following modules:

Cloning SSL-Enabled Application Tiers

If you have cloned an SSL-enabled application tier with self-signed certificates, then follow these steps to enable SSL for your cloned application tier:

  1. Recreate the self-signed certificates on the cloned application tier.

  2. Perform "Step 2: Configuring Oracle Beehive Instance to Use Oracle Wallet" in "Configuring TLS with Oracle Wallet".

If you have cloned an SSL-enabled application tier with test certificates, you only need to perform "Step 2: Configuring Oracle Beehive Instance to Use Oracle Wallet" in "Configuring TLS with Oracle Wallet".

Cloned Application Tiers and LDAP Synchronization

If you have cloned an application tier that you have synchronized with an LDAP server, as described in "Integrating and Synchronizing LDAP with Oracle Beehive", the cloned application tier should still be synchronized with the same LDAP server.

However, if you have configured the Domain Name Service (DNS) on the host of the source instance, as described in "Active Directory Considerations", you must perform the same configurations on the host of the cloned instance.

If you wish to synchronize your cloned Oracle Beehive instance with another LDAP server, that LDAP server must be a clone of the source LDAP server. It must have matching GUIDs as the source LDAP server, although not necessarily matching hostname, port, or administrator credentials. Refer to the next section, "Replicating LDAP Server for Cloned Instance" to create a clone of the source LDAP server (these directions are specific to Oracle Internet Directory).

Replicating LDAP Server for Cloned Instance

If you have cloned an application tier that you have synchronized with an LDAP server, the cloned application tier will be synchronized with the same LDAP server. However, if you wish to synchronize the cloned instance with a replicated LDAP server instead, follow the steps in this section.

These steps only apply to a source instance that is synchronized with Oracle Internet Directory.

  1. Install a new instance of an LDAP server for the cloned instance.

    • If you are using Oracle Internet Directory, install it in replicated mode. You may choose any type of replication (LDAP replication or Advanced Replication). However, you probably only need one-way LDAP replication; you probably do not want changes in the cloned LDAP server to be propagated to the source LDAP server.

      For more information about installing Oracle Internet Directory in replicated mode, refer to Chapter 6, "Installing Oracle Internet Directory in Replicated Mode" in Oracle Application Server Installation Guide for Solaris Operating System (SPARC 64-Bit.

    • If you are using Active Directory, create a new domain controller.

  2. Add a replica of the supplier (the source LDAP server) to the LDAP server you just created (which is called the consumer). Replicate the nodes specified in the source instance's LDAP mapping profile (in particular, the DNs specified in <user_search_base> and <groups_search_base>).

    • If you are using Oracle Internet Directory, for more information about adding a replica, refer to Chapter 30, "Oracle Internet Directory Replication Installation and Configuration" in Oracle Internet Directory Administrator's Guide.

    • If you are using Active Directory, create a new replica of the application directory partition and add it to the domain controller you created in the previous step. (In particular, replicate the application directory partitions identified by <user_search_base> and <groups_search_base> in the source instance's LDAP mapping profile, then add those replicas to the domain controller you created in the previous step.)

  3. Ensure that the names of the LDAP mapping profiles of the source and cloned instances are the same.

  4. If you are using Oracle Internet Directory, set the attribute orclDIPRepository to true in your consumer.

  5. Retrieve the LDAP mapping profile from the source instance with the following command:

    beectl list_directory_profiles --file <your home directory>/source_profile.xml
    

    The LDAP mapping profile will be saved in the file specified by the --file option; in this example, this file is <your home directory>/source_profile.xml.

  6. Update LDAP mapping profile you just retrieved (<your home directory>/source_profile.xml) with values that correspond to the cloned instance and the replicated LDAP server:

    • Set <profile_state> to DISABLE

    • Update the obfuscated <ldap_user_password>. Call the following command on the cloned instance to get a new obfuscated password for the LDAP administrator's password:

      beectl obfuscate --expiration_time_in_minutes 0
      
    • Ensure that the enterprise and organization IDs are correct for the cloned instance.

    • Change the SSL and non-SSL port, if required.

  7. Delete the existing profile on the cloned instance:

    beectl delete_directory_profile --profilename "My Profile"
    

    Retrieve the name of the existing profile from the <profile_name> element.

  8. Add the LDAP mapping profile you modified in step 6 to the cloned instance:

    beectl add_directory_profile --file ~/source_profile.xml
    
  9. Restart the BEECORE and BEEMGMT processes on the cloned instance:

    beectl status
     
    ------------------------------------------------+--------
    Component identifier           | Component type | Status  
    ------------------------------------------------+--------
    BTI_instance1.example.com      | BTI            | RUNNING 
    ------------------------------------------------+--------
    BEEAPP_instance1.example.com   | OC4J           | RUNNING 
    ------------------------------------------------+--------
    BEEMGMT_instance1.example.com  | OC4J           | RUNNING 
    ------------------------------------------------+--------
    BEECORE_instance1.example.com  | OC4J           | RUNNING 
    ------------------------------------------------+--------
    oc4j_soa_instance1.example.com | OC4J           | RUNNING 
    ------------------------------------------------+--------
    ohs_instance1.example.com      | HTTP_Server    | RUNNING 
    -------------------------------+----------------+--------
    
    beectl restart --component BEEMGMT_instance1.example.com
    beectl restart --component BEECORE_instance1.example.com
    
  10. This step is optional. Temporarily disable LDAP authentication with the following beectl commands:

    beectl modify_property --component _AuthenticationService
      --name AuthStoreType --value db
    beectl activate_configuration
    beectl modify_local_configuration_files
    
  11. Update the BEE_DATA.UDS_SYNC_PROFILE table with the changelog information from the replicated LDAP server:

    SELECT chg_no FROM ods.ods_chg_log WHERE rownum = 1 ORDER BY chg_no desc;
     
    
    1. If you are using Oracle Internet Directory, retrieve the change log value from the replicated Oracle Internet Directory by executing the following query on the Oracle Directory Server (ODS) schema:

      SELECT chg_no FROM ods.ods_chg_log WHERE rownum = 1 ORDER BY chg_no desc;
       
      
    2. If you are using Active Directory, retrieve the change log value from the domain controller that contains your replicated users and groups with the following command:

      ldapsearch
        -p <Port of the domain controller>
        -h <Hostname of the domain controller>
        -D "<Administrator name of the Active Directory's Windows domain>"
        -w "<Administrator Password>"
        -b ""
        -s base "objectclass=*"  
        highestCommittedUSN
      
    3. Update the BEE_DATA.UDS_SYNC_PROFILE table:

      UPDATE bee_data.uds_sync_profile
        SET changeid = <Value retrieved from previous query>;
      
  12. Re-enable LDAP synchronization:

    beectl modify_property --component <Profile name>
      --name ProfileState --value ENABLE
    beectl activate_configuration
    beectl restart --all
    
  13. Re-enable LDAP authentication:

    beectl modify_property --component _AuthenticationService
      --name AuthStoreType --value ldap
    beectl activate_configuration
    beectl modify_local_configuration_files
    

Testing Replicated LDAP in Cloned Instance

Perform these tasks to ensure that the replicated Oracle Internet Directory server is working in your cloned instance:

  1. Create a new user in your source Oracle Internet Directory instance

  2. Check your source Oracle Beehive instance; the new user you created should appear in UDS.

  3. Check the ODS_CHG_LOG table from the ODS schema from the replicated Oracle Internet Directory instance. You should see your changes; expect a delay of one hour.

  4. Between fifteen to thirty minutes later, you should see a change in the cloned Oracle Beehive instance's UDS.

Troubleshooting Replicated LDAP

Site Cloning and Multiple Instances

Oracle Beehive site cloning will result in a single application tier in the cloned site irrespective of the number of application tiers in the source site. To create more application tiers in the cloned site, follow the procedures described in "Application Tier Cloning" in the cloned site. Note that a cloned application tier will not be SSL enabled even if the source image is SSL enabled. Refer to "Cloned Application Tiers Are Not Automatically SSL or AJPS Enabled" for more information.

References to Oracle Application Server Cloning Documentation

Oracle Beehive cloning scripts internally use Oracle Application Server cloning scripts to clone Oracle Application Server components such as OC4J on which Oracle Beehive is based. Refer to the following sections in Chapter 9, "Cloning Application Server Middle-Tier Instances" in Oracle Application Server Administrator's Guide: