|Plug-in Programmerís Guide
Red Hat Directory Server
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.
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:
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:
- 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.
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
- In the Directory Server Console, select the Configuration tab.
- Expand the Data tree, and select the suffix to which you want to add another database.
- From the Object menu, select New Database. You can also right click the suffix and select New Database from the menu.
- Enter the name of the new database in the "Database Name" field.
- In the "Create database in" field, enter the path to the location where the data for your new database will be stored.
- 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
- In the Directory Server Console, select the Configuration tab.
- Expand the Data tree, and select the suffix to which you want to add the distribution function.
- Select the Databases tab in the right pane.
- Click Add to add new databases to the suffix from the Database List.
- Enter the path to the distribution library in the Distribution Library field, or click Browse to locate the library on your local machine.
- Enter the name of your distribution function in the Function Name field.
- 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:
- 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.
- 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.
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:
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.