Configuring Fractional Replication

Fractional replication enables you to replicate specific parts of directory data to other replicas in the topology. This feature is particularly useful in the following scenarios:

• Limited disk space. Restricting the data that is replicated can significantly cut down on the amount of disk space that is required on certain replicas, particularly if you restrict the replication of attributes such as jpeg photos, which represent large data volumes.

• Security concerns. Certain data, such as user passwords, might be sensitive and not required on certain replicas, especially if there is a risk of inappropriate access on these replicas.

This section describes how to configure fractional replication on one or more servers in a topology. For information about the architecture of the fractional replication mechanism, see Fractional Replication in Sun OpenDS Standard Edition 2.2 Architectural Reference.

Fractional replication is configured on the directory server that receives the partial data, and is attribute-based. Consider the following scenario:

Fractional replication is configured on Directory Server B. An ldapmodify operation is sent to Directory Server A. The entire operation is forwarded to Replication Server 1, then to Replication Server 2, then to Directory Server B. When the operation is replayed on Directory Server B, certain attributes from the operation are filtered out, based on that server's fractional configuration.

Fractional replicas remain writable directly from client applications. However, if an add or modify operation that includes certain “forbidden attributes” is attempted on a fractional replica, the operation is denied and the server returns an “Unwilling to perform” error.

Fractional replication can be configured in one of two modes:

• Exclusive mode. In this mode, the multi-valued fractional-exclude attribute is used to filter out the specified attributes from an incoming LDAP add or modify operation.

  Excluded attributes must be optional attributes of an object class.

• Inclusive mode. In this mode, the multi-valued fractional-include attribute is used to filter in only the specified attributes from an incoming LDAP add or modify operation.

  All other attributes (except for those that are mandatory in the object class) are removed from the change that is replayed on the server.

The two modes are mutually exclusive, that is, you can include only one of these attributes in a domain configuration.

Fractional replication is configured per replicated domain (see Retrieving the Replication Domain Name). A fractional domain implies that certain attributes are entirely absent from the domain. These attributes are filtered out at operation replay time but are also absent from the existing data in the domain.

To ensure coherency of the data across a replicated topology, it is necessary to identify whether a particular data set is fractional. The configuration of a new fractional domain therefore implies specific steps to ensure that the domain is free of forbidden attributes, and recognizable as a fractional domain. For more information, see To Configure and Initialize a Fractional Domain.

Use the dsconfig command to configure fractional replication in a domain, as follows.

To Configure Exclusive Fractional Replication

The following example configures a replica to exclude the photo and jpegPhoto attributes from any creation or modification of an entry whose object class is inetOrgPerson.

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X \
  set-replication-domain-prop --provider-name "Multimaster Synchronization" \
  --domain-name "dc=example,dc=com (domain 10233)" \
  --set fractional-exclude:inetOrgPerson:photo,jpegPhoto
 

Object classes and attributes can be specified by their names, or by their OIDs, so the following example has the same effect as the previous example:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X \
  set-replication-domain-prop --provider-name "Multimaster Synchronization" \
  --domain-name "dc=example,dc=com (domain 10233)" \
  --set fractional-exclude:2.16.840.1.113730.3.2.2:0.9.2342.19200300.100.1.7, \
  0.9.2342.19200300.100.1.60

If you use a mix of object class or attribute names and OIDs, both values are added. For example, the following command adds both the attribute name and its OID to the list of excluded attributes:

$ dsconfig set-replication-domain-prop ... 
  --set fractional-exclude:*:jpegPhoto,*:0.9.2342.19200300.100.1.60

If you wanted to remove this attribute from the list, you would need to remove both the attribute name and the OID.

To specify that the photo and jpegPhoto attributes should be removed from any creation or modification of any entry (regardless of its object class), use an asterisk in place of the object class. For example:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X \
  set-replication-domain-prop --provider-name "Multimaster Synchronization" \
  --domain-name "dc=example,dc=com (domain 10233)" \
  --set fractional-exclude:*:photo,jpegPhoto
 

To Configure Inclusive Fractional Replication

The following example configures a replica to include only the uid and employeeNumber attributes from any creation or modification of an entry whose object class is inetOrgPerson. All other attributes are ignored in the modification, except those that are mandatory for the object class.

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X \
  set-replication-domain-prop --provider-name "Multimaster Synchronization" \
  --domain-name "dc=example,dc=com (domain 10233)" \
  --set fractional-include:inetOrgPerson:uid,employeeNumber

Object classes and attributes can be specified by their names, or by their OIDs, so the following example has the same effect as the previous example:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X \
  set-replication-domain-prop --provider-name "Multimaster Synchronization" \
  --domain-name "dc=example,dc=com (domain 10233)" \
  --set fractional-include:2.16.840.1.113730.3.2.2:0.9.2342.19200300.100.1.1, \
  2.16.840.1.113730.3.1.3

If you use a mix of object class or attribute names and OIDs, both values are added. For example, the following command adds both the attribute name and its OID to the list of included attributes:

$ dsconfig set-replication-domain-prop ... 
  --set fractional-include:*:jpegPhoto,*:0.9.2342.19200300.100.1.60

If you wanted to remove this attribute from the list, you would need to remove both the attribute name and the OID.

To specify that a particular attribute should be included in the creation or modification of any entry (regardless of its object class), use an asterisk in place of the object class. The following example includes only the description attribute in a creation or modification operation on any entry.

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X \
  set-replication-domain-prop --provider-name "Multimaster Synchronization" \
  --domain-name "dc=example,dc=com (domain 10233)" \
  --set fractional-include:*:description 

To Configure and Initialize a Fractional Domain

The following steps are required when you initialize a new fractional domain:

1. Configure exclusive or inclusive fractional replication, as described in the previous two sections.

   At this point, the domain obtains a bad generation ID status. For more information, see Replication Status in Sun OpenDS Standard Edition 2.2 Architectural Reference.

   This means that all modifications on the domain are blocked until the data is synchronized with the rest of the topology.

2. Import a new data set from one of the other servers in the topology.

   The new data set can be imported online, by using dsreplication initialize or by using import-ldif in online or offline mode. The server from which you import the data must either be an entire replica (that is, not a fractional replica) or must have the same fractional configuration as the server to which you are importing the data. During the import, all entries will be filtered with the fractional configuration set up in the previous step.

   For information about how to import a data set, see Initializing a Single Replicated Server and Importing and Exporting Data.

3. After the data import, the domain returns to normal status.

   For more information, see Replication Status in Sun OpenDS Standard Edition 2.2 Architectural Reference.

   The domain is now able to accept new entries from local LDAP operations, or synchronization operations with other servers in the topology. The data in the domain is free of any “forbidden” attributes.