|
Distributed Configuration Management Reference Guide
10g (9.0.4) Part No. B12052-02 |
|
|
|
|
Distributed Configuration Management Reference Guide
10g (9.0.4) Part No. B12052-02 |
|
|
|
|
This chapter describes the characteristics of the dcmctl utility, and provides syntax and reference information for each of its commands. It is divided into these sections:
All dcmctl commands have this syntax:
ORACLE_HOME/dcm/bin/dcmctl command [options]
Before you use the dcmctl utility, note the following:
Do not run updateConfig concurrently with any other dcmctl commands or Oracle Enterprise Manager Application Server Control (Application Server Control) configuration operations from multiple Oracle Application Server instances in a farm or cluster (see updateConfig for details).
Oracle recommends that Oracle Application Server Clusters using a file based repository contain four (4) or less than four instances.
Oracle Application Server supports heterogeneous instances as part of the same farm. For example, an instance running on Solaris Operating System, an instance running on a Linux system, and an instance running on an HP-UX system can reside in the same farm. Oracle Application Server instances that you want to be part of a cluster must be installed on identical operating systems.
You must log in to the operating system with the user name that was used to install Oracle Application Server in order to use dcmctl.
When using a file based farm, you may need to refresh or restart Application Server Control after issuing the following dcmctl commands:
Ensure that you issue dcmctl commands in the Oracle home of the instance you wish to manage. dcmctl commands operate on the instance in which the dcmctl executable is located. The value of the ORACLE_HOME environment variable does not determine the instance on which dcmctl operates.
All dcmctl commands and options are case-insensitive.
Instance, component, and cluster names are case-sensitive.
If you use dcmctl set commands while multiple DCM clients are active, the clients will not act upon the changed values until they are restarted. You must restart the dcmctl and Enterprise Manager clients after using dcmctl set when multiple DCM clients are active.
As shown in the syntax description, dcmctl commands may be used with options. An option can be one of following types:
Global: These can be used with all commands (see Table 2-1).
Scope: These options indicate the scope of a command. The scope can be an application, application server cluster, component, type of component, or application server instance (see Table 2-2).
Command-specific: These options apply only to certain commands. Each command description in the following pages includes information about any options the command provides (see Table 2-3).
Table 2-1 dcmctl Global Options
| Option | Description |
|---|---|
–d
|
Prints the stack trace if an exception occurs when the command is executed. By default, dcmctl executes with this option on. You can change this behavior with the set command.
|
–l directory
|
Saves the DCM client error log file log.xml in the named directory.
The directory can be a full path name or a path name relative to the current directory. Default value: |
–v
|
Prints the long (verbose) version of state and error messages. Setting verbose to off is recommended when using scripts or using the dcmctl shell, since the brief messages are easier to parse.
By default, |
Table 2-2 dcmctl Scope Options
| Option | Description |
|---|---|
–a app_name
|
Applies the command to the named application app_name, or designates the name of an application during initial deployment. |
–admin
|
Applies the command to the DCM daemon. For example:
start –admin stop –admin |
–cl cluster_name
|
Applies the command to the named application server cluster, cluster_name, or designates the name of a cluster during creation. |
–co comp_name
|
Applies the command to the named component, comp_name, or designates the name of a component during creation |
–ct type
|
Applies the command to components of the named component type.
Component type can be of type: |
–i inst_name
|
Applies the command to the named instance, inst_name. |
–r repository_info
|
Applies the command to the repository name or port specified with repository_info. |
Table 2-3 dcmctl Command-Specific Options
| Option | Description |
|---|---|
–arch
|
Specifies an archive name. Use with archive commands.
For example:
|
–c
|
Creates a comment. Use with archive commands and ’import’ and ’export’ configuration management commands. |
–force
|
Performs an operation without performing checks or issuing a confirmation. This option should be used judiciously, since in some cases, it can result in lengthy processing, and in others, it can perform a destructive action that might be unrecoverable. |
–sort
|
Sorts listed results by name. Use with all ’list’ commands. For example:
You can make sorting persistent with the set command. |
–src
|
Indicates the source of the archive. Use with archive commands.
For example, to apply an archive to the current instance:
|
The following rules apply to command-specific options. If you do not use options, by default, the command applies to the local instance.
If –cl is supplied, the command applies to all instances in the cluster.
If –ct is supplied with –cl or –i, then the command applies to the component type within the cluster, or the component type within the instance within the cluster.
If –co is supplied with –ct, –cl, –i then the command applies to the component within the cluster, or the component type within the instance within the cluster.
If –a is supplied with any of the preceding options, that particular application within the component, component type, instance, or cluster is used.
You can execute dcmctl commands from within the dcmctl shell. Within the shell, it is not necessary to preface commands with dcmctl (see the following sample session). To start the dcmctl shell, type:
dcmctl shell
Following is a sample shell session, in which the shell is started, commands are executed, and the shell is stopped.
dcmctl shell
dcmctl> createcluster -cl testcluster
dcmctl> joincluster -cl testcluster
dcmctl> createcomponent -ct oc4j -co component1
dcmctl> start -co component1
dcmctl> deployapplication -f /stage/apps/app1.ear -a app1 -co component1
dcmctl> start -cl testcluster
dcmctl> getstate
dcmctl> exit
This section describes types of dcmctl commands and their uses.
Configuration Management: Use these commands to create and associate configuration elements (clusters, instances, components)
Table 2-4 Configuration Management Commands
dcmctl Shell: Use these commands with the dcmctl shell.
Archive: Use these commands to create archives of configurations.
Table 2-6 Archive Commands
| Command |
|
|
|
|---|---|---|---|
| applyArchiveTo
|
createArchive
|
exportArchive
|
importArchive
|
| listArchives
|
removeArchive
|
|
|
Application: Use these commands to deploy and manage applications.
Table 2-7 Application Commands
| Command |
|
|
|
|---|---|---|---|
| deployApplication
|
listApplications
|
redeployApplication
|
undeployApplication
|
| validateEarFile
|
|
|
|
dcmctl Properties: Use these commands to administer the dcmctl utility.
Table 2-8 dcmctl Properties Commands
| Command |
|
|
|
|---|---|---|---|
| getError
|
getReturnStatus
|
getState
|
help
|
| listComponentTypes
|
set
|
|
|
Non-managed Clusters: Use these commands to work with non-managed clusters.
Process Management: These commands allow you to start and stop processes within clusters and instances. These commands are deprecated in Oracle Application Server 10g. Use opmnctl to manage processes in Oracle Application Server 10g.
This section lists all commands alphabetically. The command type, syntax, and description is included for each command.
|
Note: All commands are case-insensitive. Capital letters are used in this guide only to increase readability. Many examples show the commands in all lower case. |
Repeats the previous command.
Shell
!!
Use this command in the dcmctl shell to repeat the previous command.
!!
Creates a non-managed Oracle Application Server cluster.
Configuration Management
addOPMNLink hostname:port[, hostname:port...]
You can use this command to create a non-managed Oracle Application Server cluster that includes the local application server instance and the instances specified as arguments.
You must run this command in the Oracle home of each instance you would like to put into the cluster, using the rest of the instances as arguments.
All instances must be J2EE and Web Cache instances and the instances must not be part of a farm (associated with a repository); otherwise, the command will fail.
If you would like to change the ONS remote port for an instance in a cluster, you must remove the instance from the cluster using removeOPMNLink, change the remote port, and add it to the cluster again using addOPMNLink. You must repeat the command in every Oracle home.
If you create a cluster and then want to add another instance to the cluster, you must run the command again in all Oracle homes (essentially creating a new cluster with the added instance).
HOST1_ORACLE_HOME/dcm/bin/dcmctl getopmnport host1:6200 HOST2_ORACLE_HOME/dcm/bin/dcmctl getopmnport host2:6200 HOST3_ORACLE_HOME/dcm/bin/dcmctl getopmnport host3:6200 HOST1_ORACLE_HOME/dcm/bin/dcmctl addopmnlink host2:6200,host3:6200 HOST2_ORACLE_HOME/dcm/bin/dcmctl addopmnlink host1:6200,host3:6200 HOST3_ORACLE_HOME/dcm/bin/dcmctl addopmnlink host1:6200,host2:6200
Applies an archived configuration to an instance or cluster.
Archive
applyArchiveTo –src archiveName [-cl clusterName | -i instanceName]
When configuration information is stored in the DCM repository, it is recognized as one of the following two types of information:
Information which is generic to any instance (cluster-wide information).
Information that is specific to a particular instance (instance specific information). Instance specific information is defined by the various managed components, including: Oracle HTTP Server, OC4J, OPMN, and JAZN and may include such things as host name or port values
When an archive is applied to the same instance that it was created for, both the cluster-wide information and instance specific information is restored to the instance. When the archive is applied to a cluster or to a different instance than the one it was created for, only the cluster-wide information is restored, the existing instance specific information is not changed.
dcmctl applyarchiveto –src archive1 –i instance1
Applies the configuration of a cluster to an instance or cluster.
Configuration Management
applyClusterTo -src clusterName [-cl clusterName | -i instanceName]
The configuration of the named cluster (as specified by the -src option) is applied to the named instance or cluster. The named source cluster is not affected.
dcmctl applyclusterto –src cluster1 –i instance1
Applies the configuration of the named instance to another instance or cluster.
Configuration Management
applyInstanceTo –src instanceName [-cl clusterName | -i instanceName]
The configuration of the named instance is applied to the named instance or cluster. If no instance or cluster is specified, then the configuration of the named instance is applied to the current instance. The named source instance is not affected. The command will fail if the current instance and the named instance are the same (you cannot apply the configuration of an instance to itself).
dcmctl applyinstanceto –src instance1
Specifies the location and password of the keystore used to secure the farm.
For more information on using this command, see the Oracle Application Server 10g High Availability Guide.
Configuration Management
configRepositorySSL -keystore pathToKeystore -storepass password
Specifies the location and password of the keystore to use to provide certificate-based security for the farm. This command applies to a distributed File based repository only. Configuring the keystore does not automatically enable security.
To use certificate-based security, each instance in the farm must have a Java keystore. It be shared by other Java applications, or it can be a separate keystore specifically for repository administration. After the keystore is set up, use the configRepositorySSL command in each instance in the farm to tell the system which keystore to use.
To enable this security feature, edit the file ORACLE_HOME/dcm/config/dcmCache.xml, in each instance in the farm to set the value of <useSSL> true </useSSL>. You must restart all DCM daemons and clients in the farm for the security change to take effect. The security setting must be consistent across all instances in the farm, or they will not communicate properly.
configRepositorySSL -keystore /OracleHome/security/files -storepass welcome
Creates an archive of the named cluster or instance.
Archive
createArchive -arch archiveName [-cl myCluster | -i myInstance] [-comment "myComments"]
An archive is created of the named instance or cluster. If you don’t specify a cluster or instance, the current instance is archived.
The difference is as follows.Notes for using createArchive with Oracle Application Server clusters:
Cluster-wide archives, created with createArchive -cl, contain only cluster-specific information and do not contain any information specific to the instance the archive is created on.
Instance-specific archives, created with createArchive -i or with no options, contain cluster-specific information, plus any DCM managed information pertaining to the instance where createArchive runs.
createArchive -arch myInstance -comment "my favorite configuration"
Creates a managed Oracle Application Server cluster.
|
Note: Oracle recommends that Oracle Application Server Clusters using a file based repository contain four (4) or less than four instances. |
Configuration Management
createCluster -cl cluster_name
A managed cluster is created.
Notes for using createCluster:
When creating a cluster with the createCluster command, use only the following characters in the cluster_name argument supplied with the -cl option:
abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-
You must issue this command in the Oracle home of an instance that belongs to a farm (that is, is associated with a metadata repository). The cluster will be created in that farm.
The cluster has no members when created. You can add members using joinCluster.
You can create an unlimited number of clusters.
dcmctl createCluster -cl cluster1
Configuration Management
createComponent -ct oc4j -co component_name
Creates a new OC4J instance belonging to the local application server instance. You cannot specify another instance with the –i option; the command operates locally. Note that OC4J is currently the only component type allowed for this command.
|
Note: When creating a component with thecreateComponent command, use only the following characters in the component_name argument supplied with the –co option:
abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_- |
dcmctl createComponent -ct oc4j -co OC4J_myapps
Application
deployApplication -f file -a app_name [-co comp_name] [-enableIIOP] [-rc rootcontext] [-pa parent_name]
where
file is the name of the WAR or EAR file to deploy
app_name is the name of the application specified by the user in original deployment
comp_name is the name of the OC4J instance to which the application will be deployed. The default is the home instance.
–rc rootcontext is the base path used in the URL to access the web module (for example, http://hostname:port/context root). Applies to deployment of WAR files only.
–pa parent_name is the parent application name. The parent application contains common classes used by child applications.
The J2EE application is deployed to the local application server instance.
To deploy an application to the home OC4J instance:
dcmctl deployApplication -f app1.ear -a app1
To deploy an application to the OC4J_my_apps instance:
dcmctl deployApplication -f app1.ear -a app1 -co OC4J_myapps
To deploy a WAR file to the home OC4J instance:
dcmctl deployApplication -f app2.war -a app1 -rc /myiAS/myWebapps
Removes an instance from the DCM repository.
Configuration Management
destroyInstance -i instance_name
Removes all information related to the specified application server instance from the DCM repository. The need for this command arises when an instance is removed using operating system commands on files or directories, and the repository information about the instance remains. This may cause problems in subsequent installation attempts. The destroyInstance command clears the repository of all vestiges of an instance that was removed precipitously.
If the command is executed in the instance being destroyed, the dcm.conf file, targets.xml file, and the repository directory will be cleaned up. If it is executed remotely, you should check to ensure that the instance-related information has been removed, and, if not, remove it manually.
dcmctl destroyInstance -i instance1
Displays the specified string to standard output.
Shell
echo
Used in a dcmctl command script to display a specified string to standard output.
echo "this is a comment"
Shell
exit
Exits a dcmctl shell client. This command is only applicable to the shell; it does not affect the dcmctl daemon.
exit
Exports the named archive from the repository to a JAR file.
Archive
exportArchive -arch archiveName -f myFile [-comment myComments]
See "Exporting and Importing Archives".
dcmctl exportArchive –arch archive1 –f /exports/testConfig -comment "this is an export of archive1"
Copies the named file-based repository to the specified location.
Configuration Management
exportRepository -f myFile [-force]
Copies the File based repository information to the location specified. Use the –force option to overwrite an existing file. If you do not use the –force option and the named file exists, an exception is thrown.
Note for using exportRepository:
Usually if you use the exportRepository command, you also use importRepository on another instance. Before running importRepository , stop all DCM daemons in the instances that are part of the farm where you run importRepository. Use the following command at each instance in the farm to stop DCM daemons:
dcmctl shell dcmctl> shutdown
This example assumes that you have two instances: instance1 and instance2. To relocate the file-based repository host from instance1 to instance2, perform the following steps:
On instance1, the original file-based repository host,
dcmctl shell dcmctl> exportrepository -f /export/repository_save_file dcmctl> shutdown
If there are more than two instances, issue the shutdown command on all the other instances.
On instance2, shutdown and import the saved repository,
dcmctl shell dcmctl> shutdown dcmctl> importrepository -f /export/repository_save_file
On instance1,
dcmctl> repositoryrelocated
After the repositoryRelocated command completes, sequentially, start the dcm daemons, as follows:
On instance1,
dcmctl> start -admin
When this command completes, on instance2 issue the command,
dcmctl> start -admin
If there are more than two instances, issue the following command sequentially on all of the other instances:
dcmctl> start -admin
Returns the type of the component in the local instance or specified instance.
Configuration Management
getComponentType [-i instance_name] -co component_name
Returns the type of the component to standard output. By default, it returns the type of the component in the local application server instance. You can use the –i option to specify a different instance.
To obtain the type of the home component in the local application server instance:
dcmctl getComponentType -co home
OC4J
To obtain the type of the OC4J_SECURITY component in instance1:
dcmctl getComponentType -co OC4J_SECURITY -i instance1
OC4J
Displays descriptions of errors.
dcmctl Properties
getError [error_number | error_name]
Displays error descriptions. If you issue this command with no arguments, it displays the error message from the most recent DCM error that occurred. If the debug option is set to on, the stack trace is printed, if there was one. If you provide an error number or error name, it displays the message for that error.
To view the description of the error that most recently occurred:
dcmctl getError
You can use the following commands to print the messages for ADMN-906025:
dcmctl getError 906025 dcmctl getError ADMN-906025
Returns the hostname and ONS remote port.
Non-managed Cluster
getOPMNPort
This command returns the hostname and the ONS remote port for the local application server instance. It retrieves this information from the ons.conf file.
dcmctl getopmnport
myhost.example.com:6200
Returns the repository ID of a File based repository.
Configuration Management
getRepositoryId
Returns the File based repository identifier of the farm to which the instance belongs. If the instance is a standalone instance, this command returns the repository identifier for the instance. If the standalone instance is to be used to establish a new distributed File based repository, then use the returned repository identifier to initialize the repository host with joinFarm and the –r option.
See the Oracle Application Server 10g High Availability Guide for a complete description of using getRepositoryId and joinFarm -r.
dcmctl getrepositoryid
Returns the status of the last dcmctl command.
dcmctl Properties
getReturnStatus
This command displays the status of the last dcmctl command the performed an asynchronous operation (as opposed to a command that returned information). This command is intended to be used to get the status of a previous command that timed out. You can issue the getReturnStatus command repeatedly until it reports that the previous command has finished.
For synchronous operations, use the getError command to retrieve more information on the last failed command.
In this example, the start command times out and the getReturnStatus command is used to check for status:
dcmctl getReturnStatus
ADMN-906005
The specified command, "start", is being executed asynchronously. The maximum wait time of, 120 seconds, has been reached. This operation will continue to execute to completion. Use the "getReturnStatus" command to determine if/when the operation completes successfully.
Returns the state of the components in the indicated scope. The getState command only displays the state of the following components: OC4J, Oracle HTTP Server, and JAZN.
Configuration Management
getState [-i instance_name] [-cl cluster_name] [-co component_name]
Without any arguments, this command returns the state of all components in the local application server instance. The state includes the following indicators:
In Sync Status — indicates whether the component’s configuration is synchronized with the configuration in the DCM repository
You can use arguments with the command to narrow the scope of the command by instance, cluster, or component.
To get the state of the local application server instance:
dcmctl getState
To get the state of the component HTTP_Server:
dcmctl getState -co HTTP_Server
To get the state of a managed Oracle Application Server cluster:
dcmctl getState -cl cluster1
Returns a listing of dcmctl commands or help for a specific command.
dcmctl Properties
help [commandName]
Returns a listing of dcmctl commands. If a command name is specified after the help command, description and syntax information on that command is returned.
To list all commands:
dcmctl help
To get help for the createComponent command:
dcmctl help createcomponent
Imports an archive file to the current repository.
Archive
importArchive [-arch archiveName] -f myFile [-comment "myComments"]
Imports the named archive file to the current repository. Use –arch to change the name and –comment to change the comment during the import.
dcmctl importArchive –arch Archive1 –f /exports/testConfig -comment "this is an import"
Moves a File based repository.
Configuration Management
importRepository -f file_name [-force]
Moves a File based repository from one instance to another, based on a saved file from the exportRepository command. The repository may be restored to any instance in the farm. If the current instance is not hosting a repository, dcmctl prompts for confirmation of the action, unless the –force option is used.
If the repository has been moved, and the repository host is still a member of the farm, then the repositoryRelocated command must be run in the repository host instance to notify it that it is no longer the host.
Note for using importRepository:
Before running importRepository, stop all DCM daemons in the instances that are part of the farm where you are running importRepository. Use the following command at each instance in the farm to stop DCM daemons:
dcmctl shell dcmctl> shutdown
This example assumes that you have two instances: instance1 and instance2.
To relocate the file-based repository host from instance1 to instance2, perform the following steps:
On instance1, the original file-based repository host,
dcmctl shell dcmctl> exportrepository -f /export/repository_save_file dcmctl> shutdown
If there are more than two instances, issue the shutdown command on all the other instances.
On instance2, shutdown and then import the saved repository,
dcmctl shell dcmctl> shutdown dcmctl> importrepository -f /export/repository_save_file
On instance1,
dcmctl> repositoryrelocated
After the repositoryrelocated command completes, start the dcm daemons, as follows:
On instance1,
dcmctl> start -admin
When this command completes, issue the following command on instance2:
dcmctl> start -admin
If there are more than two instances, issue the following command sequentially on all of the other instances:
dcmctl> start -admin
Identifies whether an application server instance can become a member of a managed Oracle Application Server cluster.
Notes for using Oracle Application Server clusters:
Oracle Application Server supports heterogeneous instances as part of the same farm. For example, an instance running on Solaris Operating System, an instance running on a Linux system, and an instance running on an HP-UX system can reside in the same farm. Oracle Application Server instances that you want to be part of a cluster must be installed on identical operating systems
Oracle recommends that Oracle Application Server Clusters using a file based repository contain four (4) or less than four instances.
Configuration Management
isClusterable [-i instance_name | -arch archive_name]
Identifies whether an application server instance is eligible to become a member of a managed Oracle Application Server cluster. By default, this command uses the local instance. You can use the –i option to specify a different instance. In order for an instance to be eligible, all components in the instance must be clusterable.
If the instance is ineligible, and the verbose option is enabled, the reason is included with the false answer returned by the command.
dcmctl isClusterable
Identifies whether an application server instance is compatible with other members of a managed Oracle Application Server cluster.
Configuration Management
isCompatible -cl cluster_name [-i instance_name | -arch archive_name]
Identifies whether an application server instance is compatible with other members of a managed Oracle Application Server cluster. By default, this command uses the local instance. You can use the –i option to specify a different instance. An instance is compatible if it has the same components configured and is of the same version.
dcmctl isCompatible -cl cluster1
Adds an Oracle Application Server instance to the named managed cluster.
Notes for using Oracle Application Server clusters:
Oracle Application Server supports heterogeneous instances as part of the same farm. For example, an instance running on Solaris Operating System, an instance running on a Linux system, and an instance running on an HP-UX system can reside in the same farm.
Oracle Application Server instances that you want to be part of a cluster must be installed on identical operating systems
Oracle recommends that Oracle Application Server Clusters using a file based repository contain four (4) or less than four instances.
If you are using Oracle Enterprise Manager Application Server Control, then, after issuing joinCluster command, you must stop and then start Oracle Enterprise Manager Application Server Control using the commands:
%emctl stop iasconsole %emctl start iasconsole
Configuration Management
joinCluster -cl cluster_name [-i instance_name]
Adds an application server instance to the managed Oracle Application Server cluster specified with the –cl option. By default, this command uses the local instance. You can specify a different instance with the –i option. The instance must be a member of the same farm as the cluster. There is no limit to the number of instances you can add to a cluster. An instance is stopped after being added to a cluster, so you must manually start it.
To add the local application server instance to cluster1 and restart it:
dcmctl joinCluster -cl cluster1
dcmctl start
To add instance1 to cluster1 and restart it:
dcmctl joinCluster -cl cluster1 -i instance1
dcmctl start -i instance1
Associates an instance with a database repository or a File based repository.
Notes for using Oracle Application Server farms and the joinFarm command:
Oracle Application Server supports heterogeneous instances as part of the same farm. For example, an instance running on Solaris Operating System, an instance running on a Linux system, and an instance running on an HP-UX system can reside in the same farm.
Oracle Application Server instances that you want to be part of a cluster must be installed on identical operating systems.
Oracle recommends that Oracle Application Server Clusters using a file based repository contain four (4) or less than four instances.
If you are using Oracle Enterprise Manager Application Server Control, then, after issuing joinFarm command, you must stop and then start Oracle Enterprise Manager Application Server Control using the commands:
%emctl stop iasconsole %emctl start iasconsole
|
Caution: UsingjoinFarm, when an instance joins a farm all archives for the instance are removed. If you want to preserve the archives on the instance that is joining the farm, export each of the archives with the exportArchive command prior to using the joinfarm command.
|
Configuration Management
joinFarm [-r repository_ID]
With the –r option and a repository ID, it associates an instance with the named file- based repository. The repositoryId is a hostname and port.
If the instance was originally associated with a database repository, using infrastructure database information, you can issue this command without arguments to reassociate the instance with the original database.
You can obtain the file-based repository ID by issuing the getRepositoryId command on any instance that is a member of the farm associated with the repository. (To establish a distributed file-based repository, execute getRepositoryId on the instance that will host the repository, then issue the joinFarm command with the identifier returned by getRepositoryId). See the Oracle Application Server 10g High Availability Guide for a complete description of using getRepositoryId and joinFarm -r.
To reassociate the instance with a repository:
Get the repository ID from the instance that hosts the repository (the instance could be file-based or stored in a database).
% dcmctl getRepositoryID
Using the repository ID that you obtain in the previous step, issue the command:
% dcmctl joinFarm -r repository_ID
Removes an instance from a managed Oracle Application Server cluster.
Configuration Management
leaveCluster [-i instance_name]
Removes an application server instance from its managed Oracle Application Server cluster. By default, this command uses the local instance. You can specify a different instance with the –i option. The instance being removed is stopped, so you must restart it after using this command.
Note the following when using leaveCluster:
If you are using Oracle Enterprise Manager Application Server Control, then after issuing the dcmctl leaveCluster command, you must stop and then start Oracle Enterprise Manager Application Server Control using the commands:
% emctl stop iasconsole % emctl start iasconsole
To remove the local instance from the cluster:
dcmctl leaveCluster
To remove instance1 from its cluster:
dcmctl leaveCluster -i instance1
Removes an application server instance from a farm.
Configuration Management
leaveFarm
Removes an application server instance from a farm. This command affects only the relationship between DCM and a repository, and has no impact on other components. Specific implications for this command on the repository and other components are as follows:
Only the metadata for the DCM-managed configuration is moved from the centralized DCM repository to a local instance.
When an instance is removed from a farm, any associated archives are deleted from the centralized repository. For this reason, it is a good idea to issue the createArchive command immediately after issuing the leaveFarm command. This creates a new baseline archive for the instance.
The leaveFarm command does not remove connections to the infrastructure database for other components, such as Oracle Application Server Single Sign-On or JAZN.
Note for using leaveFarm:
Using Oracle Enterprise Manager Application Server Control, after issuing the dcmctl leaveFarm command, you must stop and then start Oracle Enterprise Manager Application Server Control using the commands:
% emctl stop iasconsole % emctl start iasconsole
To remove an instance from the farm:
dcmctl leaveFarm
Lists the applications deployed in an OC4J instance.
Application
listApplications [-cl cluster_name | -i instance_name | -arch archive_name] [-co component_name] [-sort]
List the applications deployed in the named OC4J instance. The default is the home OC4J instance in the local application server instance.
To list the applications in home:
dcmctl listApplications
1 BC4J
2 BC4JManager
3 transtrace
To list the applications in OC4J_SECURITY in instance1:
dcmctl listApplications -i instance1 -co OC4J_SECURITY
1 wirelesssso
2 oiddas
3 sso
Returns a list of archive names.
Archive
listArchives [–arch archive_name] [-sort]
Returns a list of archive names, and, with the –v (verbose) option, the display includes the name, source, version, and other information about the archive. If the –arch (archive name) option is used, only the named archive is listed.
To list information about archives:
dcmctl listarchives -v 1 Name: InstalledImage_M21.example.com Source: instance: M21.example.com Version: 9.0.4.0.0 Comments: This is an archive of the initial installed configuration. Created: 2003-10-27 12:01:55.327 Clusterable: true 2 Name: initial_archive_M21.example.com Source: instance: M21.example.com Version: 9.0.4.0.0 Comments: The initial archive after leaving the farm for M21.example.com Created: 2003-10-30 09:08:22.591 Clusterable: true
Lists the managed Oracle Application Server clusters in the local farm.
Configuration Management
listClusters
This command lists the managed Oracle Application Server clusters in the farm that is associated with the local application server instance.
dcmctl listClusters
1 cluster1
2 cluster2
Lists components within the named scope.
Configuration Management
listComponents [-i instance_name] [-cl cluster_name] [-arch archive_name] [-sort]
Returns a list of the components in the specified scope. Without arguments, this command returns a list of components in the local application server instance.
Components are listed in the format component type:component name.
The listcomponents command may display components that OPMN manages. Use the opmnctl command to manage, start, stop, and restart these components.
dcmctl listComponents
1 HTTP_Server:HTTP_Server
2 OC4J:OC4J_SECURITY
3 OC4J:home
4 OID:OID
Lists supported component types.
dcmctl Properties
listComponentTypes
Lists the component types that DCM supports.
dcmctl listComponentTypes
Lists the application server instances in the farm.
Configuration Management
listInstances [-cl cluster_name]
With no options, this command lists the application server instances that belong to the same farm as the local instance, but are not part of a cluster. If you use the –cl option, it lists only the instances that are part of the specified cluster.
To list all non-clustered instances in the farm associated with the local instance:
dcmctl listInstances
To list the instances in cluster1:
dcmctl listInstances -cl cluster1
Lists the instances that are in a non-managed Oracle Application Server cluster with the local instance.
Configuration Management
listOPMNlinks
This command lists all instances that are in a non-managed Oracle Application Server cluster with the local instance. These instances could have been added to the cluster using the addOPMNLink command.
dcmctl listopmnlinks
host1:6200
host2:6200
Ends a dcmctl shell client session.
Shell
quit
Ends a dcmctl shell client session. This command is only applicable to the shell; it does not affect the dcmctl daemon.
quit
Application
redeployApplication -f file -a app_name [-co comp_name] [-enableIIOP] [-rc rootcontext]
where
file is the name of the WAR or EAR file to deploy
app_name is the name of the application specified by the user in original deployment
comp_name is the name of the OC4J instance to which the application will be deployed. The default is the home instance.
–rc rootcontext is the base path used in the URL to access the web module (for example, http://hostname:port/context root). Applies to deployment of WAR files only.
This command redeploys a J2EE application (WAR or EAR file) to the local application server instance.
To redeploy app1.ear to the home OC4J instance:
dcmctl redeployApplication -f app1.ear -a app1
To redeploy app1.ear to the OC4J_myapps instance:
dcmctl redeployApplication -f app1.ear -a app1 -co OC4J_myapps
To redeploy app2.war to the home OC4J instance:
dcmctl redeployApplication -f app2.war -a app1 -rc /myiAS/myWebapps
Archive
removeArchive -arch archive_name
Deletes the named archive file.
dcmctl removeArchive –arch archive3
Removes a cluster from the farm.
Configuration Management
removeCluster -cl cluster_name
Remove the specified cluster from its farm. The cluster must contain no instances when it is removed. This command destroys all information about the cluster in the DCM repository.
dcmctl removeCluster -cl cluster1
Configuration Management
removeComponent -co component_name
Destroy an OC4J instance. By default, the OC4J instance must belong to the local application server instance. Note that OC4J is the only component type allowed for this command. You cannot remove any component that was created by the installation process (such as OC4J_SECURITY).
dcmctl removeComponent -co OC4J_myapps
Removes instances from a non-managed Oracle Application Server cluster.
Configuration Management
removeOPMNLink hostname:port[, hostname:port...]
Removes one or more instances from a non-managed Oracle Application Server cluster. You must run this command in the Oracle home of each instance in the cluster.
This example shows a non-managed Oracle Application Server cluster with three instances on host1, host2, and host3. The command removes the host2 instance.
HOST2_ORACLE_HOME/dcm/bin/dcmctl listopmnlinks
host1:6200
host2:6200
host3:6200
HOST1_ORACLE_HOME/dcm/bin/dcmctl removeopmnlink host2:6200
HOST2_ORACLE_HOME/dcm/bin/dcmctl removeopmnlink host2:6200
HOST3_ORACLE_HOME/dcm/bin/dcmctl removeopmnlink host2:6200
Notifies an instance that it is no longer hosting a repository.
|
Note: Usually you use of therepositoryRelocated command, after an associated exportRepository and importRepository. Before running importRepository and repositoryRelocated, stop all DCM daemons in the instances that are part of the farm where you run repositoryRelocated.
Use the following command in each instance in the farm to stop DCM daemons: dcmctl shell dcmctl> shutdown |
Configuration Management
repositoryRelocated
Notifies an instance that the repository it formerly hosted has been imported to another instance. This command is issued in the instance that formerly hosted the repository.
This command is used in conjunction with the importRepository command. A farm can only be associated with one repository at a time. When the repository is imported to a new instance of the farm, the old instance must be notified, through the repositoryRelocated command, that it is no longer the repository host.
This example assumes that you have two instances: instance1 and instance2.
To relocate the file-based repository host from instance1 to instance2, perform the following steps:
On instance1, the original file-based repository host,
dcmctl shell dcmctl> exportrepository -f /export/repository_save_file dcmctl> shutdown
If there are more than two instances, issue the shutdown command on all the other instances.
On instance2, shutdown and import the saved repository using these commands:
dcmctl shell dcmctl> shutdown dcmctl> importrepository -f /export/repository_save_file
On instance1, issue this command:
dcmctl> repositoryrelocated
After the repositoryrelocated command completes, start the DCM daemons, as follows:
On instance1, issue this command:
dcmctl> start -admin
When this command completes, on instance2 issue this command:
dcmctl> start -admin
If there are more than two instances, issue the following command sequentially on all of the other instances:
dcmctl> start -admin
Updates the port used by the DCM cache for instance discovery in Oracle Application Server Clusters that are managed using a file-based repository.
Configuration Management
resetDCMCachePort [new_port_number] [-r]
Changes the port value used by the DCM cache in File based clusters. To find the current host and port, issue the command without arguments, as follows:
dcmctl resetDCMCachePort
To update the port associated with the current instance, issue the command with the new port number, as follows:
dcmctl resetDCMCachePort 12345
If the port value is changed on the instance that is hosting the repository, other instances in the farm may not be able to locate the repository. If this occurs, issue the following command in the instance that cannot locate the repository:
dcmctl resetDCMCachePort -r 12345
where 12345 is the port number set at the repository host.
To find the current host and port:
dcmctl resetdcmcacheport
To update the port associated with the current instance:
dcmctl resetdcmcacheport 12345
To notify an instance of the location of the repository:
dcmctl resetdcmcacheport -r 12345
Resets a file repository to its pre-transaction state after an interrupted operation.
Configuration Management
resetFileTransaction
Resets a File based repository. If an operation on a File based repository is interrupted with control–c, uncommitted information may be left in the repository. This command blocks all subsequent updates to the repository, cleans up uncommitted data, and reopens the repository for update.
dcmctl resetfiletransaction
Updates IP address or hostname information.
Configuration Management
resetHostInformation [-r repository_hostname]
If the IP address or hostname information has changed for an instance in the farm, this command updates the repository and the ons.conf file with the new information. This command is used in the local instance. If the host information changes for the repository host of a File based farm repository, it is best to have all instances running, so that all instances can locate the repository.
For instances that were not running during the change, it may be necessary to update the repository host information directly. Use the –r option and the name of the repository host to do this.
resethostinformation
Restarts processes. This command is deprecated in Oracle Application Server 10g and is provided for backward compatibility only. Use opmnctl to manage processes in Oracle Application Server 10g.
Process Management
restart [[-cl cluster_name] | [-i instance_name] | [-co component_name] | [-ct component_type]] | [-admin]
Restarts running processes in the specified scope. This command does not restart OPMN or the DCM daemon, it leaves them running. Only the processes that were running when the command was issued are restarted. If the –admin option is used, then the DCM daemon is restarted.
To restart the local instance:
restart
To restart a remote instance:
restart -i myInstance
To restart a component across a cluster:
restart -cl myCluster -co myComponent
Restores configuration and application information to the local instance.
Configuration Management
restoreInstance [-dir directory_name]
This command is deprecated; use archiving commands instead. This command restores the configuration and application information for the local instance from the specified directory. The directory must have been created with saveInstance; instance information can only be restored to the instance from which it was saved. To move configuration between instances in a farm, use the applyClusterTo and applyInstanceTo commands. To move configuration between farms, use the exportArchive and importArchive commands.
This command stops the instance, you must restart the instance after this command.
If the instance is part of a managed Oracle Application Server cluster, it will be removed from the cluster before the configuration information is restored. This operation does not affect other members of the cluster.
To restore an instance to the configuration saved in /private/config1:
dcmctl restoreInstance -dir /private/config1
dcmctl start
Resynchronizes instance configuration files with the DCM repository.
Configuration Management
resyncInstance [-force]|[-i instance_name]
Resynchronizes the instance configuration files with the contents of the DCM repository. This command takes all data from the repository that is not yet propagated and writes it out to the configuration files for the specified instance. It updates the Oracle HTTP Server, OC4J, and OPMN configuration files, as well as targets.xml. It may also deploy or undeploy applications and add or remove components, as required. This could involve lengthy processing; use this command judiciously.
This command operates on the local application server instance, unless you specify a different instance with the –i option.
By default, the command only updates the configuration files for components whose In Sync Status is false (see getState). You can use the –force option to force it to update all configuration information.
To re synchronize instance1 with the contents of the DCM repository:
dcmctl resyncinstance -i instance1
To force all files in the local instance to be updated with that is in the DCM repository:
dcmctl resyncinstance -force
Saves configuration and application information.
Configuration Management
saveInstance -dir directory_name
This command is deprecated; use createArchive instead. This command saves the configuration and application information of the local instance to the designated directory. Creates the directory if it does not exist. If it does exist, then the specified directory must be empty. This command can be used to save the current configuration settings and installed J2EE applications before making configuration changes. You can then undo the changes, if necessary, using restoreInstance.
saveInstance -dir instance1/config
Sets dcmctl options, timeout value, sorting preference, and number of versions for automatically archived instances.
dcmctl Properties
dcmctl set [-v off | on] [-d off | on] [-t timeout_value] [-arch number_of_auto_archive_versions] [-sort off | on]
Sets properties of the dcmctl utility. The set command enables you to set the –verbose and –debug flags on a persistent basis, and the default time out value to be set on a persistent basis. You can also specify the number of versions to be automatically archived.
When set is run without any arguments, it displays the current settings.
|
Note: If you usedcmctl set commands while multiple DCM clients are active, the clients do not recognize the changed values until they are restarted. You must restart the dcmctl and Enterprise Manager clients after using dcmctl set with multiple active DCM clients.
|
To turn verbose and debug off, and set the timeout value to 200:
dcmctl set -v off -d off -t 200
To view current settings:
dcmctl set Verbose: true Sort: false Debug: true Default Timeout: 120 Auto Archive Count: 10
To set name sorting of ’list’ command output on:
set -sort on
To automatically archive 45 versions of an instance:
set -arch 45
To turn off automatic archiving:
set -arch 0
Shell
setLogLevel [-admin] [error] [notification] [debug] [trace]
Sets the logging level for the dcmctl client shell, or for the daemon (with the -admin option).
Set the DCM daemon log level,
setloglevel -admin notification
Sets the dcmctl shell log level,
setloglevel notification
Shell
Starts the dcmctl shell, and, optionally, executes the commands in a named file.
dcmctl shell [-f file_name]
To start the shell:
dcmctl shell
To start the shell and execute the commands in the file myDCMCommands:
dcmctl shell -f myDCMCommands
Process Management
Stops running processes in the local instance, including OPMN and the DCM daemon. To stop processes selectively, use stop.
dcmctl shutdown
dcmctl shutdown
Starts the named instance, cluster, or component. This command is deprecated in Oracle Application Server 10g and is provided for backward compatibility only. Use opmnctl to manage processes in Oracle Application Server 10g.
Process Management
dcmctl start [[-cl cluster_name] | [-i instance_name] | [-co comp_name] | [-ct comp_type]] | [-admin]
Starts all components indicated with the scope options. If no options are supplied, the command starts all components in the local application server instance. If the –admin option is used, this command starts the DCM daemon.
To start the cluster named myCluster:
dcmctl start -cl myCluster
To start all HTTP servers:
dcmctl start -ct HTTP_Server
Stops processes. This command is deprecated in Oracle Application Server 10g and is provided for backward compatibility only. Use opmnctl to manage processes in Oracle Application Server 10g.
Process Management
stop [[-cl cluster_name] | [-i instance_name] | [-co component_name] | [-ct component_type]] | [-admin]
Stops the specified processes. This command does not stop OPMN or the DCM daemon unless the –admin option is used; in that case, it stops the daemon. To stop everything, including the daemon, use shutdown.
To stop the cluster named myCluster:
dcmctl stop -cl myCluster
To stop all HTTP servers:
dcmctl stop -ct ohs
To stop a component across a cluster:
dcmctl stop -cl myCluster -co myComponent
Updates the repository with information from local configuration files.
The purpose of the updateConfig operation is to take the configuration that is currently stored in the local file system and place it into the DCM repository. This is a coarse grained operation with minimal validation of the content of the configuration file.
The dcmctl updateConfig command should be used in limited and controlled situations. It is recommended that when changing DCM managed configuration for Oracle HTTP Server, OC4J, OC4J applications, OPMN, or JAZN that you use either dcmctl commands or use Application Server Control. If you use these tools, then you do not need to use updateConfig.
If you need to manually edit configuration files for a component, you must use updateConfig to place these changes into the DCM repository. If you make manual changes and you do not run updateConfig the changes will be overwritten the next time that the configuration is resynchronized.
|
Caution: Do not runupdateConfig concurrently with any other dcmctl commands or while performing Application Server Control configuration operations across multiple instances in a farm or cluster.
|
Configuration Management
updateConfig [-ct component_type [, component_type...]] [-force]
Updates the DCM repository with the information in local configuration files. With no arguments, this command updates all DCM managed components, configuration files, as well as targets.xml. It does not cause all applications to be redeployed, but if an EAR or an expanded EAR file was changed manually since the last deployment, it will redeploy the application.
You can specify which component’s configuration files to update with the –ct option.
ohs: Oracle HTTP Server
oc4j: Oracle Application Server Containers for J2EE
opmn: Oracle Process Manager and Notification Server
jazn: Oracle Application Server Java Authentication and Authorization Service
When you make manual configuration file changes and then use updateConfig, follow these guidelines:
Before making a manual change requiring updateConfig, you should verify that your instance has the most current configuration from the DCM repository. Issue the resyncInstance command to resync the configuration.
Create an explicit archive for the instance or the cluster using createArchive.
While a configuration, make sure that there are no other administrative operations happening in the farm that may alter the configuration while you are making the manual change to the configuration. This includes Oracle Enterprise Manager Application Server Control changes, deployments, or other dcmctl shell or dcmctl commands running in the farm.
Make the manual configuration file change and test the change, if possible.
Finally, run dcmctl updateConfig to place the updated configuration files into the DCM repository.
If the precautions outlined in step 3 are not observed, there is a risk of conflicting changes being placed in the repository. This could leave the configuration stored in the repository in a non-functional state, and could require a restore from the archive created in step 2. If you restore from the archive, you will need to restart at step 1.
To register all DCM configuration files with the Distributed Configuration Management repository and restart them:
dcmctl updateConfig
dcmctl restart
If you have just updated an Oracle HTTP Server configuration file, you can register the change with the Distributed Configuration Management repository and restart Oracle HTTP Server as follows:
dcmctl updateConfig -ct ohs
dcmctl restart -ct ohs
Application
undeployApplication -a application_name -co instance_name
Undeploys the named application in the named Oracle Application Server Containers for J2EE instance.
To undeploy the application testApp in the home instance:
undeployApplication -a testApp -co home
Checks an EAR file for J2EE compliance.
Application
validateEarFile -f file [-noproxy]
Examines the named EAR file and lists characteristics that are not compliant with the J2EE specification.
You may need to set up a proxy to enable access to DTDs on the Web. You can pass a parameter to the JVM using the ORACLE_DCM_JVM_ARGS environment variable to specify the proxy host and port.
To validate the petstore EAR file:
dcmctl validateEarFile -f petstore.ear
Warning: J2EE/DTD validation errors were foundADMN-906001
{0} Base Exception: oracle.ias.sysmgmt.deployment.j2ee.exception.J2eeDeploymentException:Cannot get xml document by parsing /var/tmp/jar50152.tmp: Invalid element 'servlet' in content of 'web-app', expected elements '[servlet-mapping, session-config, mime-mapping, welcome-file-list, error-page, taglib, resource-ref, security-constraint, login-config, security-role, env-entry, ejb-ref]'.
Returns the cluster name for the named instance.
Configuration Management
Returns the name of the cluster that contains the named instance. If no instance is specified, returns the name of the cluster that contains the local instance.
whichCluster [-i instance_name]
dcmctl whichCluster
Identifies the type and location of the farm.
Configuration Management
Identifies the type and location of the farm.
Configuration Management
Returns farm name, farm type (database or distributed file based repository), the hosting instance, and the host name. If the repository is hosted by a third-party database, the hosting instance name and host name are not available.
dcmctl whichFarm
