2 Using the dcmctl Utility

2.2.1 Designating the OracleAS File-Based Farm Repository Host

You must designate the Oracle Application Server Instance that will be the repository host of the OracleAS File-Based Farm. The Oracle Application Server Instance you designate must be a standalone Oracle Application Server Instance (that is, not associated with any OracleAS Farm). Follow these steps to designate the repository host of a OracleAS File-Based Farm:

1. Navigate to the Oracle Application Server Instance that will be the repository host Oracle Application Server Instance.

2. Determine whether it is a standalone Oracle Application Server Instance by issuing this command:

   dcmctl whichFarm
   
   

   If dcmctl returns an OracleAS File-Based Farm name, the Oracle Application Server Instance is still part of an OracleAS File-Based Farm, and is thus still associated with an existing repository. To place the Oracle Application Server Instance in a standalone state:

   1. Issue this command:

      dcmctl leaveFarm
      
      

      The Oracle Application Server Instance is now in a standalone state, and all components running in it are stopped.

3. Issue this command:

   dcmctl getRepositoryID
   
   

   dcmctl returns a repository identifier in the format hostname:port.

4. Issue this command:

   dcmctl joinFarm -r repository ID
   
   

   In the preceding command, repository ID is the hostname:port value returned by the getRepositoryID command.

   The current Oracle Application Server Instance is established as the repository host instance of the OracleAS File-Based Farm. The OracleAS File-Based Farm configuration information is stored in the file-based repository in the repository host Oracle Application Server Instance.

2.2.2 Adding Instances to an OracleAS Farm

An Oracle Application Server Instance can be part of an OracleAS Farm as a standalone Oracle Application Server Instance (without also being a DCM-Managed OracleAS Cluster member) as shown in Figure 2-1. This makes it possible to manage as one unit a collection of UNIX, Windows, and Linux Oracle Application Server Instances. (Instances of like operating systems may be clustered; however, before an Oracle Application Server Instance can join a DCM-Managed OracleAS Cluster, it must be in the OracleAS Farm). Follow these steps to bring an Oracle Application Server Instance into an OracleAS File-Based Farm:

1. Obtain the repository ID of the repository host Oracle Application Server Instance of the OracleAS File-Based Farm the Oracle Application Server Instance will join (if necessary, by issuing this command):

   dcmctl getRepositoryID
   
   

   dcmctl returns a repository identifier in the format hostname:port.

2. In the Oracle Application Server Instance that will join the OracleAS File-Based Farm, issue this command:

   dcmctl joinFarm -r repository ID
   
   

   In the preceding command, repository ID is the repository identifier returned in Step 1.

3. (Optional) Verify that the OracleAS File-Based Farm was joined as expected by issuing this command:

   dcmctl whichfarm -v
   
   

   dcmctl returns the farm name, host instance name, host name and repository type.

2.2.3 Creating a DCM-Managed OracleAS Cluster

A DCM-Managed OracleAS Cluster is created as a member of an Oracle Application Server Farm, as depicted in Figure 2-1. Follow these steps to create a DCM-Managed OracleAS Cluster:

1. Navigate to the Oracle home of an Oracle Application Server Instance that belongs to the OracleAS Farm in which you want to create a DCM-Managed OracleAS Cluster.

2. Issue this command:

   dcmctl createCluster -cl nameOfCluster
   
   

   In the preceding command, nameOfCluster is the identifier for the DCM-Managed OracleAS Cluster.

   
   

   Tip: See createCluster for syntax and rules, or issue the command dcmctl help createcluster to view help text.

   
   

   dcmctl lists the DCM-Managed OracleAS Clusters as shown:

   1  cluster2
   2  cluster1
   
   

   The DCM-Managed OracleAS Cluster does not have any member Oracle Application Server Instances upon creation. You add Oracle Application Server Instances to the DCM-Managed OracleAS Cluster using the joinCluster command.

2.2.4 Understanding DCM-Managed OracleAS Cluster Membership

After a DCM-Managed OracleAS Cluster is created, you can add Oracle Application Server Instances to it. Before you add an Oracle Application Server Instance to an DCM-Managed OracleAS Cluster, review and understand the following guidelines about DCM-Managed OracleAS Cluster configuration and the characteristics of clusterable Oracle Application Server Instances.

2.2.5 Adding an Instance to a DCM-Managed OracleAS Cluster

Follow these instructions to add an Oracle Application Server Instance to an DCM-Managed OracleAS Cluster:

1. (Optional) Find the names of the DCM-Managed OracleAS Clusters in the local OracleAS Farm by issuing this command:

   dcmctl listClusters
   
   

   dcmctl returns a list of DCM-Managed OracleAS Cluster names that belong to the OracleAS Farm that is associated with the local Oracle Application Server Instance.

2. Navigate to the Oracle Application Server Instance that you want to join to the DCM-Managed OracleAS Cluster.

3. (Optional) Determine whether the Oracle Application Server Instance can be added to a DCM-Managed OracleAS Cluster by issuing this command:

   dcmctl isClusterable
   
   

   If dcmctl returns true, then continue with Step 4.

4. Issue this command:

   dcmctl joinCluster -cl nameOfCluster
   
   

   In the preceding command, nameOfCluster is the identifier for the DCM-Managed OracleAS Cluster you want the Oracle Application Server Instance to join.

   
   

   Tip: See joinCluster for instructions on joining an Oracle Application Server Instance other than the local Oracle Application Server Instance to an DCM-Managed OracleAS Cluster, or issue the command dcmctl help joincluster to view help text.

   
   

   The Oracle Application Server Instance is joined to the DCM-Managed OracleAS Cluster and stopped. The dcmctl joincluster command lists the Oracle Application Server Instances in the DCM-Managed OracleAS Cluster in the following format:

   1  10g01.my.pc.mycompany.com
   2  10g02.my.pc.mycompany.com
   
   

5. (Optional) Start the Oracle Application Server Instance by issuing this command:

   opmnctl startall
   
   

2.2.6 Removing an Oracle Application Server Instance From a DCM-Managed OracleAS Cluster

Follow these instructions to remove an Oracle Application Server Instance from a DCM-Managed OracleAS Cluster:

1. (Optional) Find the names of the Oracle Application Server Instances in the DCM-Managed OracleAS Cluster by issuing this command:

   dcmctl listInstances -cl nameOfCluster
   
   

   dcmctl returns a list of Oracle Application Server Instance names in the DCM-Managed OracleAS Cluster.

2. Navigate to the Oracle Application Server Instance that you want to remove from the DCM-Managed OracleAS Cluster.

3. Issue this command:

   dcmctl leaveCluster 
   

   
   

   Tip: See leaveCluster for instructions on removing an DCM-Managed OracleAS Cluster from an Oracle Application Server Instance other than the local Oracle Application Server Instance, or issue the command dcmctl help leavecluster to view help text.

   
   

2.2.7 Exporting and Importing Configurations From a File-based Repository

One of the benefits of managing configurations with DCM is that configuration information is portable from one Oracle Application Server Instance to another. This section explains how to save and restore a repository and move an Oracle Application Server Instance from one repository to another.

Oracle Application Server provides commands to save a file-based repository, so that you can restore it if the repository host Oracle Application Server Instance stops functioning, or its file system is damaged. The exportRepository command saves the file-based repository; then, with the importRepository command, you can restore the saved configuration information to the repository host Oracle Application Server Instance, or to a different Oracle Application Server Instance in the OracleAS File-Based Farm.

To export the repository from the repository host Oracle Application Server Instance, issue this command:

dcmctl exportRepository -file file name

In the preceding command, file name is the name of the file in which the configuration information will be stored.

Follow these steps to import a saved file-based repository:

1. Stop the DCM daemon in each Oracle Application Server Instance of the OracleAS File-Based Farm except for the current Oracle Application Server Instance (in which you are using dcmctl). Issue the following command in each Oracle Application Server Instance of the OracleAS File-Based Farm:

   ORACLE HOME/opmn/bin/opmnctl stopproc ias-component=dcm-daemon
   
   

2. Issue this command on the system that is to be the repository host Oracle Application Server Instance for the OracleAS File-Based Farm:

   dcmctl importRepository -file file name
   
   

   In the preceding command, file name is the name of the file you specified in the exportRepository command.

3. On the system that was the repository host, indicate that the Oracle Application Server Instance is no longer the host Oracle Application Server Instance by issuing the following command:

   dcmctl repositoryRelocated
   
   

2.2.8 Moving an Instance From One OracleAS File-Based Farm to Another

You can move an Oracle Application Server Instance that belongs to one OracleAS File-Based Farm to another OracleAS File-Based Farm. To move to another repository, you use the leaveFarm and joinFarm commands.

When an Oracle Application Server Instance leaves an OracleAS File-Based Farm, it becomes a standalone Oracle Application Server Instance. This means that:

• The Oracle Application Server Instance's DCM-managed configuration metadata in the repository is moved to the Oracle Application Server Instance's local, file-based repository.

• Archives of the Oracle Application Server Instance remain in the farm; they are not moved to the new farm.

• If there are connections to the Infrastructure database for other components (Oracle Application Server Single Sign-On, Oracle Application Server Java Authentication and Authorization Service (JAAS) Provider, and Oracle Internet Directory) they remain.

Follow these steps to move an Oracle Application Server Instance from one repository to another:

1. Issue the following command in the Oracle Application Server Instance that you will move to another OracleAS File-Based Farm:

   dcmctl whichFarm
   
   

   If dcmctl returns an OracleAS File-Based Farm name, the Oracle Application Server Instance is still part of a OracleAS File-Based Farm, and is thus still associated with an existing repository.

2. Issue this command:

   dcmctl leaveFarm
   
   

   The Oracle Application Server Instance is now in a standalone state.

3. Use the createArchive command to create a baseline archive of the Oracle Application Server Instance. For example:

   dcmctl createArchive -arch myArchive
   

4. Issue the following command in one of the Oracle Application Server Instances that belongs to the OracleAS File-Based Farm whose repository the Oracle Application Server Instance will join:

   dcmctl getRepositoryId
   
   

   dcmctl returns the repository identifier in the format hostname:port.

5. Join the Oracle Application Server Instance to the OracleAS File-Based Farm of the repository identified in Step 4 by issuing this command:

   dcmctl joinFarm -r repository ID
   
   

   
   

   Note: The change will not be reflected in the Application Server Control Console until it is restarted. In the ORACLE_HOME/bin directory, issue these commands: ORACLE_HOME/bin> emctl stop iasconsole ORACLE_HOME/bin> emctl start iasconsole

   
   

2.2.9 Moving An Instance to a OracleAS Database-Based Farm

You can use the dcmctl utility to move an Oracle Application Server instance that is joined to a OracleAS File-Based Farm to a OracleAS Database-Based Farm.

To move an instance from a OracleAS File-Based Farm to an OracleAS Database-Based Farm, first disassociate the instance from its current repository by leaving the OracleAS File-Based Farm. The instance is then in a standalone state, and you can join the instance to the OracleAS Database-Based Farm.

Follow these steps to move the instance:

1. Determine whether the instance is still part of an OracleAS File-Based Farm using the following command:

   dcmctl whichFarm
   
   

2. If the output indicates that the instance is part of a OracleAS Database-Based Farm, issue the following command to put the instance in a standalone state:

    dcmctl leaveFarm 
   
   

3. If you want the instance to join a OracleAS Database-Based Farm, and the instance was previously a member of that OracleAS Database-Based Farm, use the following command to rejoin the OracleAS Farm:

   dcmctl joinFarm
   
   

   If this step fails, then the instance was not previously a member of the OracleAS Database-Based Farm. Therefore, its configuration metadata is not in the DCM repository, which means that you will need to use Application Server Control Console to join the OracleAS Database-Based Farm.

2.2.10 Moving an Instance to an OracleAS File-Based Farm

2.2.11 Enabling SSL For Communication Between Instances in an OracleAS File-Based Farm

You can configure DCM to send configuration information between instances using the Secure Sockets Layer (SSL) protocol. This feature ensures the security of messages sent between all instances in the OracleAS File-Based Farm, and prevents unauthorized instances from joining the OracleAS File-Based Farm.

This section provides instructions for setting up SSL and certificate-based security for instances in a OracleAS File-Based Farm. The complete procedure consists of the following tasks:

1. Generating the Keystore

2. Stopping the Oracle Application Server Processes on Each Instance

3. Setting Up Keystore Information File on Each Instance in the OracleAS File-based Farm

4. Enabling SSL in the dcmCache.xml File

5. Verifying that Configuration Changes are Effected

6. Starting the Instances in the OracleAS File-based Farm

7. Adding a New Instance to a SSL-Enabled OracleAS File-based Farm

http://java.sun.com/j2se/1.4.1/docs/tooldocs/solaris/keytool.html

ORACLE_HOME/bin/emctl stop iasconsole
ORACLE_HOME/dcm/bin/opmnctl stopall

dcmctl whichfarm -v

<useSSL>
  true | false
</useSSL>

<sslConfigFile>
  sslfile
</sslConfigFile>

dcmctl getstate

ORACLE_HOME/opmn/bin/opmnctl startall
ORACLE_HOME/bin/emctl start iasconsole

2.2.12 Improving Performance in a Large OracleAS File-Based Farm

You can improve the performance of a large OracleAS File-Based Farm by tuning parameters in the in ORACLE_HOME/dcm/config/dcmCache.xml file. Table 2-5 lists the parameters and the sample values that were used to improve the performance of an OracleAS File-Based Farm with 12 Oracle Application Server Instances.

After you change ORACLE_HOME/dcm/config/dcmCache.xml, you must restart:

• The dcm daemon, by issuing these commands in ORACLE_HOME/opmn/bin:

  opmnctl stopproc ias-component=dcm-daemon
  opmnctl startproc ias-component=dcm-daemon
  
  

• The dcmctl shell, by issuing these commands in ORACLE_HOME/dcm/bin:

  dcmctl shell
  exit
  
  

• The Enterprise Manager daemon, by issuing these commands in ORACLE_HOME/bin:

  emctl stop iasconsole
  emctl start iasconsole
  
  

2.2.13 A Note About Port Assignments for the Oracle Application Server File-Based Farm: Instance Communication Across Firewalls

You should understand the implications of the default port assignments for Distributed Configuration Management communication, in the case of environments that require inter-instance communication across a firewall.

The Oracle Universal Installer assigns the ports described inTable 2-6 by default when the instance is installed.

If the ports in the range 7100 to 7179 were open on the firewall before installation, the instances in the farm will be able to communicate immediately after installation. Note that:

• If you want the port assignments to be of a different numeric range from these, then, before installation, you must assign a DCM Discovery Port using the staticports.ini file, and select the Manual option during installation. (See the Oracle Application Server Installation Guide, Chapter 4, section titled "Using Custom Port Numbers (the "Static Ports" Feature)" for more information.) The range of ports will then be assigned accordingly, as specified in Table 2-6.

• After installation of all instances, configure the firewall to close the unused ports within the assigned range on each instance.

2.2.14 Removing an Instance From the Infrastructure After Executing the leaveFarm Command

The leaveFarm command removes an Oracle Application Server Instance from an Oracle Application Server Farm, but in an OracleAS Database-based Farm, the Oracle Application Server Instance remains in the Identity Management configuration. You may choose to remove the Oracle Application Server Instance from the Identity Management configuration.

The configuration files and entries that must be changed depend on the installation type of the Oracle Application Server Instance that was removed from the OracleAS Database-based Farm. Follow the steps in the section for the applicable installation type. After the steps are performed, the Oracle Application Server Instance is a standalone Oracle Application Server Instance.

<SchemaConfigData>
  <ComponentName>DCM</ComponentName>
  <BaseName>DCM</BaseName>
  <Override>true</Override>
  <SchemaName>DCM</SchemaName>
  <DBConnect>iasdb.us.oracle.com</DBConnect>
  <Password></Password>
  <SvcPassword></SvcPassword>
</SchemaConfigData>

<SchemaConfigData>
  <ComponentName>DCM</ComponentName>
  <BaseName>DCM</BaseName>
  <Override>false</Override>
  <SchemaName/>
  <DBConnect/DBConnect>
  <Password/>
  <SvcPassword/>
</SchemaConfigData>

2.3.1 Creating an OC4J Instance

Follow these steps to create an OC4J instance:

1. Navigate to the Oracle Application Server Instance that will contain the new OC4J instance.

2. Issue this command:

   dcmctl createComponent -ct oc4j -co nameOfOC4JInstance
   
   

   In the preceding command, nameOfOC4JInstance is the identifier for the new OC4J instance. Do not use the host name, the Oracle home or IP address of the computer containing the Oracle Application Server installation as the name for the OC4J instance.

   
   

   Tip: See createComponent for syntax and rules, or issue the command dcmctl help createcomponent to view help text.

   
   

2.3.2 Deleting an OC4J Instance

You can use the dcmctl utility to remove an OC4J instance from the local application server instance, if the OC4J instance was created after installation by a user. You cannot remove any OC4J instance that was created by the Oracle Application Server installation process (such as OC4J_SECURITY). Follow these steps to remove an OC4J instance:

1. Navigate to the Oracle Application Server Instance that contains the OC4J instance you want to delete.

2. Issue this command:

   dcmctl removeComponent -co nameOfOC4JInstance
   
   

   In the preceding command, nameOfOC4JInstance is the identifier for the new OC4J instance.

   
   

   Tip: See removeComponent for syntax and rules, or issue the command dcmctl help removecomponent to view help text.

   
   

2.4.1 Log File Location and Naming

The log files are created in subdirectories of the ORACLE_HOME/dcm/logs directory. The subdirectories are named for the DCM component or function: dcmctl_logs, daemon_logs, busrule_logs, emd_logs. The log files in each directory are named as follows:

log.xml, log1.xml, log2.xml ... logN.xml

The log.xml file is the most recent log file; log1.xml is the oldest. When the log.xml file size reaches approximately the number of bytes specified by the maxFileSize parameter, the log.xml file is renamed to log1-N.xml, and a new log.xml file is created.

The maxLogSize parameter specifies the maximum number of bytes of the combined files (log.xml through logN.xml) and determines when the oldest log file is removed. The actual log size may be slightly larger or smaller than the specified maxLogSize when rotation occurs.

The Oracle Application Server Administrator's Guide, section 5.6.2.2, "ODL Log File Naming", describes the Oracle Diagnostic Logging naming convention in detail.

2.4.2 Changing Log Size Parameters

Follow these steps to change the maxFileSize or maxLogSize parameters:

1. Ensure that the DCM daemon process and DCM client processes such as dcmctl and Oracle Enterprise Manager 10g Application Server Control Console are stopped.

2. Edit the ORACLE_HOME/dcm/config/sysmgmtProperties.xml file and change the maxFileSize and maxLogSize parameter values to the sizes you want. Example 2-1 shows the parameters as they appear in the file.

   
   

   Note: An error will occur if the value of maxFileSize is larger than the value of maxLogSize.

   
   

   Example 2-1 sysmgtProperties.xml File Contents

    <Section>
     <Component name="DMSLogging">
        <Property name="maxFileSize" value="200000"/>
        <Property name="maxLogSize" value="1000000"/>
     </Component>
   </Section>
   
   

3. Use these commands to restart:

   • The dcm daemon, by issuing these commands in ORACLE_HOME/opmn/bin:

     opmnctl stopproc ias-component=dcm-daemon
     opmnctl startproc ias-component=dcm-daemon
     
     

   • The dcmctl shell, by issuing these commands in ORACLE_HOME/dcm/bin:

     dcmctl shell
     exit
     
     

   • The Enterprise Manager daemon, by issuing these commands in ORACLE_HOME/bin:

     emctl stop iasconsole
     emctl start iasconsole