Skip Headers
Distributed Configuration Management Administrator's Guide
10g Release 2 (10.1.2)
  Go To Documentation Library
Go To Product List
Solution Area
Go To Table Of Contents
Go To Index


3 Archiving A Managed Configuration

This chapter describes DCM archiving capabilities, and explains how to restore saved configurations from archives.

This chapter covers the following topics:

3.1 DCM Archiving Commands

The dcmctl utility provides commands (listed in Table A-6, "Archive Commands") that enable you to create an archive of the configuration of an Oracle Application Server Instance or OracleAS Cluster, and then apply the archived configuration to the same Oracle Application Server Instance or OracleAS Cluster, or to a different Oracle Application Server Instance or OracleAS Cluster. The archiving feature makes it easy to save configurations before making changes to the system, or to save and restore a particular configuration for specific purposes, such as operating one configuration during the day and another at night.


The saveInstance and restoreInstance commands are deprecated; the archiving feature contains all of the functionality provided by saveInstance and restoreInstance.

3.2 Initial Archive Creation

The Oracle Universal Installer invokes the archiving function at the end of installation, and archives the initial configuration of Distributed Configuration Management. The name of the initial archive is:


In the example above, name is the name of the Oracle Application Server Instance.


To list the archives, use the dcmctl listArchives command. The initial configuration archive is shown in the "User Generated Archives" section of the listArchives report.

3.3 Archive and Instance Compatibility

When an archive is created, the configuration and application deployment information associated with the archived object (the Oracle Application Server Instance or OracleAS Cluster) is stored in the repository. This archived image can then be applied to any compatible Oracle Application Server Instance or OracleAS Cluster in the repository, or exported to a file to be applied to an Oracle Application Server Instance or OracleAS Cluster in another repository. The compatibility of an archive with an Oracle Application Server Instance or OracleAS Cluster is similar to the compatibility of Oracle Application Server Instances to be clustered.

Applying archives to Oracle Application Server Instances and OracleAS Clusters is subject to these compatibility rules:

See Also:


3.4 Exporting and Importing Archives

You can export an archive from the repository to a file, and then import the file back to the same repository, or to a different repository. You can change the name of the archive and associated comments during the import. The original archive name and comments are the defaults.

You can also export from a repository to a file, and import from a file to a repository. The import and export functionality allows an archive to be moved from one repository to another. Archives can be moved from:

The exported archive file is in a .jar format. Two entries in the jar file encapsulate a description of the archive: Export_Information and Archive_Information. These entries can be extracted from the export file and viewed as text. The other entries in the export file contain the configuration information, one entry for each component instance. Example 3-1, Example 3-2, and Example 3-3 provide sample archive files.

In Oracle Application Server 10g Release 2 (10.1.2), the files stored in the DCM Repository are not the actual configuration files, but are an internal form with information such as the ORACLE_HOME, host name, and IP address removed. The current archive files are binary. They are JAR files (ZIP files with additional metadata) that could be stored in a version control system and the used later to apply a prior version of configuration. Considering the configuration data stored within the archive is an internal Oracle form, it makes sense to keep archive files in binary form, rather than exploding the JAR and storing individual files.


Do not edit the archive files. If you do, the archive may not function as it should.

Example 3-1 Expanded Export file




HTTP Server




Example 3-2 Export_Information File



Comments: ÒUser comments about the exportÓ

Farm: dbmachine.1234.5678

Create Time: Mon Sep 30 12:42:10 PDT 2002

Example 3-3 Archive_Information File


Name: archive1

Source: cluster1


Configured Component Types: [Apache, J2EE]

Comments: ÒUser comments about the archiveÓ

Create Time: 2002-09-26 16:46:40.0


3.5 Using Automatic Archiving

When you turn automatic archiving on, DCM automatically creates an archive when you perform any operation listed in Table 3-1. The automatic archives coexist with archives created with the createArchive command, and are distinguished by their system-generated name.

Example 3-6 shows several automatically generated archives.

Table 3-1 Automatic Archive Operations


Add an Oracle Application Server Instance to an OracleAS Cluster

Change an OracleAS Cluster's attributes

Change an Oracle Application Server Instance's attributes

Configure Oracle Application Server Single Sign-On with configuration tool

Create a new OC4J instance

Deploy a J2EE application

Dump or clear instrumentation timer

Issue the updateConfig command

Join an OracleAS Cluster

Perform a configuration change with System Management Interface

Remove an OC4J instance

You can specify the number of automatic archive versions you want to save, or disable automatic archiving with the set command, using the -arch option and an integer, as shown in Example 3-4 and Example 3-5.

Example 3-4 Setting Automatic Archiving to Save 10 Versions

dcmctl set -arch 10

Example 3-5 Turning Automatic Archiving Off

dcmctl set -arch 0

Automatic archives have system-generated names that resemble those shown in archive 2 in Example 3-6. Automatic archive names all begin with dcm.autoarchive. Appended to this is the IP address of the computer, an identifier for the DCM operation that triggered the archive, and a user ID that is unique to the computer. This ensures that the automatic archive name is unique across the Oracle Application Server Farm. When an Oracle Application Server Instance is a member of an OracleAS Cluster, the Source: identifier is shown as: "cluster: cluster name".

Example 3-6 Automatic versus User Generated Archive Names (listArchives Command Output)

dcmctl listArchives



Name:         dcm.autoarchive_138.2.142.2121ff7a1e.fcb87f2e6d.-7ffe

Source:       instance:

Comments:     Automatic archival prior to deployment of application IsWebCacheWkngCreated:      2004-05-24 12:34:24.972Clusterable:  true


Name:         dcm.autoarchive_138.2.142.21212d3205.fcb882fb5b.-7fff

Source:       instance:


Comments:     Automatic archival prior to hand-editing of configuration files OC4J OHS opmn jazn 

Created:      2004-05-24 12:35:59.168

Clusterable:  true




Source:       instance:


Comments:     The initial archive after joining the farm for

Created:      2004-05-24 14:01:54.158

Clusterable:  true

3.5.1 Tuning Automatic Archiving to Improve Performance

When you install Oracle Application Server, the auto-archiving feature is set to maintain fifteen archives. You can improve system performance by reducing the number of archives, or by turning off auto-archiving.


Limiting or disabling DCM auto-archiving may reduce the potential for full recovery from a system failure.

3.6 Preserving Configurations With Archive Commands

You should save the DCM configuration regularly. You may find it useful to create "before" and "after" snapshots of a configuration when performing extensive configuration changes. Archives that you create are designated as user-generated archives, to differentiate them from archives created automatically (shown in Example 3-6). Use the following steps to create an archive:

  1. Issue one of the following commands (depending on the configuration):

    dcmctl createarchive -arch archive name -cl cluster name


    dcmctl createarchive -arch archive name -i instance name

    The archive is created in the repository.

  2. (Optional) Export the archive to the file system with this command:

    dcmctl exportarchive -arch archive name -f file name


    Archives are stored in the repository. If you do not export an archive to the file system, and the repository is destroyed, any archives saved in the repository are also lost. Exporting the archive to the file system provides an extra measure of safety.

3.7 Importing and Applying an Archive to an Instance

If an Oracle Application Server Instance is inadvertently destroyed or a repository contains errors, you can restore the configuration from an exported archive. Use the importArchive command to bring the archive from the file system to the repository:

dcmctl importarchive -arch archive name -f file name

You can restore an archive to the DCM repository with one of the following commands:

dcmctl applyarchiveto -arch archive name -cl cluster name

dcmctl applyarchiveto -arch archive name -i instance name

3.8 Benefits of Archiving

The DCM archive feature provides a convenient way to create snapshots of the DCM-managed portions of Oracle Application Server system configuration. Archives are useful for staging changes, recovering from errors, and provisioning DCM- managed Oracle Application Server Instance configuration information from one Oracle Application Server Instance to another. Archiving enables you to: