|
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 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 2-6, "Archive Commands") that enable you to create an archive of the configuration of an Oracle Application Server instance or cluster, and then apply the archived configuration to the same instance or cluster, or to a different instance or 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, so the initial configuration of Distributed Configuration Management is archived. The name of this archive is:
There are two ways to create archives:
Automatic Archiving creates an archive automatically prior to performing a DCM administrative operation. Use the dcmctl set command to verify that auto-archiving is enabled.
For example:
dcmctl set Verbose: true Sort: false Warning: true Debug: true Default Timeout: 120 Auto Archive Count: 15
The dcmctl set command shows the Auto Archive count value. If the Auto Archive Count is nonzero, then auto-archiving is enabled and an archive will be automatically created prior to issuing a DCM administrative command.
Even when auto-archiving is enabled, the Administrator may want to explicitly create a named version of an archive prior to performing a DCM administrative operation. Explicitly created archives are saved until the Administrator deletes them.
For example, to create an archive prior to deploying a new J2EE application named "foo" use the command,
dcmctl createArchive -arch PriorToDeployingFoo -comment "prior to foo deploy V1"
When using createArchive, it is a good practice to use an archive name and a corresponding comment that identifies the version of configuration that the archive is associated with. Regardless of whether you use automatic or explicit archiving, it is recommended that you create an archive prior to performing any administrative operation.
This section describes best practices for explicit and automatic archiving. It consists of the following topics.
There are two archive types available to be created. One archives cluster-wide data while the other archives both cluster-wide data and one single instance’s instance-specific data.
createArchive only archives data stored in the DCM Repository. After making manual modifications to OAS files, it is critical that dcmctl updateConfig be run. This command stores changes to DCM managed files in the DCM Repository and ensures that a properly created archive will then contain those changes.
|
Note: While it is recommended that the-comment switch, representing comments, be utilized to help describe the archive, this switch has been left off in the following documentation to help improve clarity of the concepts being discussed.
|
The contents of an archive created with createArchive -arch myArchiveName or createArchive -arch myArchiveName -i <myInstanceName> differ from the contents of an archive created with createArchive -arch myArchiveName -cl <clusterName>
The difference is as follows.
Cluster-wide (createArchive -cl) archives contain only cluster-specific information and do not contain any information specific to the instance it is created on.
Instance-specific (createArchive -i / or no option) archives contain cluster-specific information, plus any DCM managed information pertaining to the instance where createArchive was run.
If you have made instance-specific changes to an instance, and you want to ensure that they are saved, you should use the -i option and not the -cl option when running createArchive.
Currently, there is no simple way to differentiate instance-specific archives from cluster-specific archives. Due to this, it is highly recommended that you use comments to reflect which type of archive you are creating.
Note that applyArchiveTo does not apply instance-specific data, stored with the -i option, to a cluster. Please see the Best Practices for Restoring Archives section.
It is highly recommended that archives be exported for the highest level of protection.
|
Note: Please be certain to review the Automatic Archiving and Archive Types section to understand how Automatic Archiving handles archiving instance-specific data. It is also important to review the Best Practices for Restoring Archives section prior to needing to restore and archive to ensure that any restore operation goes smoothly and as expected. |
If you have a cluster which is comprised of three Oracle Application Server instances, you have made instance-specific changes on one instance, and you wish to save those changes in case you need to restore them in the future, you must run the following command to properly save the changes.
createArchive -arch archive_name -i instance_name
If you have a cluster which is comprised of three Oracle Application Server instances, you have made instance-specific changes on all instances, and you wish to save those changes in case you need to restore them in the future, you must run the following for each instance you wish to back up.
% createArchive -arch archive_name -i instance_name1
% createArchive -arch archive_name -i instance_name2
% createArchive -arch archive_name -i instance_name2
The Automatic Archiving feature of DCM works in the following fashion when generating archives.
If an instance is in a cluster, a cluster-specific (createArchive -cl) archive is generated.
If an instance is standalone, an instance-specific (createArchive -i) archive is generated.
It is important to note that any instance-specific changes made to a clustered instance do not get saved by the Automatic Archive mechanism. These changes will need to be saved explicitly by the Administrator following the guidelines in the Best Practices for Creating Archives section.
The process of restoring an explicit or automatic archive is the same. There are five different scenarios for restoring an archive.
Restoring an archive to a cluster.
Restoring an archive to a standalone instance.
Restoring an archive to a non-clustered instance
Restoring an instance-specific archive to only one instance in a cluster
Restoring instance-specific archives to a set of instances in a cluster
The procedure for each of these scenarios is given below. Please note that by peforming any of these procedures, the target cluster will be stopped. It is recommended that you create and export an archive before restoring another archive in case there are any issues, including accidentally restoring an undesired archive.
Pick an instance in the cluster as your management point.
Choose the archive you wish to restore. If necessary, import the archive from the file system using importArchive.
Run the following command.
% applyarchiveTo -cl cluster_name -arch archive_name
Pick an instance in the cluster as your management point.
Choose the archive you wish to restore. If necessary, import the archive from the file system using importArchive.
Run the following command.
% applyarchiveTo -cl archive_name -arch archive_name
Pick an instance in the cluster as your management point.
Choose the archive you wish to restore. If necessary, import the archive from the file system using importArchive.
Run the following command.
% applyarchiveTo -arch archive_name
Run these steps if you wish to restore instance-specific changes to an instance which is part of a cluster. Upon rejoining the cluster, cluster-specific information will be reset to cluster-settings, but instance-specific data will not be modified.
Pick an instance in the cluster as your management point.
Choose the archive you wish to restore. If necessary, import the archive from the file system using importArchive.
Have the instance leave the cluster by running leaveCluster on that instance.
% leaveCluster
Apply the archive.
% applyArchiveTo -arch archive_name
Verify that the instance-specific changes were restored.
Rejoin the cluster.
% joinCluster -cl cluster_name
You can also restore instance-specific changes to some or all instances which are part of a cluster. To do this, repeat the steps outlined in Restoring an Instance-specific Archive to Only One Instance in a Cluster for each instance you want to restore.
When an archive is created, the configuration and application deployment information associated with the archived object (the Oracle Application Server instance or cluster) is stored in the repository. This archived image can then be applied to any compatible instance or cluster in the repository, or exported to a file to be applied to an instance or cluster in another repository. The compatibility of an archive with an instance or cluster is similar to the compatibility of instances to be clustered.
Applying archives to instances and 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 cluster, the archive cannot contain any non-clusterable objects.
Information specific to an instance, such as host name, can only be applied back to the instance from which it came.
The configuration from one instance or cluster may be applied directly to another instance or cluster. That is, the apply functionality can take, as a source, an archive of an instance or a 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 repository to another Database repository
A File based repository to another File based repository
A Database repository to a File based repository
A File based repository to a Database 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 per component instance. Example 4-1, Example 4-2, and Example 4-3 provide sample archive files.
|
Caution: Do not edit the archive files. If you do, the archive may not function as it should. |
Example 4-1 Expanded Export file
Archive_Information Export_Information Default_Information HTTP Server home Component1 Component2
Using automatic archiving, an archive is created automatically when you perform any operation listed in Table 4-1. The automatic archives coexist with archives created with the createArchive command, and are made distinct by their system-generated name. Example 4-6 shows an example of an automatic archive name for archive 2 in the example.
Table 4-1 Automatic Archive Operations
| Add an instance to a cluster |
| Change a cluster’s attributes |
| Change an instance’s attributes |
| Configure Oracle Application Server Single Sign-On with configuration tool |
| Create a new OC4J instance |
| Deploy a J2EE application |
| Issue the updateConfig command |
| Join a cluster |
| Configure Oracle Application Server using Enterprise Manager standalone console |
| 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 4-4 and Example 4-5.
The integer value specifies the automatic archive limit for the associated instance or cluster. For example, if you have a farm with 10 instances and each instance has an automatic archive count of 15, the automatic archive count will continue to grow until 150 archives are created.
Automatic archives have system-generated names that resemble those shown in archive 2 in Example 4-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 farm. When an instance is a member of a cluster, the Source: identifier is shown as: "cluster: cluster name".
Example 4-6 Automatic Archive Names (listArchives Command Output)
dcmctl> listarchives 1 Name: InstalledImage_10gM21.example.com Source: instance: 10gM21.example.com Version: 9.0.4.0.0 Comments: This is an archive of the initial installed configuration for this instance. Created: 2003-11-12 14:08:34.162 Clusterable: true 2 Name: dcm.autoarchive_222.222.3.12.999f1921.f8d70c4e79.-7fff Source: instance: 10gM21.example.com Version: 9.0.4.0.0 Comments: Automatic archival prior to hand-editing of configuration files OC4J OHS opmn jazn Created: 2003-11-13 13:45:49.259 Clusterable: true
You should save the DCM configuration regularly. You may find it useful to create "before" and "after" snapshots of a configuration when extensive configuration changes are performed.
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
(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, archives saved there are lost. Exporting the archive to a file system provides an extra measure of safety. |
If, by accident, an instance is destroyed or a repository contains errors, you can restore the configuration from an exported archive with the import command:
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
