Chapter 19   mmldif


The mmldif (multi-merge of LDIF) tool combines multiple LDIF files into a single directory hierarchy. The result is the union of all input files: it contains any entry whose DN appears in one or more of the input files.

In a typical usage scenario, mmldif can be used to recreate an authoritative database for servers cooperating in a multi-master replication agreement. If for some reason all masters are no longer able to synchronize, the mmldif tool can be used to regenerate the master database manually.

This chapter contains the following sections:

• Command Usage

• Examples and Sample Output

Command Usage

---

The mmldif tool performs a union of all input files, based on the DNs they contain: entries that exist in one or more input files are added to the hierarchy of the final output. When the same DN appears in multiple files, the tool will verify that all attribute values are identical. If the attribute values differ, the conflict is resolved by choosing the entry with the most recent time stamp.

The time stamp is given by one of the following attributes: modifyTimestamp, createTimestamp, or deleteTimestamp. The tool also recognizes deleted entries by their objectclass: nsTombstone attribute and handles them accordingly. For LDIF files to contain these special attributes, you must use the db2ldif -r option when extracting the entries from your directories (see Chapter 7, "Command-Line Scripts," in the iPlanet Directory Server Command, Configuration and File Reference).

Optionally, mmldif can generate change files for each of the input files. Change files contain LDIF update statements that represent the difference between the corresponding input and the merge result. Applying the change file to the directory of the corresponding input will make the directory contents equivalent to the contents of the merge result. To do this, the change file can be used as input to the ldapmodify command (see Chapter 4).

Syntax

The mmldif command has the following syntax:

mmldif [-c] [-o output .ldif] input1 .ldif input2 .ldif ...

Where:

• output .ldif is the name of a writable file for the LDIF output.

• inputn .ldif is an LDIF input file to be merged. You must specify at least two input files, and you may specify more.

The mmldif -h command will display a usage help text that briefly describes all options.

Options

The mmldif options and parameters are described in the following table.

Table 19-1    Command-Line Options for the mmldif Tool 

Option	Parameter	Purpose
-o	outputFile	Specify the output file for the merge of all LDIF inputs. The output file is itself a complete directory hierarchy in LDIF text. When this parameter is omitted, the mmldif tool produces no output and reports only the number of differences between the input files.
-c		Write a change file containing LDIF update statements for each input file. The change file will have the same path and filename as the corresponding input file, with the addition of the suffix .delta. When using this option, the input files must be in a writable location. Old change files for the same input will be overwritten.
-h		Display the usage help text that briefly describes all options.

Examples and Sample Output

---

The examples in this section demonstrate the output of the mmldif tool. These examples are based the following input files. Differences between the files are shown in bold type:

Table 19-2    Sample mmldif Input Files

Filename: one.ldif

Filename: two.ldif

dn: sn=Jensen,dc=siroe,dc=com objectclass: top objectclass: person cn: Babs Jensen sn: Jensen telephoneNumber: 555-5550 createTimestamp: 100 dn: sn=Minsky,dc=siroe,dc=com objectclass: top objectclass: person cn: Pete Minsky sn: Minsky telephoneNumber: 555-5551 createTimestamp: 100 dn: sn=Rose,dc=siroe,dc=com objectclass: top objectclass: person cn: Paula Rose sn: Rose telephoneNumber: 555-5552 createTimestamp: 100

dn: sn=Jensen,dc=siroe,dc=com objectclass: top objectclass: person cn: Babs Jensen sn: Jensen telephoneNumber: 555-5550 createTimestamp: 100 dn: sn=Minsky,dc=siroe,dc=com objectclass: top objectclass: person cn: Pete Minsky sn: Minsky telephoneNumber: 555-5559 modifyTimestamp: 200 dn: sn=Morris,dc=siroe,dc=com objectclass: top objectclass: person cn: Ted Morris sn: Morris telephoneNumber: 555-5558 createTimestamp: 200 dn: sn=Rose,dc=siroe,dc=com objectclass: nsTombstone deleteTimestamp: 200

Merge Statistics

The mmldif tool always displays merge statistics to the standard output. The -o outputFile parameter may be omitted when you are interested only in the number of differences between input files.

$ mmldif one.ldif two.ldif

start time Wed Jul 11 12:34:56 2001

entry counts: unchanged=1 changed=2 new=1 total=4

end time Wed Jul 11 12:34:56 2001
differencing took <= 1 second

This output confirms what we can see in our simple example files:

• unchanged=1 - There is one entry where all attributes match exactly.

• changed=2 - Two entries with matching DNs have different attribute values.

• new=1 - One entry is considered new: its DN does not appear in all files.

• total=4 - The input files contain a total of four different DNs.

Merge Output File

Running the command again with the -o outputFile parameter will allow us to see the result of the merge.

$ mmldif -o merge.ldif one.ldif two.ldif

start time Wed Jul 11 12:34:56 2001

entry counts: unchanged=1 changed=2 new=1 total=4

end time Wed Jul 11 12:34:56 2001
differencing took <= 1 second

$ cat merge.ldif

dn: sn=Jensen,dc=siroe,dc=com
cn: Babs Jensen
CreateTimestamp: 100
objectclass: person
objectclass: top
sn: Jensen
telephoneNumber: 555-5550

dn: sn=Minsky,dc=siroe,dc=com
cn: Pete Minsky
objectclass: person
objectclass: top
sn: Minsky
telephoneNumber: 555-5559

dn: sn=Morris,dc=siroe,dc=com
cn: Ted Morris
CreateTimestamp: 200
objectclass: person
objectclass: top
sn: Morris
telephoneNumber: 555-5558

This output shows the result of the union of the input files:

• The first entry, sn=Jensen, remains unchanged.

• Only the telephone number is modified in the second entry, sn=Minsky.

• The third entry, sn=Morris, is counted as new because it was not present in one.ldif.

• The deleted entry, sn=Rose, is not included, although it is tallied as a change in the entry counts.

Change Files

In order to see how each input relates to the merge result, we can generate the change files. These will contain LDIF update statements showing the difference between each input file and merge result shown in the previous example:

$ mmldif -o merge.ldif -c one.ldif two.ldif

start time Wed Jul 11 12:34:56 2001
entry counts: unchanged=1 changed=2 new=1 total=4
end time Wed Jul 11 12:34:56 2001
differencing took <= 1 second

$ cat one.ldif.delta

dn: sn=Minsky,dc=siroe,dc=com
changetype: modify
delete: createTimestamp
-
replace: telephoneNumber
telephoneNumber: 555-5559
-

dn: sn=Rose,dc=siroe,dc=com
changetype: delete

dn: sn=Morris,dc=siroe,dc=com
changetype: add
cn: Ted Morris
createTimestamp: 200
objectclass: person
objectclass: top
sn: Morris
telephoneNumber: 555-5558

The file two.ldif.delta is also generated but it is empty (zero length) because two.ldif contains all of the most recent modifications between the two input files.

This output shows how to bring the contents of one.ldif up to date with the result of the merge:

• Modify the entry for sn=Minsky by:
  • Deleting the createTimestamp attribute: mmldif removes timestamp attributes from modified entries.

  • Replacing the value of the telephoneNumber attribute.

• Delete the entire entry for sn=Rose.

• Add the entire new entry for sn=Morris.

Supposing that one.ldif represents the contents the directory on host one, port 389, the following command will update those contents so that they are equivalent to merge.ldif:

$ ldapmodify -h one -D "bindDN " -w bindPassword \
             -f one.ldif.delta

This command uses the credentials of the bindDN to access the directory and assumes that user has permission to modify entries. See Chapter 4 "ldapmodify," for more information.