
Directory information is divided into naming contexts which are stored in a data store. The data store is the physical location of the naming context. Each data store can hold more than one naming context. A directory server can hold more than one data store.
Quick Reference
Configuring the Data Store
To configure a data store, you must specify the distinguished name of the naming context that identifies the data store, and the name of the directory where the database files reside. Optional configuration information includes:
Creating a Data Store gives step-by-step instructions for creating a new data store. Modifying a Data Store explains how to modify an existing data store.
Renaming the Default Data Store
In your initial configuration, you must specify the distinguished name of the naming context that identifies the data store on the server, and the directory where the data store files are held.
- Click on Data Store in the Sections list to display the Data Store screen.
- Highlight the default data store (o=XYZ, c=US), and choose Modify from the Selected option button.
Alternatively, double-click on the default data store (o=XYZ, c=US).
- Modify the data store suffix to reflect the distinguished name of the naming context that the directory server will store.
If you intend to initialize the NIS service, you must modify the suffix made up of dc elements so that this naming context can contain the NIS domain managed by the server.
If you want the data store to hold more than one naming context, you can specify additional naming suffixes by clicking the More Suffixes button. If necessary, use the Set button to specify the distinguished name. See Using the Distinguished Name Editor.
- Specify the path name to the directory where the data store is to be held.
For a default configuration, you do not need to specify any other information.
For information about creating a data store, see
Creating a Data Store.
Creating a Data Store
- Click on Data Store in the Sections list to display the Data Store screen.
- Select Data Store from the Create option button.
The Create Data Store window is displayed.
- Click on General in the Sections list to display the General screen.
- In the Data Store Suffix field, specify the distinguished name of the naming context stored in this data store.
Either type the desired suffix in the text field or click Set to specify the name using the Distinguished Name Editor.
To specify more suffixes click on the More suffixes button.
- In the DB directory field, specify the path name to the directory where this database is to be stored.
- With the Read-Only Data Store option button, specify if the data store should be read-only.
The default value is No.
- With the Last Modification Attributes option button, specify whether the last modification attributes should be recorded.
When this option is enabled, the creator's DN, a creation timestamp, the modifier's DN, and a modification timestamp are added in the entry. This enables you to search the directory for entries created or modified since a particular date or time. This can be useful if you are synchronizing changes across data stores, or you are using partial replication.
- Specify the cache size limit, in entries and in bytes.
See Caching for details.
The default sizes are 1000 entries and 100 000 bytes.
- Specify the congestion limits.
See Congestion Limits for details.
The default congestion limits are 200 kbytes for critical, 500 kbytes for congested, and 1000 kbytes for back-to-normal.
- Click on Indexes in the Sections list to display the Indexes screen.
- Optionally, you can specify which attributes to index in the database.
See Creating an Index for details.
- Click on Naming Contexts in the Sections list to display the Naming Contexts screen.
- Specify the master and slave subtrees held in this data store.
These are naming contexts that are subtrees or objects within the naming context used to name the data store. If you do not specify any naming contexts, the distinguished name of the data store itself is added to the list of master naming contexts automatically, but it is not displayed until you save the naming contexts information. See Naming Contexts for details.
- Choose Naming Context from the Create option button.
The Add Naming Context screen is displayed.
- Specify the subtree type (subtree or object).
- Specify the DN of the subtree or object in the Suffix field.
- Select the mode from the Mode option button.
- If the naming context is a replica (slave), specify:
- The name of the server from which it is replicated in the Master Hostname field
- The master update DN that dspushd will use when the master initiates the bind to replicate changes.
- Whether or not you want the slave to pull updates from the master. If so select Yes from the Configure pull replication option button and see Creating a Replica for information on how to set the bind parameters.
- Click OK to save the naming context information.
- Click on Replicas in the Sections list to display the Replicas screen.
- Optionally, you can replicate any of the stored naming contexts to a different server.
If you choose to do this you need to create the naming context on the target server following the procedure described in step 13, because the replication procedure does not create it automatically. See Configuring Pull Replication for details.
- Click OK in the Create Data Store window to save the Data Store definition.
- Add a directory entry for the root of the data store.
See Creating a Root Entry for details of how to add an entry to the directory. You cannot add any entries to the data store until this root entry exists.
Creating an Index
- Click Indexes in the Sections list of the Data Store window.
- Specify which attributes should be indexed in the database:
- Select Index from the Create option button.
- Specify the name of the indexed attribute and the index types
Use the Set button to select attributes from a list. You can specify several attributes separated by commas. These indexed attributes will have the same index types.
- Specify the index types with the Indexed on radio buttons.
You can select more than one type. The default setting is Indexed on Equal.
- Click Apply to add the index.
Modifying a Data Store
- Click on Data Store in the Sections list to display the Data Store screen.
- Double-click on the data store you want to modify from the Data Store list.
The modify data store window is displayed. You can modify any part of the data store configuration, except if the data store is not empty you cannot modify a data store suffix.
Backing Up a Data Store
- Click on Data Store in the Sections list to display the Data Store screen.
- Double-click on the data store you want to back up from the Data Store list.
The modify data store window is displayed.
- Select Backup from the Data Store option button.
- Select or create a directory for your backup.
- Click Save.
Restoring a Data Store
- Click on Data Store in the Sections list to display the Data Store screen.
- Double-click on the data store you want to restore from the Data Store list.
The modify data store window is displayed.
- Select Restore from the Data Store option button.
- Select the directory containing the backed up data store that you want to restore.
The default selection is the previous backup directory.
- Click Load.
The directory service is restarted with the restored data store.
Regenerating the Data Store Indexes
Rebuilding the data store attribute indexes every few weeks or whenever large numbers of entries have been deleted will improve performance and free disk space no longer required by the attribute indexes. You need to do this for each data store individually.
Regenerating the indexes for a data store can take several minutes, depending on the number and complexity of the indexes defined. For example, regenerating the default indexes for a data store of 20 000 entries takes approximately 5 minutes.
- Click on Data Store in the Sections list to display the Data Store screen.
- Double-click on the data store for which you want to rebuild the indexes.
The modify data store window is displayed.
- Select Update Indexes from the Data Store option button.
Creating a Root Entry
You must create a root entry for a data store before you can add entries to it. The root entry is the top entry of the tree held by the data store. It identifies the data store.
To create the root entry, you must create a simple LDIF file containing the entry information, and add it to the database using the ldapadd command. The following procedure shows how to create the root entry for the XYZ corporation.
- Create an LDIF file called root-file that contains:
dn: o=XYZ, c=US
objectClass: organization
The LDIF file format is described in detail in the ldif(4) manpage.
- Add this file using ldapadd:
prompt% ldapadd -D "cn=admin,o=XYZ,c=US" -w secret -f root-file
where:
- -D introduces the distinguished name of the data store administrator
- -w introduces the administrator password
- -f introduces the file holding the information to add to the database.
The ldapadd command is described in detail in the ldapmodify(1) manpage.
The root entry now exists.
Indexing
A data store can contain a number of attribute indexes to help optimize the speed of access to directory information. An attribute index is a list of entries containing a given attribute or attribute value. You can index attributes using any of the following matching rules:
- Equality - Optimizes direct access to entries where an exact attribute value is supplied.
- Presence - Optimizes searches with filters specifying the presence of an attribute but no specific value (cn=*, for example).
- Substring - Optimizes searches with filters containing a partially-specified attribute value (cn=ada*, for example). Substring indexing uses the first three letters of an attribute.
- Approximate - Optimizes searches with approximate match filters. The method used in approximate indexing is to discard vowels.
In a data store having the default characteristics, the following attributes are indexed:
- commonName, surname, mail, mailHost, and givenName are indexed by presence, equality, approximate match and substring match
- uid is indexed by presence and equality
- preferredRfc822Recipient, rfc822Mailbox, cCMailAddress, pROFSAddresses, mSMailAddresses are indexed by presence and equality
The advantage of indexing is that it optimizes access for indexed attributes. The disadvantages are that it uses more disk space, and that adding and modifying entries takes longer.
When you add or modify an entry after an index has been created, the index is automatically updated. However, if you create a new index and the data store already contains entries, those entries are not automatically included in the index. Indexes are not automatically updated when entries are removed from the directory, so the size of the index files does not reduce as entries are removed.
To update all the indexes defined in a data store, choose Update Indexes from the Data Store menu of the data store window. See Regenerating the Data Store Indexes. Regenerating the indexes for a data store can take several minutes, depending on the number and complexity of the indexes defined. For example, regenerating the default indexes for a data store of 20,000 entries takes approximately five minutes.
Congestion Limits
Congestion limits ensure that the directory does not become overloaded, by preventing new operations from starting when there are insufficient resources.
- When the available disk space reaches the congested limit, add operations are no longer permitted, though modify, modify RDN (modrdn), search, read, and delete operations are allowed. The default limit is 500 Kbytes.
- When the database reaches the critical limit, only search, read, and delete operations are allowed, and add, modify, and modrdn operations are not permitted. The default limit is 200 kbytes.
- The restrictions remain in force until the remaining disk space becomes greater than the back-to-normal limit. The default limit is 1000 kbytes.
Threshold values are given in kbytes free on the disk holding the data store. The default location for the data store is /var/opt/SUNWconn/ldap/dbm.
Caching
As information is retrieved from the directory it is saved in the cache. When the cache is full, the oldest entry is discarded to make room for new information. Retrieving information from the cache is faster than retrieving entries from the database, but a large cache occupies more memory.
Default values for cache size and number of entries are 100,000 bytes and 5000 entries.
Naming Contexts
A data store can contain up to four naming contexts. The distinguished names of these naming contexts are used to identify the data store. In the Admin Console, the naming contexts of the data store are shown in the Data Store Suffix fields in the data store General section.
The distinguished name of a naming context, or of a subtree of the naming context corresponds to the base DN you specify when you perform a directory operation such as a search, or when you configure an LDAP client application.
You can specify a DN that conforms to the OSI tree structure (for example o=XYZ, c=US), or a DN that reflects your organization's DNS naming structure, through a sequence of domain components (for example dc=XYZ, dc=com).
A data store can contain a mixture of master and replica (slave) naming contexts, some or all of which can be replicated to other servers.
About Replication
Information from a master naming context is propagated to a replica by the dspushd daemon. This information can also be pulled from the master server by the dspulld daemon running on the replica server. The dspushd and dspulld daemons use the LDAP protocol to update a replica naming context.
A master naming context for which a replica is defined maintains a replication log. Each time the master naming context is updated, the transaction is recorded in the replication log. When the dspushd daemon next runs, it reads the replication log and sends the change to the server that holds the replica naming context. The dsservd server handles update requests from dspushd in the same way that it handles all requests, using the information supplied in the bind request to set the access level granted to dspushd requests. To guarantee that all replication updates are completed, dspushd must bind with the DN defined when the replica naming context was configured. If a different DN is used, write access for all entries may not be granted.
A replica data store always has a referral pointing to the master data store. If a replica server receives a request to modify an entry, it returns a referral to the client, indicating the master server to be contacted. Once the modification has been made in the master naming context, the change is sent to the replica naming context the next time the dspushd daemon runs.
Any naming context held in the data store, including replica naming contexts, can be replicated to another server.
See Setting Up Replication for more information.
Setting Up Replication
Before you start configuring replication on master servers and slave servers, you must make the following decisions:
- What information you want to replicate
- Which server will hold the master copy
- Which servers will hold replicas
- Will the master server push updates to all slaves, or will replica servers individually pull updates from the master
In defining the information you want to replicate, you specify:
- The entries you want to replicate
- The attributes you want to replicate
To select the entries to replicate, you can:
- Provide the DN of a subtree: all the entries in the subtree are replicated
- Specify an individual entry (object)
To select the attributes to replicate, you can:
- Specify all attributes
- Include or exclude certain attributes from the replication
You can also define a replication synchronization schedule. This schedule determines when all updates are sent to replicas. There are three types of synchronization:
- Immediate, which means that the replication daemon, dspushd, runs permanently and sends updates to the replica immediately when modifications are made in the master.
- Delayed, which means that modifications are logged until the next time dspushd runs. If you select Delayed synchronization, specify a schedule for dspushd.
- Disabled, which means that modifications are not automatically sent to the replica.
You can use the Send updates now button to send any outstanding modification immediately to a replica. Setting the synchronization type to Disabled and using the Send updates now button to initiate replication updates manually can be useful where the update traffic is unpredictable, or where the remote server is connected by a dial-up line.
You must configure replication for both the Master and the Slave servers.
- On the Master server you must:
- On the Slave server you must:
Both the master and the slave must be configured correctly for replication to work correctly.
After you have configured a replica naming context, the master and replica data stores must be in the same state, so that the replica can receive replication updates from the master. If the master data store already contains entries, the Admin Console displays a dialog box giving you the option of populating the replica. Use this facility to populate the replica automatically with the entries that the master contains.
Note - Although you can start the replication process from the Admin Console, the Admin Console does not control the process and does not display error messages. You need to check the replication log file, dspushd.log or dspulld.log, to ensure that the replication process has completed successfully.
Creating Replicas
- Select Replicas in the Sections list of the Create or Modify Data Store window.
- Select Replica from the Create option button.
The Add Replica dialog box is displayed.
- Specify the type of replica (subtree or object) with the Subtree option button.
- In the text field, specify the distinguished name of the subtree or object to be replicated, or click the Set button to use the DN editor.
To create a replica of the whole data store, specify the DN of the naming context used to identify the data store.
- Select the attributes to be replicated.
You can specify that all attributes are replicated, or you can exclude or include certain attributes. If you choose Exclude or Include from the Attributes option button, you must specify the particular attributes you want to exclude or include in the replica.
- In the Host text field, type the name of the target host (replica server) where the replica will be stored.
- In the Port text field, type the port number of the dsservd server on the replica server to be used by the replication daemon, dspushd.
- In the Update DN field, type the distinguished name that the master will supply when requesting authentication.
Alternatively click on Set to use the DN editor.
- In the Password field, type the password that the master will supply when requesting authentication.
- Specify the bind method, security mode, and SSL key package if you select SSL or TLS as the security mode.
- Click OK to save the replica definition and exit from the Add Replica window.
- Optionally, you can set up a replication synchronization schedule.
Creating a Replication Synchronization Schedule
There are three types of replication synchronization:
- Immediate, which means that the replication daemon, dspushd, runs permanently and sends updates to the replica immediately when modifications are made in the master.
- Delayed, which means that modifications are logged until the next time dspushd runs. If you select Delayed synchronization, specify a schedule for dspushd.
- Disabled, which means that modifications are not automatically sent to the replica.
The synchronization schedule is defined in the Data Store section of the main window. The synchronization schedule applies to every master replica.
To specify a synchronization schedule:
- Click on Data Store in the Sections list to display the Data Store screen.
- In the Data Store section of the main page, select the type of replication synchronization you want.
- Click Apply to save your changes.
Alternatively, you can use the Send updates now button to send any outstanding modification immediately to a replica. Setting the synchronization type to Disabled and using the Send updates now button to initiate replication updates manually can be useful where the update traffic is unpredictable, or where the remote server is connected by a dial-up line.
Configuring Pull Replication
- In the Add Data Store or Modify Data Store window choose Naming Context from the Create option button.
The Add Naming Context screen is displayed.
- Specify the subtree type (subtree or object).
- Specify the DN of the subtree or object in the Suffix field.
- Select Slave from the Mode option button.
- Specify the name of the server from which it is replicated in the Master Hostname field
- Specify the master update DN that dspushd will use when the master initiates the bind to replicate changes.
- Select Yes from the Configure pull replication option button.
- Select the attributes to be replicated.
You can specify that all attributes are replicated, or you can exclude or include certain attributes. If you choose Exclude or Include from the Attributes option button, you must specify the particular attributes you want to exclude or include in the replica.
- In the Bind to master as text field, type the distinguished name that the slave server will supply when requesting authentication.
Alternatively click on Set to use the DN editor.
- In the Password field, type the password that the slave server will supply when requesting authentication.
- Specify the bind method, security mode, and SSL key package if you select SSL or TLS as the security mode.
- Click OK to save your changes and dismiss the Add Naming Context window.
In the Data Store section of the Admin Console main window, an extra set of controls is displayed. These controls enable you to set up a synchronization schedule on the slave server, and to start replication at any time from the slave.
Creating a Pull Replication Synchronization Schedule
The synchronization schedule is defined in the Data Store section of the main window. The synchronization schedule applies to every slave replica.
- Click on Data Store in the Sections list to display the Data Store screen.
- From the Request updates from master option button select Enabled.
Day and Time option buttons are displayed.
- Select the day and time at which you want replication to occur.
- Click Apply in the Admin Console main window to save your changes.
Alternatively, to start replication at any time from a slave server:
- Click on Data Store in the Sections list to display the Data Store screen.
- Select the replica that you want to synchronize with the master.
- Click on the Request updates now button.