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:

• DCM Archiving Commands

• Initial Archive Creation

• Archive and Instance Compatibility

• Exporting and Importing Archives

• Using Automatic Archiving

• Preserving Configurations With Archive Commands

• Importing and Applying an Archive to an Instance

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.

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

InstalledImageinstance_name

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

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

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

See Also: isClusterable

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.

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

Example 3-1 Expanded Export file

Archive_Information

Export_Information

Default_Information

HTTP Server

home

Component1

Component2

Example 3-2 Export_Information File

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

Example 3-3 Archive_Information File

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.

Table 3-1 Automatic Archive Operations

Operation
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

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

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

   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.