Chapter 12

Using the Custom Distribution Logic

---

The distribution plug-in provided with Red Hat Directory Server (Directory Server) distributes a flat namespace, allowing you to associate several databases with a single suffix.

This chapter contains the following sections:

• About Distributing Flat Namespaces (page 155)
• Creating a Distribution Function (page 156)
• Adding the Distribution Function to Your Directory (page 158)
• Using the Distribution Logic Examples (page 161)
• Custom Distribution Checklist (page 162)

About Distributing Flat Namespaces

You can distribute entries located in a flat tree structure. Imagine you administer the directory for example.com, an ISP. The directory for example.com contains the following entries distributed in a flat tree structure:

Because the number of users is too large, you decide to distribute the entries according to the first letter of each user's last name, assigning each letter to a separate database. To do this, you need to create your own distribution function. Your function determines how each operation received by the ou=users suffix is routed to the database containing the information for a particular user.

Once you have distributed entries, you cannot redistribute them. The following restrictions apply:

• You cannot change your distribution function once you have deployed entry distribution.
• You cannot use the ldapmodrdn operation to rename entries if the modification would cause them to be distributed into a different database.
• You cannot use the ldapmodify operation to change entries if that would cause them to be distributed into a different database.

For example, if you distribute entries according to their telephone number, you cannot change the telephone number attribute of an entry without breaking entry distribution.

• Once you have deployed entry distribution you cannot add more databases.

Creating a Distribution Function

Using the distribution function, you can set a suffix to have any number of database pointers. This allows you to distribute requests made to a suffix over a number of databases.

For example, the entry for the dc=example,dc=com suffix appears as follows:

dn: cn="dc=example,dc=com", cn=mapping tree, cn=config

objectclass: top

objectclass: extensibleObject

nsslapd-backend: example.com database A-M

nsslapd-backend: example.com database N-Z
 

When the suffix receives a request from a client, it uses the distribution function to determine which database services the operation. The plug-in consists of a function and a library. This function and library are part of the entry for the dc=example,dc=com suffix and appear as follows:

nsslapd-distribution-plugin: /path/to/a/shared/library

nsslapd-distribution-funct: distribution-function-name
 

Each time the server gets a request for a suffix that contains the distribution function, the function is called. The function then decides which database (backend) processes the request. The decision made by the function is based on some piece of information present in the pblock at the time of the request, such as the entry DN, a hash function, the time of day, or the type of operation.

For search operations, the function can forward the operation to just one database or to all databases.

The distribution function itself looks as follows:

int distribution_function(Slapi_PBlock *pb, Slapi_DN * dn, 
Slapi_Backend **mtn_be, int be_count, Slapi_DN * node_dn);
 

The following table lists the parameters taken by the distribution function:

Table 12-1 Distribution Function Parameters  

Parameter Name	Description
pb	The pblock of the plug-in which contains all of the information about the operations in progress. This structure is the same as that for other plug-ins; for example, operation type, IP address of the client, target DN, search filter, bind credentials, etc.
mtn_be	A table of size be_count containing the list of databases defined for the suffix. If a database is defined in the suffix entry but not available, the corresponding pointer in the table will be set to NULL.
node_dn	The suffix containing the distribution function.
be_count	The size of the table that contains the list of databases involved in the distribution of entries.
int	The row number of the database in the mtn_be table. For search operations, you can return a value of MTN_ALL_BACKENDS to specify that all databases must be searched.

The root entry for the suffix must be present in each database in order for the distribution function to work properly. For example, for the suffix dc=example,dc=com, you need to create an entry corresponding to dc=example,dc=com in each database involved in the distribution.

You can create the root entry in two ways:

• Import the same LDIF file into each database using the ldif2db command-line utility.

This LDIF file should contain the root entry as well as data that you want to distribute across the databases. Only the data determined by the distribution function to be appropriate for each database will be imported.

• Create an LDIF file that contains the root entry. You can do this by exporting the root entry (for example, dc=example,dc=com) in LDIF format using the ldapsearch command-line utility.

Then, import the LDIF file into each database using the ldif2db command-line utility. If you have three databases for a single suffix, you need to import the suffix entry three times.

When a subtree search is performed above a suffix that is distributed among several databases, the search will be performed on all databases. This means that the shared suffix entry that you create on each database (in the example, dc=example,dc=com) can be returned multiple times.

Adding the Distribution Function to Your Directory

To declare the distribution function to your directory, you need to add multiple databases to a single suffix and then declare the distribution function in the suffix.

These procedures assume you have already created a suffix and associated it with a single database. For the procedure on creating a new suffix and database, refer to chapter 2, "Creating Directory Entries," in the Red Hat Directory Server Administrator's Guide.

Note

You need to add all of the databases required for your distribution algorithm before you deploy entry distribution. You cannot add more databases later without changing the algorithm. Whenever you install new distribution functions, be sure to restart the Directory Server. Otherwise, the new libraries will not get loaded properly.

Adding Multiple Databases to a Single Suffix

The following procedures describe adding multiple databases to a suffix using the Console and the command-line.

Using the Console

1. In the Directory Server Console, select the Configuration tab.
2. Expand the Data tree, and select the suffix to which you want to add another database.
3. From the Object menu, select New Database. You can also right click the suffix and select New Database from the menu.

The Create New Database dialog box appears.

4. Enter the name of the new database in the "Database Name" field.
5. In the "Create database in" field, enter the path to the location where the data for your new database will be stored.

You can also click Browse to locate the path on your local machine.

6. Click OK to save your changes.

A warning message displays telling you to declare a distribution function in the suffix. The next procedure describes how to declare the function in a suffix.

From the Command-Line

Use the ldapmodify command-line utility to add another database to your directory configuration file. The database configuration information is stored in the cn=ldbm database,cn=plugins,cn=config entry.

For example, to add a new database to the server example1, you add a new entry to the configuration file by performing an ldapmodify as follows:

ldapmodify -a -h example1 -p 389 -D "cn=directory manager" -w 
secret
 

The ldapmodify utility binds to the server and prepares it to add an entry to the configuration file.

Next, you create the entry for the new database as follows:

dn: cn=Data2,cn=ldbm database,cn=plugins,cn=config

objectclass: extensibleObject

objectclass: nsBackendInstance

nsslapd-suffix: ou=people,dc=example,dc=com
 

The entry added corresponds to a database named Data2 that contains the data for the root suffix ou=people,dc=example,dc=com.

The database name, given in the DN attribute, must correspond with one of the values in the nsslapd-backend attribute of the suffix entry.

Adding Distribution Logic to a Suffix

The distribution logic is a function declared in a suffix. This function is called for every operation reaching this suffix, including the subtree search operations that start above the suffix. You can add a distribution function to a suffix using both the Console and the command-line.

Using the Console

1. In the Directory Server Console, select the Configuration tab.
2. Expand the Data tree, and select the suffix to which you want to add the distribution function.
3. Select the Databases tab in the right pane.
4. Click Add to add new databases to the suffix from the Database List.
5. Enter the path to the distribution library in the Distribution Library field, or click Browse to locate the library on your local machine.
6. Enter the name of your distribution function in the Function Name field.
7. Click Save to save your changes.

From the Command-Line

Use the ldapmodify command-line utility to add the following lines to the suffix entry:

nsslapd-distribution-plugin:  path_to_shared_library 

nsslapd-distribution-funct:  distribution_function_name
 

The first line provides the name of the library that your plug-in uses. The second line provides the name of the distribution function itself.

Using the Distribution Logic Examples

The directory provides three distribution logic examples. The examples illustrate the following:

• Distributing entries based on the first letter of their RDN (alpha_distribution).

The example uses as many databases as you like to contain the data. For example, if you create 3 databases for a single suffix, entries starting with the letters A-I to database 0, entries starting with the letters J-R go to database 1, and entries starting with the letters S-Z go to database 2. If you create 26 databases, each database would receive the entries for one letter of the alphabet.

• Distributing entries based on a simple hash algorithm (hash_distribution).

In this example, entries are randomly distributed using a hash algorithm on the RDN to compute the database to which the entry will be written.

• Chaining entries to a read-write replica from a read-only replica (chaining_distribution).

Usually the directory returns a referral to clients making update requests to a read-only replica. This example uses a distribution function on a suffix that contains both a read-only database and a database link. When the read-only database receives an update request, it forwards the request using the database link to a read-write database. The database link needs to be configured to chain on update. For information on configuring database links, refer to chapter 2, "Creating Directory Entries," in the Red Hat Directory Server Administrator's Guide.

The following directory in your Directory Server installation contains the uncompiled C code examples:

server_root /plugins/slapd/slapi/examples/distb/
 

This directory contains a file named distrib.c, which contains three example functions (alpha_distribution, hash_distribution, and chaining_distribution) and a Makefile for compiling them.

Once you have compiled the source code, you will have the following files:

HP-UX	distrib-plugin.sl
Solaris, Linux	distrib-plugin.so

Imagine you want to use the hash distribution function on a Solaris machine. First create a suffix. Then create several databases under that suffix. Next, import the suffix entry to each of the databases you created. Finally, add the following lines to the suffix:

nsslapd-distribution-plugin: /plugin/distrib-plugin.so

nsslapd-distribution-funct: hash_distribution
 

Custom Distribution Checklist

In summary, the following steps are involved in adding the distribution function to your directory:

• Create the distribution function.
• Create a suffix.
• Add as many databases to the suffix as required by your distribution algorithm.
• Declare the distribution function in the suffix. You must specify the library path and the function name.
• Import data to the databases. If you do not import data, you need to import the root entry to each database.