2 Using the dcmctl Utility

This chapter explains how to use the dcmctl utility to create and manage the elements of a managed configuration: Oracle Application Server File-Based Farm, DCM-Managed Oracle Application Server Cluster, Oracle Application Server Instance, and component instance. Database-based repository creation and maintenance tasks are not documented here, because they are performed with tools other than the dcmctl utility—namely, the Oracle Universal Installer and the Repository Creation Assistant. See the Oracle Application Server Administrator's Guide for those instructions.

This chapter contains the following topics:

Managed Configuration Overview
Oracle Application Server Farm Creation and Maintenance Tasks
Creating and Maintaining OC4J Instances In DCM-Managed OracleAS Clusters
Best Practices for DCM-Managed OracleAS Cluster Management

2.1 Managed Configuration Overview

The managed configuration elements are related as shown in Figure 2-1. "Managed" means that a repository (file-based or database) is involved in administration. DCM-Managed OracleAS Cluster configurations can be created and kept in synch on an individual, manual basis, but that method is not discussed here.

The broadest scope of administration of a DCM-managed configuration is the Oracle Application Server Farm, in which DCM-Managed OracleAS Clusters of Oracle Application Server Instances and non-clustered, or standalone, Oracle Application Server Instances may reside. An OracleAS Farm may be created during installation, or with the dcmctl utility. Figure 2-1 depicts the elements, relationships, and cardinalities within an OracleAS Farm.

Figure 2-1 Oracle Application Server Farm, Instance, and Cluster Configuration

Description of "Figure 2-1 Oracle Application Server Farm, Instance, and Cluster Configuration "

2.2 Oracle Application Server Farm Creation and Maintenance Tasks

An OracleAS Farm is defined as a collection of OracleAS Clusters and Oracle Application Server Instances that share the same DCM metadata repository. The Oracle Application Server Farm is the scope of administration for the OracleAS Clusters and Oracle Application Server Instances that share a repository.

This section explains how to set up a OracleAS File-Based Farm and add Oracle Application Server Instances to it, create and maintain DCM-Managed OracleAS Clusters of the Oracle Application Server Instances, and perform other system administration tasks. The following topics are included:

Designating the OracleAS File-Based Farm Repository Host
Adding Instances to an OracleAS Farm
Creating a DCM-Managed OracleAS Cluster
Understanding DCM-Managed OracleAS Cluster Membership
Removing an Oracle Application Server Instance From a DCM-Managed OracleAS Cluster
Exporting and Importing Configurations From a File-based Repository
Moving an Instance From One OracleAS File-Based Farm to Another
Moving An Instance to a OracleAS Database-Based Farm
Enabling SSL For Communication Between Instances in an OracleAS File-Based Farm
Improving Performance in a Large OracleAS File-Based Farm
Removing an Instance From the Infrastructure After Executing the leaveFarm Command

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:

Navigate to the Oracle Application Server Instance that will be the repository host Oracle Application Server Instance.
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.
Issue this command:
```
dcmctl getRepositoryID
```
dcmctl returns a repository identifier in the format hostname:port.
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:

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.
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.
(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:

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.
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.4.1 How the Common Configuration is Established

The order in which the Oracle Application Server Instances are added to the DCM-Managed OracleAS Cluster is significant. The common configuration that will be replicated across the DCM-Managed OracleAS Cluster is established by the first Oracle Application Server Instance added to the cluster. The configuration of the first Oracle Application Server Instance added is inherited by all Oracle Application Server Instances that subsequently join the DCM-Managed OracleAS Cluster.

The common configuration includes all cluster-wide configuration information— namely, DCM-Managed OracleAS Cluster and Oracle Application Server Instance attributes, such as components configured. For example, if the first Oracle Application Server Instance to join the cluster has four OC4J instances, then the common configuration includes those four OC4J instances and the applications deployed on the OC4J instances. Instances that subsequently join the DCM-Managed OracleAS Cluster replicate the OC4J instances and their deployed applications. (In addition, when the Oracle Application Server Instance joins the DCM-Managed OracleAS Cluster, DCM removes any OC4J components that do not match the common configuration). Furthermore, changes to one Oracle Application Server Instance in the DCM-Managed OracleAS Cluster, such as adding new OC4J instances or removing OC4J instances, are replicated across the DCM-Managed OracleAS Cluster; the components configured are part of the replicated cluster-wide, common configuration.

When the last Oracle Application Server Instance leaves a DCM-Managed OracleAS Cluster, the DCM-Managed OracleAS Cluster becomes an empty DCM-Managed OracleAS Cluster, and the next Oracle Application Server Instance to joins the DCM-Managed OracleAS Cluster provides the new common configuration for the DCM-Managed OracleAS Cluster.

2.2.4.2 Parameters Excluded from the Common Configuration: Instance-Specfic Parameters

Some parameters only apply to a given Oracle Application Server Instance or computer, and are therefore not propagated automatically to all of the OracleAS Instances in a DCM-Managed OracleAS Cluster. Therefore, when changing any of these parameters, you must apply the changes to the appropriate Oracle Application Server Instance.

Table 2-1 OC4J Instance-specific Parameters

Parameter	Description
Oracle Application Server Cluster (OC4J) definitions	Specific to an Oracle Application Server Instance. Stateful OC4J applications require that each OracleAS Cluster (OC4J) in each OC4J instance across the DCM-Managed OracleAS Cluster have the same name.
number of processes	Specific to a computer. You may want to tune this parameter according to the computer's capabilities.
command-line options	Specific to a computer.
port numbers for RMI, JMS and AJP communication	Specific to a computer.

Table 2-2 Oracle HTTP Server Instance-Specific Parameters

Parameter	Description
ApacheVirtualHost	Specific to a computer.
Listen	Specific to a computer. This directive binds the server to specific addresses or ports.
OpmnHostPort	Specific to a computer.
Port	Specific to a computer. This directive specifies the port to which the standalone server listens.
User	Specific to a computer.
Group	Specific to a computer.
NameVirtualHost	Specific to a computer. This directive specifies the IP address on which the server receives requests for a name-based virtual host. This directive can also specify a port.
ServerName	Specific to a computer. This directive specifies the host name that the server should return when creating redirection URLs. This directive is used if `gethostbyname` does not work on the local host. You can also use it if you want the server to return a DNS alias as a host name (for example, www.abccompany.com).
PerlBlob	Specific to a computer.

Table 2-3 Oracle Process Manager and Notification Server Instance-Specific Parameters

Parameter in opmn.xml file Description

Parameter in opmn.xml file	Description
All configuration for the notification server: opmn/notification-server	Specific to a computer.
`process-manager` elements: `log-file` `process-module`	Specific to an Oracle Application Server Instance.
`ias_instance` attributes: `id` `ORACLE_HOME` `ORACLE_CONFIG_HOME`	Specific to an Oracle Application Server Instance.
The following elements and attributes of `opmn/process-manager/ias-instance /ias-component/process-type` `port.range` `start` `stop` `ping` `restart` `process-set`	Specific to an Oracle Application Server Instance. Although instance-specific, these elements and attributes have default configurations (the configurations are not propagated, but retrieved from repository).The `MissingLocalValuePolicy` flag indicates that element or attribute has a default value: `MissingLocalValuePolicy="UseRepositoryValue"`
The following `opmn/process-manager/ias-instance` attributes and elements: `module-data/category/data[id='config-file']` `ias-component/module-data/category/data[id='config-file']` `ias-component/process-type/module-data/category/data[id='config-file']` `ias-component/process-type/process-set/module-data/category/data[id='config-file']` `environment` `ias-component/environment` `ias-component/process-type/environment` `ias-component/process-type/process-set/environment` All other components whose id is not `HTTP_Server` or `OC4J` in `opmn/process-manager/ias-instance/ias-component`: `[id='dcm-daemon']` `[id='WebCache']` `[id='OID']` `[id='IASPT']` `[id='wireless']` `[id='ProcessConnect']` `[id='ReportsServer1']` `[id='Discoverer']` `[id='LogLoader']` `[id='Custom']`	Most of the `HTTP_Server` and `OC4J` parameters are cluster-wide; only those shown here are instance-specific. In general: Any data element whose id is `config-file` is instance-specific. Any environment element is instance-specific. Note: Example B-1 in Appendix B, "Troubleshooting DCM", shows a complete `opmn.xml` file that shows the hierarchy of these elements and attributes.

All configuration for the notification server:

opmn/notification-server

Specific to a computer.

process-manager elements:

log-file

process-module

Specific to an Oracle Application Server Instance.

ias_instance attributes:

id

ORACLE_HOME

ORACLE_CONFIG_HOME

Specific to an Oracle Application Server Instance.

The following elements and attributes of opmn/process-manager/ias-instance /ias-component/process-type

port.range

start

stop

ping

restart

process-set

Specific to an Oracle Application Server Instance. Although instance-specific, these elements and attributes have default configurations (the configurations are not propagated, but retrieved from repository).The MissingLocalValuePolicy flag indicates that element or attribute has a default value:

MissingLocalValuePolicy="UseRepositoryValue"

The following opmn/process-manager/ias-instance attributes and elements:

module-data/category/data[id='config-file']

ias-component/module-data/category/data[id='config-file']

ias-component/process-type/module-data/category/data[id='config-file']

ias-component/process-type/process-set/module-data/category/data[id='config-file']

environment

ias-component/environment

ias-component/process-type/environment

ias-component/process-type/process-set/environment

All other components whose id is not HTTP_Server or OC4J in opmn/process-manager/ias-instance/ias-component:

[id='dcm-daemon']

[id='WebCache']

[id='OID']

[id='IASPT']

[id='wireless']

[id='ProcessConnect']

[id='ReportsServer1']

[id='Discoverer']

[id='LogLoader']

[id='Custom']

Most of the HTTP_Server and OC4J parameters are cluster-wide; only those shown here are instance-specific.

In general:

Any data element whose id is config-file is instance-specific.
Any environment element is instance-specific.

Note: Example B-1 in Appendix B, "Troubleshooting DCM", shows a complete opmn.xml file that shows the hierarchy of these elements and attributes.

2.2.4.3 Rules and Guidelines for Adding Instances to DCM-Managed OracleAS Clusters

Instances that are to be added to DCM-Managed OracleAS Clusters are subject to the following restrictions:

Instances in an DCM-Managed OracleAS Cluster must be of the same installation type and version and reside on a like operating system (Solaris, Linux, and HP-UX are like operating systems).
Instances in an DCM-Managed OracleAS Cluster must contain only Oracle HTTP Server, OC4J, OPMN and OracleAS JAAS Provider (JAZN) components.
Configuration changes can be made in any Oracle Application Server Instance in the DCM-Managed OracleAS Cluster, and will be propagated across the DCM-Managed OracleAS Cluster from there. However, it is probably a good idea to designate one Oracle Application Server Instance as the origin of configuration changes.

2.2.4.4 Naming Restrictions For Instances and Applications

Do not use the host name of the computer that contains the Oracle Application Server installation when naming applications, OC4J instances, Oracle Application Server Instances, or J2EE applications. In a clustered environment, in particular, do not use the host name, Oracle home, or the IP address of any Oracle Application Server installation in the DCM-Managed OracleAS Cluster.

For example, if your computer has the host name of abc.com, you should not create a new OC4J instance or J2EE application that consists of, or contains, the string abc.com. This rule also applies to the Oracle home directory path or the IP address of the computer.

The reason for this restriction has to do with the clustering, archival, and cloning features of DCM. When archiving or capturing configuration parameters, DCM scans all configuration files for occurrences of the host name, Oracle home and IP address. When it finds occurrences of these values, it replaces the values with symbolic macros and stores them in the DCM Repository.

When DCM applies these configurations to other installations, the occurrences of host name, Oracle home and IP address are replaced with the values for that installation to which the configuration is being applied. Consequently, if OC4J instance names or J2EE application names contain host names, Oracle home names or IP addresses, they are inappropriately substituted if a configuration is applied to other installations.

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:

(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.
Navigate to the Oracle Application Server Instance that you want to join to the DCM-Managed OracleAS Cluster.
(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.

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

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

(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.
Navigate to the Oracle Application Server Instance that you want to remove from the DCM-Managed OracleAS Cluster.

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:

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
```
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.
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:

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.
Issue this command:
```
dcmctl leaveFarm
```
The Oracle Application Server Instance is now in a standalone state.
Use the createArchive command to create a baseline archive of the Oracle Application Server Instance. For example:
```
dcmctl createArchive -arch myArchive
```

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.

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:

Determine whether the instance is still part of an OracleAS File-Based Farm using the following command:
```
dcmctl whichFarm
```
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 
```
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.

Note:

When an Oracle Application Server instance leaves a OracleAS Farm, it becomes a standalone instance. The standalone instance has its DCM-managed configuration metadata saved on the file system of the standalone instance. Archives for the instance are deleted from the previous repository host. However, connections to the Infrastructure database that may exist for other components, including Oracle Application Server Single Sign-On, JAAS, and Oracle Internet Directory, are not removed.

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

Generating the Keystore
Stopping the Oracle Application Server Processes on Each Instance
Setting Up Keystore Information File on Each Instance in the OracleAS File-based Farm
Enabling SSL in the dcmCache.xml File
Verifying that Configuration Changes are Effected
Starting the Instances in the OracleAS File-based Farm
Adding a New Instance to a SSL-Enabled OracleAS File-based Farm

2.2.10.1 Generating the Keystore

Use the JDK keytool command to generate a certificate and create the keystore, as documented in:


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

If you have already generated the key pair and obtained the certificate for OC4J, then you can use the same keystore you previously obtained.

To use SSL certificate-based security, a Java keystore must be created on each instance in the OracleAS File-Based Farm. This keystore may be the same as that used by other Java applications, or it can be unique for OracleAS File-Based Farm configuration. Note the path to each keystore location for each instance in the OracleAS File-Based Farm.

2.2.10.2 Stopping the Oracle Application Server Processes on Each Instance

In each instance of the OracleAS File-Based Farm, issue the following commands to stop Oracle Application Server processes:


ORACLE_HOME/bin/emctl stop iasconsole

ORACLE_HOME/dcm/bin/opmnctl stopall

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

After obtaining the keystore and certificate information, you must create the file that holds the keystore information on each Oracle Application Server instance in the OracleAS File-Based Farm.

Important:

The keystore information file must be set up for the repository host instance OracleAS File-Based Farm before it is set up in any other instance. To find the repository host and host instance, execute the following:


dcmctl whichfarm -v

To set up the keystore information file, perform these steps, beginning with the repository host instance OracleAS File-Based Farm. The steps can be performed on the remaining instances in any order.

Copy the keystore file that you generated in the first step, "Generating the Keystore," to a location in the local host.
Use the configRepositorySSL command as follows:
```
dcmctl configRepositorySSL -keystore path_to_keystore -storepass password
```
The generated file, .ssl.conf, is stored in the ORACLE_HOME/dcm/config directory.

2.2.10.4 Enabling SSL in the dcmCache.xml File

To enable or disable the use of SSL, modify the <useSSL> attribute in the ORACLE_HOME/dcm/config/dcmCache.xml file. Table 2-4 lists the configuration parameters for enabling SSL.

Optionally, you can specify the location of the file that was generated using configRepositorySSL by modifying the value of the <sslConfigFile> element. If you modify this value, you need to copy the .ssl.conf file that configRepositorySSL generated to the new file that you specify using the <sslConfigFile> element.

Table 2-4 Elements for Enabling SSL in a Farm Using a File-Based Repository

Element Description

Element	Description
<useSSL> true \| false </useSSL>	Set to `true` to use SSL or to `false` to disable the use of SSL for DCM communications. The default value is `false`. Valid values: `true`, `false`
<sslConfigFile> sslfile </sslConfigFile>	Specifies the name, `sslfile` , of the SSL configuration file. The default value is `.ssl.conf.` For most installations, there should be no need to change the default value for this element.


<useSSL>

  true | false

</useSSL>

Set to true to use SSL or to false to disable the use of SSL for DCM communications.

The default value is false.

Valid values: true, false


<sslConfigFile>

  sslfile

</sslConfigFile>

Specifies the name, sslfile , of the SSL configuration file.

The default value is .ssl.conf.

For most installations, there should be no need to change the default value for this element.

2.2.10.5 Verifying that Configuration Changes are Effected

Ensure that the configuration changes are effected by executing the following command on each instance in the OracleAS File-Based Farm, beginning with the repository host instance:


dcmctl getstate

This shows the synchronization state of the local instance in the OracleAS File-Based Farm.

2.2.10.6 Starting the Instances in the OracleAS File-based Farm

After the security configuration is consistent across all the instances in the OracleAS File-Based Farm, restart each instance, beginning with the repository host instance, using the following command:


ORACLE_HOME/opmn/bin/opmnctl startall

ORACLE_HOME/bin/emctl start iasconsole

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

You can add a standalone instance to a OracleAS File-Based Farm that is using SSL. On the standalone machine:

Copy the keystore file that you generated in the first step, "Generating the Keystore," to a location on the local computer.
Use the configRepositorySSL as follows on each instance to create the keystore information file:
```
dcmctl configRepositorySSL -keystore path_to_keystore -storepass password
```
The generated file, .ssl.conf, is stored in ORACLE_HOME/dcm/config.
Follow the instructions in Section 2.2.2, "Adding Instances to an OracleAS Farm" to join the instance to the farm.

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

Table 2-5 Sample Values for Tuning a 12-Instance OracleAS File-Based Farm

Parameter	Default Value	Adjusted Value	Description
`<clean-interval>`	180	540	As the size of the farm increases, there are more cached objects. The process of cleaning the cache entails removing references to invalidated objects at a given interval. The more cached (and invalidated) objects, the longer it takes to clean the cache. With an increased number of objects, the cleanup interval should be set higher to decrease the frequency of cache cleanup, which is CPU-intensive.
`<max-objects>`	2000	6000	If the log file contains `CacheFullException` or `RegionFullException` errors, increase the value of `max-objects`.
`<disksize>`	256	768	The `disksize` parameter should be set to a value larger than the sizes of the J2EE deployment EAR files.

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

Table 2-6 Oracle Universal Installer Default Port Assignments

Quantity Purpose/Description

Quantity	Purpose/Description
1	DCM Discovery Port. The first instance installed on a computer is assigned port 7100 for this; the second instance installed on a computer is assigned 7101, and so on. This is defined in the `ORACLE_HOME/dcm/config/dcmCache.xml` file, in the `discoverer` element (for example, `<discoverer discovery-port ="7100" original-"true" xmlns=""/>`
50	Range of ports for inter-instance communication: 7120 to 7179. These are defined in the `ORACLE_HOME/dcm/config/dcmCache.xml` file, in the port element (for example, `<port lower="7120" upper="7179">`.) After installation, you will probably want to limit the number of ports open on the firewall. The actual port needs for inter-instance communication are: 1 for the Oracle Enterprise Manager 10g Application Server Control Console on each instance 1 for the DCM daemon on each instance 1 for each dcmctl client operating on each instance

DCM Discovery Port. The first instance installed on a computer is assigned port 7100 for this; the second instance installed on a computer is assigned 7101, and so on. This is defined in the ORACLE_HOME/dcm/config/dcmCache.xml file, in the discoverer element (for example, <discoverer discovery-port ="7100" original-"true" xmlns=""/>

Range of ports for inter-instance communication: 7120 to 7179. These are defined in the ORACLE_HOME/dcm/config/dcmCache.xml file, in the port element (for example, <port lower="7120" upper="7179">.)

After installation, you will probably want to limit the number of ports open on the firewall. The actual port needs for inter-instance communication are:

1 for the Oracle Enterprise Manager 10g Application Server Control Console on each instance
1 for the DCM daemon on each instance
1 for each dcmctl client operating on each instance

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

2.2.13.1 J2EE and Web Cache Instance Using Identity Management (Oracle Internet Directory)

Follow these steps to remove the Oracle Application Server Instance from the Identity Management configuration:

Use the oidadmin tool to remove the entries created during installation to register the Oracle Application Server Instance with Oracle Internet Directory.

One of the entries to be removed is shown in bold italic:
```
"orclApplciationCommonName=instance name,cn=IAS Instances, cn=IAS, cn=Products, cn=OracleContext
```
The other entry to remove is the uniquemember attribute of the following entry:
```
"cn=Associated Mid-tiers, OrclReferenceName=repository name, cm=IAS Infrastructure Databases,cn=Products,cn=OracleContext
```
Edit the ORACLE_HOME/config/ias.properties file to remove the Oracle Internet Directory host, port, dbname, and instance password. Change the InfrastructureUse flag to false.

Modify the ORACLE_HOME/j2ee/home/config/jazn.xml file to replace the following entry:


orclApplicationCommonName=jaznadmin1,cn=JAZNContext,cn=products,cn=OracleContext

with this entry:


<?xml version="1.0" encoding="UTF-8" standalone='yes'?>

<!DOCTYPE jazn PUBLIC "JAZN Config" "http://xmlns.oracle.com/ias/dtds/jazn-9_04.dtd">

<jazn provider="XML" location="./jazn-data.xml">

</jazn>

Remove the corresponding Oracle Internet Directory entry also.

Modify the LDAP configuration as follows:
1. Remove the ORACLE_HOME/network/admin/ldap.ora file.
2. Edit the ORACLE_HOME/network/admin/sqlnet.ora file to remove the LDAP naming from the list of namings.

2.2.13.2 J2EE and Web Cache Installation with Database-based Repository

To remove the Oracle Application Server Instance from the Identity Management configuration of a J2EE and Web Cache Installation:

Edit the ORACLE_HOME/config/iasschema.xml file to change the DCM repository association entry as follows:

from this entry:


<SchemaConfigData>

  <ComponentName>DCM</ComponentName>

  <BaseName>DCM</BaseName>

  <Override>true</Override>

  <SchemaName>DCM</SchemaName>

  <DBConnect>iasdb.us.oracle.com</DBConnect>

  <Password></Password>

  <SvcPassword></SvcPassword>

</SchemaConfigData>

to the following entry:


<SchemaConfigData>

  <ComponentName>DCM</ComponentName>

  <BaseName>DCM</BaseName>

  <Override>false</Override>

  <SchemaName/>

  <DBConnect/DBConnect>

  <Password/>

  <SvcPassword/>

</SchemaConfigData>

2.2.13.3 J2EE and Web Cache Installation Using Identity Management (Oracle Internet Directory) with Database-based Repository

Follow these steps to remove the Oracle Application Server Instance from the Identity Management configuration:

Use the oidadmin tool to remove the entries created during installation to register the Oracle Application Server with Oracle Internet Directory.

One of the entries to be removed is shown in bold italic:
```
"orclApplciationCommonName=instance name,cn=IAS Instances, cn=IAS, cn=Products, cn=OracleContext
```
The other entry is shown in bold italic (in the uniquename attribute of the entry):
```
"cn=Associated Mid-tiers, OrclReferenceName=repository name, cm=IAS Infrastructure Databases,cn=Products,cn=OracleContext
```
Edit the ORACLE_HOME/config/ias.properties file to remove the Oracle Internet Directory host, port, dbname, and instance password. Change the InfrastructureUse flag to false.

Edit the ORACLE_HOME/config/iasschema.xml file to change the DCM repository association entry as follows:

from this entry:


<SchemaConfigData>

  <ComponentName>DCM</ComponentName>

  <BaseName>DCM</BaseName>

  <Override>true</Override>

  <SchemaName>DCM</SchemaName>

  <DBConnect>iasdb.us.oracle.com</DBConnect>

  <Password></Password>

  <SvcPassword></SvcPassword>

</SchemaConfigData>

to the following entry:


<SchemaConfigData>

  <ComponentName>DCM</ComponentName>

  <BaseName>DCM</BaseName>

  <Override>false</Override>

  <SchemaName/>

  <DBConnect/DBConnect>

  <Password/>

  <SvcPassword/>

</SchemaConfigData>

Change the OracleAS JAAS Provider entries, editing the ORACLE_HOME/j2ee/home/config/jazn.xml file to replace the following entry:


orclApplicationCommonName=jaznadmin1,cn=JAZNContext,cn=products,cn=OracleContext

with this entry:


<?xml version="1.0" encoding="UTF-8" standalone='yes'?>

<!DOCTYPE jazn PUBLIC "JAZN Config" "http://xmlns.oracle.com/ias/dtds/

jazn-9_04.dtd">

<jazn provider="XML" location="./jazn-data.xml">

</jazn>

Remove the corresponding Oracle Internet Directory entry also.

Modify the LDAP configuration as follows:
1. Remove the ORACLE_HOME/network/admin/ldap.ora file.
2. Edit the ORACLE_HOME/network/admin/sqlnet.ora file to remove the LDAP naming from the list of namings.

2.3 Creating and Maintaining OC4J Instances In DCM-Managed OracleAS Clusters

The dcmctl utility includes commands for creating and deleting OC4J instances in OracleAS Cluster. It also contains other commands for OC4J application deployment (validateEarFile, deployApplication and redeployApplication), but it is generally recommended that in production environments, you use the Oracle Enterprise Manager 10g Application Server Control Console user interface for application deployment. The Application Server Control Console provides configuration change, monitoring, and status functionality as part of the deployment process. For example, the Application Server Control Console will notify you with a message that certain configuration changes will only take effect after you restart the OC4J instance.

2.3.1 Creating an OC4J Instance

Follow these steps to create an OC4J instance:

Navigate to the Oracle Application Server Instance that will contain the new OC4J instance.
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:

Navigate to the Oracle Application Server Instance that contains the OC4J instance you want to delete.
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 Managing DCM Log Files

DCM creates log files to track activity and errors that occurred in the operation of the dcmctl utility, the DCM daemon, the Enterprise Manager daemon, and the business rule function. You can specify the size of the individual log files and the overall size of the logs by setting the maxFileSize and maxLogSize parameters.

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.

Note:

The actual number of bytes in a log file is not always exactly equal to the maxFileSize value. Log file sizes may be slightly more or less when rotation occurs. Individual log entries are not split across files.

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:

Ensure that the DCM daemon process and DCM client processes such as dcmctl and Oracle Enterprise Manager 10g Application Server Control Console are stopped.
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>
```
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
```

2.5 Best Practices for DCM-Managed OracleAS Cluster Management

Understanding and adhering to the recommendations outlined will help you maximize DCM's capabilities and safeguard your system configuration. Note the following OracleAS Cluster management practices:

Oracle Application Server Instances grouped in a DCM-Managed OracleAS Cluster can be managed using Oracle Enterprise Manager 10g Application Server Control Console or dcmctl from a single point of administration on any Oracle Application Server Instance in the DCM-Managed OracleAS Cluster. It is advisable to use one Oracle Application Server Instance as the administrative locus for the entire DCM-Managed OracleAS Cluster.
When changing instance-specific configuration such as port numbers, host names or virtual hosts, ensure that no other concurrent administrative changes are made in the DCM-Managed OracleAS Cluster. This should help prevent application of conflicting changes to configuration (which could result in an unusable configuration).
Concurrent administration within an DCM-Managed OracleAS Cluster is strongly discouraged. If multiple administrative operations are issued at the same time in an DCM-Managed OracleAS Cluster, errors may occur, and the associated error messages may be confusing. For example, a concurrent attempt to change the configuration of an Oracle Application Server Instance that is being deleted really does not make sense. It is recommended that one Oracle Application Server Instance be used as the administrative locus for the entire DCM-Managed OracleAS Cluster. This will ensure that operations are executed in logical order and are properly serialized.
Archiving (automatically or manually) before any administrative operation is recommended. With auto-archiving, you can have dcmctl automatically detect that the Oracle Application Server Instance is associated with an DCM-Managed OracleAS Cluster and create auto-archives of the DCM-Managed OracleAS Cluster configuration before administrative operations are performed. Table 3-1, "Automatic Archive Operations" lists the operations that trigger automatic archiving.