Distributed Configuration Management Administrator's Guide 10g Release 2 (10.1.2) B13997-03 |
|
![]() Previous |
![]() Next |
This chapter describes DCM archiving capabilities, and explains how to restore saved configurations from archives.
This chapter covers the following topics:
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: ThesaveInstance and restoreInstance commands are deprecated; the archiving feature contains all of the functionality provided by saveInstance and restoreInstance . |
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.
Note: To list the archives, use thedcmctl listArchives command. The initial configuration archive is shown in the "User Generated Archives" section of the listArchives report. |
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.
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
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.
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
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. |
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:
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.
(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. |
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
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.