3 Archiving A Managed Configuration

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.

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:

InstalledImageinstance_name

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

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:

• The source of the archive must have the same installed components configured as the destination. If the destination is a OracleAS Cluster, the archive cannot contain any non-clusterable objects.

• The source of the archive and the instance or cluster to which it is applied must be of the same installation type and version.

• Information specific to an Oracle Application Server Instance, such as host name, can only be applied back to the Oracle Application Server Instance from which it came.

• The configuration from one Oracle Application Server Instance or OracleAS Cluster may be applied directly to another Oracle Application Server Instance or OracleAS Cluster. That is, the apply operation can take, as a source, an archive of an Oracle Application Server Instance or a OracleAS Cluster.

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:

• A Database-based repository to another Database-based repository

• A File-based repository to another File-based repository

• A Database-based repository to a File-based repository

• A File-based repository to a Database-based repository

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.

Archive_Information
Export_Information
Default_Information
HTTP Server
home
Component1
Component2

Export_Information:
Version: 10.1.2.0.0
Comments: ÒUser comments about the exportÓ
Farm: dbmachine.1234.5678
Create Time: Mon Sep 30 12:42:10 PDT 2002

Archive_Information:
Name: archive1
Source: cluster1
Version: 10.1.2.0.0
Configured Component Types: [Apache, J2EE]
Comments: ÒUser comments about the archiveÓ
Create Time: 2002-09-26 16:46:40.0
Clusterable:true

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.

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.

dcmctl set -arch 10

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

dcmctl listArchives
****** AUTO GENERATED ARCHIVES ******
1
Name:         dcm.autoarchive_138.2.142.2121ff7a1e.fcb87f2e6d.-7ffe
Source:       instance: my-sun.us.oracle.comVersion:      10.1.2.0.0
Comments:     Automatic archival prior to deployment of application IsWebCacheWkngCreated:      2004-05-24 12:34:24.972Clusterable:  true

2
Name:         dcm.autoarchive_138.2.142.21212d3205.fcb882fb5b.-7fff
Source:       instance: my-sun.us.oracle.com
Version:      10.1.2.0.0
Comments:     Automatic archival prior to hand-editing of configuration files OC4J OHS opmn jazn 
Created:      2004-05-24 12:35:59.168
Clusterable:  true

****** USER GENERATED ARCHIVES ******
1
Name:         initial_archive_my-sun.us.oracle.com
Source:       instance: my-sun.us.oracle.com
Version:      10.1.2.0.0
Comments:     The initial archive after joining the farm for my-sun.us.oracle.com
Created:      2004-05-24 14:01:54.158
Clusterable:  true

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
   
   

   or

   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
   

   
   

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

• Use disk space efficiently. Within an Oracle Application Server Instance, there are many managed objects (including configuration files and EAR or WAR files), but when an archive is created, only one copy of any given version of a managed object is saved in the repository.

• Restore the state of an Oracle Application Server Instance or OracleAS Cluster to a prior state. The DCM system automatically takes an archive when it performs certain administrative operations so that the administrator has the option to roll back undesired administrative changes. The number of automatic archives that are saved is configurable.

• Explicitly create archives to satisfy a site's change management or staging policy. For example, when staging groups of changes that an administrator may want to collectively rollback, or push to other Oracle Application Server Instances, it is a good idea to explicitly create an archive.

• Use archives to apply the state of any Oracle Application Server Instance to the state of any available archive. An archive can also be applied to another Oracle Application Server Instance in the same Oracle Application Server Farm, or exported and imported to another Oracle Application Server Farm and then applied to an Oracle Application Server Instance in that Oracle Application Server Farm. (A hybrid staging solution is to first stage and test changes to a non-clustered Oracle Application Server Instance, archive the changes, and finally apply the archive to an OracleAS Cluster. These changes are then automatically propagated to all members of the OracleAS Cluster.)

  
  

  Note: After applying an archive to an Oracle Application Server Instance other than the Oracle Application Server Instance from which it was created, some instance-specific configuration data may have to be modified. DCM automates this for IP addresses and hostnames. See Section 2.2.4.2, "Parameters Excluded from the Common Configuration: Instance-Specfic Parameters" for lists of these parameters in OHS, OC4J, and OPMN.

  
  

• If you use OracleAS Clusters, DCM assures that any change to the configuration is automatically distributed to all members of the OracleAS Cluster. As an alternative to using OracleAS Clusters, an archive of a staged configuration can be applied manually to non-clustered Oracle Application Server Instances in an Oracle Application Server Farm.