12.2. 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 a single database, or to all databases.
The distribution function itself appears 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 is 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.
    You then need to 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.