The following procedure merges the source directory /.:/eng into the empty target directory /.:/rnd/eng (that is, appends the /.:/eng directory under the /.:/rnd directory). Step 3 of the procedure deletes the merged /.:/eng directory from its original location and replaces it with a soft link to redirect lookups of /.:/eng to the /.:/rnd directory.

1. The following dump subtree command creates an interim file named eng.dat that contains the /.:/eng directory and its contents, /.:/eng/obj1 and /.:/eng/link1.

   cdscp> dump subtree /.:/eng into file eng.dat

2. The following create directory command creates a new empty directory named /.:/rnd/eng.

   cdscp> create directory /.:/rnd/eng

3. The following merge file command merges the interim file you created in step 1 (eng.dat) with the new /.:/rnd/eng directory. The failures to file argument copies, to a failures file named failures.dat, any names that cannot be created in the target subtree. This example assumes that all affected files were successfully merged. See Section 11.3 for more information on how to use the failures file.

   cdscp> merge file eng.dat into subtree /.:/rnd/eng failures to file failures.dat

4. After the append operation, the /.:/eng directory (and its contents) still exists at the source location. The following commands delete the /.:/eng directory from its original location and then create a soft link named /.:/eng in place of the deleted directory. This soft link redirects lookups of /obj1 and /link1 to their new locations in the /.:/rnd/eng directory.

   cdscp> delete subtree /.:/eng

   cdscp> create link /.:/eng CDS_LinkTarget /.:/rnd/eng

   
   Figure 11-3 shows the structure of the example namespace before and after this append operation.

   Figure 11-3 Example Namespace Before and After the Append Operation

   ---

   

Use the merge file command's failures to file argument to save a copy of directory and name information that cannot be merged. A failures file, like an interim file, is a printable ASCII file that can contain the following information:

• Duplicate names (and their attributes) detected during the merge operation
• Names in the source subtree stored in clearinghouses that were not reachable when the command was executing

You can use this information as an index of the names that cannot be merged or, when appropriate, you can merge the failures file itself on a subsequent merge operation.

11.3.1 Handling Duplicate Names

If the full name of a source directory, object entry, or soft link is identical to a full name of a target directory, object entry, or soft link, the merge file command does not merge the duplicate source name. Duplicate names are not merged, to avoid overwriting and destroying the identical names in the target directory.

The failures to file argument is especially useful in merge file commands that specify directories in which you know or suspect that duplicate names exist. During execution, the merge file command displays any duplicate names on your screen and copies them to the failures file.

If duplicate names exist, you need to decide which name you want to preserve: the name in the source subtree or the name in the target subtree. You can perform any of the following operations to eliminate a conflict:

• Delete the duplicate name in the target subtree, then reenter the merge file command and specify the failures file (rather than the interim file) in the command's ifile argument.
• Delete the duplicate name from the source subtree, redump the subtree to a new interim file, then repeat the merge operation using the new interim file. If you choose this solution, you do not need to use the failures file.
• Use the CDS recreate commands to recreate (under a new name) any duplicate object entry, soft link, or directory in the source subtree as a new object entry, soft link, or directory in the target subtree. Then delete the duplicate name from the source subtree.
  New names that you create with the recreate commands retain the same writable attribute values (including their ACLs) as the existing source names on which they are based. The commands do not delete or modify the existing names. An additional ACL entry is created for the new name (in the target subtree) that grants the creator full access to the name. The new name also inherits any existing default ACLs that may be propagated from the parent directory (the directory in which you re-create the name) in the target subtree. The name that you assign to the new directory, object entry, or soft link in the target subtree must be different from the name of the existing directory, object entry, or soft link in the source subtree.

  Note The recreate commands are also useful for creating new object entries whose user-defined, writable attributes (with the exception of their associated ACLs) are identical to those of an existing application-defined object entry. This is especially useful when the existing object entry maintains many writable attributes whose values you would otherwise have to assign individually with the set object command.

Sometimes, the clearinghouse that stores the master replica of a directory you are trying to merge will be disabled or will be unreachable when you enter the merge file command. When this happens, CDS is unable to create the directory and the entries it contains at the new target location.

When unable to merge a name for this reason, the merge file command copies the name and its associated attributes to the failures file and displays an error message specifying the name that could not be created. By maintaining a log of these messages, you can identify failures that were caused by name conflicts as opposed to failures that were caused because a name was unreachable and could not be created.

11.4 Merging CDS Directories with a Single Command

Although not always appropriate, you may sometimes be able to use the merge subtree command to merge or append directories. The merge subtree command combines step 1 (dump subtree) and step 2 (merge file) of a merge operation into a single command.

You can use the merge subtree command when you are sure that the following two conditions are satisfied:

• No duplicate names exist in the source and target directories.
• All clearinghouses that store master replicas of affected directories (at both the source and target locations) are running and reachable when you enter the command.

If a duplicate name is detected, or if any affected clearinghouse cannot be reached while the merge subtree command is in progress, the affected entries are not merged.

Unlike the merge file command, no failures file is created. Errors are reported only to your screen.

If the merge operation is incomplete, you can delete the partially merged information at the target location. Then reenter the command after you delete any duplicate names and are certain that connectivity to the affected clearinghouses can be maintained.

Example

The following merge subtree command (which produces the same result as steps 1 and 2 in Section 11.2.1) merges the /.:/eng directory with the /.:/rnd directory. This example assumes that no duplicate names exist and the master replicas of all affected directories are reachable.

cdscp> merge subtree /.:/eng into subtree /.:/rnd

11.5 Merging CDS Directories into a Foreign Cell

You can also use the dump subtree and merge file commands to merge CDS directories into the namespace of a foreign cell. In general, the procedure you follow is the same as the procedure you use to merge directories or subtrees within the same namespace. There are, however, some additional considerations to keep in mind.

Before you try to merge directories or subtrees into the namespace of a foreign cell, be aware of the following prerequisites and restrictions:

• Establish Cross-Cell Authentication in Advance
  If you want users and applications in the source cell to be able to conveniently continue accessing their merged information in the target cell, make sure that an agreement of cross-cell authentication exists between the source cell and foreign (target) cell. Otherwise, principals from the source cell requesting newly merged information will not be permitted to communicate with the target cell. See the DCE Security part in the OSF DCE Administration Guide --- Core Components for complete information on how to set up cross-cell authentication.
• Source ACL is Recreated in the Target Cell
  To preserve the access currently enjoyed by principals registered in the source cell to the merged information in the target cell, ACL entries associated with newly merged names from the source subtree are recreated in the target subtree according to the following scheme:
  Source ACL entries of type user are recreated in the target cell as type foreign_user. Source ACL entries of type group are recreated as type foreign_group. Source ACL entries of type any_other are recreated as type foreign_other.
  Source ACL entries of type unauthenticated are merged with any existing unauthenticated ACL entries in the target cell. If no unauthenticated entry exists on the target side, a new unauthenticated ACL entry is created.

  Note If you prefer not to merge the access control lists associated with the directory information you intend to merge with the foreign cell, you can use the exclude acls keyword in the dump subtree command you issue in step 1 of the procedure to create the interim file.

• Merging Entire Namespaces
  As part of a cell's creation, the DCE configuration process creates an initial CDS hierarchy of directories (/.:/hosts, /.:/subsys, /.:/subsys/dce, /.:/subsys/dce/sec, and so on) largely containing information for DCE's own use internally. Because these directories reside directly beneath the root directory in all CDS namespaces, they constitute duplicate names. To merge these duplicate directories, you can create a separate interim file for each source directory, then merge each interim file individually with its counterpart in the namespace of the foreign cell.

To Merge Data into a Foreign Cell

To merge CDS data into the namespace of a foreign cell, follow these steps:

1. While logged in to the source cell, use the dump subtree command to dump, into an interim file, the directory information you intend to merge with the foreign cell.
2. Physically copy or transfer the interim file to any system participating in the foreign cell.
3. While logged in to a privileged account (cell_admin or cds-admin) on the machine to which you copied the interim file in step 1, use the merge file command to merge the contents of the interim file with an existing directory in the foreign cell.
4. If you intend to continue accessing the merged information from the source cell, delete the uppermost directory in the source subtree that you dumped to the interim file in step 1 and replace the deleted information with a single soft link of the same name as that directory. This will redirect lookups of the information at its new location in the foreign cell.

Because updates and skulks of directories can occur asynchronously, and because of the distributed nature of a namespace itself, you cannot always depend on traditional backup methods to preserve CDS data. The following sections describe the proper use of the following three backup mechanisms:

• Directory replication --- For most namespaces, replication is the only completely reliable method of protecting CDS namespace data. By maintaining multiple replicas of each directory, you can more easily restore lost or damaged clearinghouse database files.
• CDS dump/merge facilities --- You can merge recently dumped directory information back into your namespace hierarchy to restore deleted directories and their contents.
• Operating system backups --- Traditional operating system backups are not recommended unless your namespace resides on a single clearinghouse.

Directory replication is always the most reliable way to back up the information in your namespace. When you create a new replica of a directory, you are not only distributing the information but also creating an up-to-date, real-time backup of the information. If a replica in one clearinghouse becomes unavailable, users can look up the information they need in another replica of the directory in some other clearinghouse. The more replicas of a directory you create, the more likely users and applications will always be able to find the information contained in the directory somewhere in the namespace.

If an entire clearinghouse is corrupted, you can restore it by creating a new clearinghouse and then creating new replicas of the directories that were stored there. See the CDS part in the DCE Administration Guide --- Core Components for complete information on how to restore a lost clearinghouse.

11.6.2 Using the Dump/Merge Facilities to Back Up Directories and Their Contents

You can use the dump subtree command to produce an interim file that contains a copy of the structure and contents of any portion of your namespace hierarchy. You can then use this file as a backup to restore deleted directories and their contents by loading the file back into your namespace with the merge file command.

If you have an interim file available that contains a recent copy of an accidentally deleted directory, you can use the merge file command to append that copy of the directory back under its former parent directory. Then, using the create replica command, you can create a new replica of the directory in each of the clearinghouses from which the directory was deleted. Although the information in an interim file may be slightly out of date, using an interim file to restore the directory and its contents is usually more efficient than creating a new directory and repopulating it one name at a time. See Section 11.1 for information on how to create an interim file.

Remember that the dump subtree command affects only directories and their contents. It does not copy clearinghouses or their associated clearinghouse object entries to the interim file and therefore cannot be used to restore clearinghouses or to account for discrepancies in information among individual replicas resident on different clearinghouses. Furthermore, as with traditional operating system backups, the directory information in an interim file only reflects what the affected directories contained at the time you created the file.

See the chapter on CDS subtree commands for information on using the dump subtree and merge file commands.

11.6.3 Using Operating System Backups

Because a namespace is a distributed database to which modifications are synchronized at variable intervals, traditional backups of a particular server system will always contain old and incomplete information. If you frequently create, modify, or delete names, restoring an out-of-date backup may cause recently created names to disappear, recent modifications to be reversed, or recently deleted names to reappear in the namespace. The degree to which a traditional backup reflects the current condition of a clearinghouse depends entirely on how recently the backup was created and what modifications were made since that time.

If you decide to use operating system backups, you should only back up the server systems whose clearinghouses store master replicas of directories. Make sure you disable the clearinghouses on these systems before you perform the backup procedure.

If your namespace is small enough to be contained on one clearinghouse, you can reliably use traditional operating system backups to save and restore the clearinghouse data. If only one clearinghouse exists, only one replica (the master replica) of each directory exists. This eliminates the need to account for the discrepancies that may exist among multiple directory replicas. Remember that the more frequently you back up clearinghouse data, the more up-to-date that information will be should you need to restore it.