Managing Directory Server Databases
he directory managed by your directory server is contained in some kind of a database. This chapter describes the procedures you need to know to manage your database. This chapter includes the following topics:
- Managing Databases Using LDIF
- Backing Up and Restoring Your Database
- Managing Database Parameters
- Managing SuiteSpot Integration
- Managing the Referential Integrity Plug-in
- Managing Database Transaction Logging
Managing Databases Using LDIF
You can use the LDAP Data Interchange Format (LDIF) to import and export database entries into and out of the directory server. You can also back up your databases using LDIF. The following sections describe: For a description of the LDIF language, see Chapter 2, "LDAP Data Interchange Format."
Importing LDIF Using the Server Manager
To use the server manager to import the LDIF file into a directory server database, do the following:
Warning
This process will overwrite your existing database, if any.
- Make sure your directory server is shut down.
- From the server manager go to Database Management | Import.
The database is created and placed in the database directory for you. Indexes are also created based on the Attribute values shown in Database Management| Attribute Indexing. For more information on indexes and index creation, refer to Chapter 7, "Managing Indexes." You should use the server manager to import an LDIF file only if the LDIF file contains a relatively small number of directory entries (less than 1,000).
Importing LDIF from the Command Line
You can convert your LDIF file to a ldbm database file using the ns-slapd command-line utility. This utility will create the database in the location specified in the directory parameter in your slapd.conf file. ldif2db also creates the index files that are specified in the slapd.conf Attribute to be Indexed parameters.
The database parameter is described on page 348. The Attribute to be Indexed parameter is described on page 347.
For information on where you can find the command-line utilities in your directory server installation, see "Finding the Command-Line Utilities" on page 29.
To perform the LDIF to LDBM conversion, do the following:
- Make sure the directory server is not running.
- cd to
<NSHOME>/slapd-<serverID>/db. The directory server database must be stored in this directory. - cd to
<NSHOME>/bin/slapd/server - Run the
ns-slapdutility with theldif2dbkeyword as follows:
ns-slapd ldif2db -i <ldif_file> -f <slapd.conf>
ldif_file> is the name of the file containing the LDIF to be
converted and <slapd.conf> is the location of your configuration file.
You can find a demo LDIF file under
<NSHOME>/slapd-<serverID>/ldif. The slapd.conf file is under
<NSHOME>/slapd-<serverID>/config.
ns-slapd Parameters Used for LDIF Imports
The following ldif2db parameters are necessary to successfully complete an LDIF file conversion:
-i
Specifies the LDIF file to be converted. This parameter is required.
-f
Specifies the
slapd.conf configuration file to use for the conversion process.
This parameter is required. For information on where to find directory server
configuration files, see "Finding the Configuration Files" on page 31.
-d
Specifies the debug level to use during runtime. This parameter is optional. Debug levels are defined in "Log Level" on page 323.
-n
Specifies the database in your
slapd.conf file for which the conversion is
performed. If this parameter is not specified, then the first database defined in
your slapd.conf file is used.
-N
Turns off checking of duplicate entries when importing the LDIF file to the
directory. Using this parameter will reduce the time required to create your
database from LDIF, but it can result in unpredictable search results if your
LDIF file contains duplicate entries. Use this parameter only if you are sure that
your LDIF does not contain duplicate entries. This parameter must be specified
last on the command line call.
LDIF to Database Example
ns-slapd ldif2db -i /usr/ns-home/slapd-<serverID>/ldif/demo.ldif -f /usr/ns-home/slapd-<serverID>/config/slapd.conf
Converting Databases to LDIF
You can convert your database to LDIF either by using the server manager, or by using thedb2ldif command-line utility. Converting your database to LDIF can be useful if you want to:
- back up your database
- copy your database to another directory server
- export your database to another application
- add an index setting for an attribute currently existing in your database
Converting to LDIF Using the Server Manager
To convert your database to LDIF from the server manager:- Make sure your server is shut down.
- From the server manager go to Database Management | Export.
For example, a file created on Wednesday August 21, 1996 at 8:43:23 p.m.
would be named:
1996_08_21_94323
Wed_Aug_21_20_43_23_1996
Converting to LDIF Using ns-slapd
You can dump your database to LDIF using the ns-slapd command-line utility. For information on where you can find the command-line utilities in your directory server installation, see "Finding the Command-Line Utilities" on page 29.
To dump your database to LDIF, do the following:
By default, the directory server stores the database in:ns-slapd db2ldif -nid2entry.dbb> output.ldif
NSHOME/slapd/server/db/id2entry.dbb
ns-slapd Parameters for Exporting Databases
-
-n
-
Specifies that entry IDs are not to be printed in the LDIF output. The entry IDs
are necessary only if the
db2ldif output is to be used as input to
ldif2index.
-
-d
db2ldif runtime. This parameter is optional. Debug levels are defined in "Log Level" on page 323.
-f
Specifies the
slapd.conf configuration file to use for the conversion process.
For information on where to find directory server configuration files, see
"Finding the Configuration Files" on page 31.
db2ldif Example
ns-slapd db2ldif -n id2entry.dbb > out.ldif
Deleting LDIF Files
By default, the server manager places LDIF files that it creates in this directory:<NSHOME>/slapd-<serverID>/ldif
You can either delete the files from that directory directly from the command line, or you can delete them using the server manager. To use the server manager to delete LDIF files located in the default directory:
-
Warning
-
This delete takes effect immediately. There is no confirmation prompt and there
is no undo.
- From the server manager go to Database Management | Delete Exports.
- Click the Delete button next to the file you want to delete.
Backing Up and Restoring Your Database
You can back up and restore your database from the server manager. To do this, you can either use the LDIF conversion built into the server manager or you can copy your database directly to a backup directory.
Note
When backing up and restoring your database using LDIF, you must shut down
your server. However, the other methods described in this section allow you to
perform these database maintenance operations while the server is running.
Converting your database to and from LDIF is described in "Importing LDIF Using the Server Manager" on page 60 and "Converting Databases to LDIF" on page 62. This section describes:
- Backing Up Your Database
- Restoring Your Database
- Deleting Database Backups
- Restoring Databases That Include Replicated Entries
Backing Up Your Database
When you back up your database from the server manager, you are copying the entire database and associated index files to a backup location. By default, all backup files are placed in:
<NSHOME>/slapd-<serverID>/bak/<backup_name>
where <backup_name> is a directory given the name of the backup. By default, the backup name identifies the time and date when the backup was created. Both the default backup file location and filename are configurable.
To create a backup, do the following:
- From the server manager go to Database Management | Backup.
- Click OK.
Do not specify a full pathname in this field; the name you enter will be
created as a subdirectory beneath the backup directory.
Restoring Your Database
If you have somehow corrupted your database, you can restore from a previously generated backup using the server manager. This process consists of copying the database and associated index files from the backup location to the database directory, which is always located at:
<NSHOME>/slapd-<serverID>/db
-
Warning
-
Restoring your database overwrites your existing database files, if any.
-
To restore your database from a previously created backup:
- Make sure the directory server is not running.
- From the server manager go to Database Management | Restore.
Deleting Database Backups
You can delete database backups from the server manager, as long as those backups are kept in directories below:
<NSHOME>/slapd-<serverID>/bak
-
Warning
-
This delete takes effect immediately. There is no confirmation prompt and there
is no undo.
-
To delete your database backups, do the following:
- From the server manager go to Database Management | Delete Backups.
- Click the Delete button next to the backup you want to delete.
Restoring Databases That Include Replicated Entries
If you are restoring a database that is supplying entries to other servers, then all
of your consumer servers must be reinitialized. A message will be logged to the
consumer servers' log files indicating that reinitialization is required. If you
want reinitialization to occur automatically, you can modify the ORCauto
parameter.
If you are restoring a database containing data consumed from a supplier server, then one of two situations can occur:
- Change log entries have not yet expired on the supplier server. If change log entries have not expired on the supplier server since the local database backup was taken, then you can simply restore the local consumer and continue with normal operations. This situation is likely to occur only if the backup was taken within a period of time that is shorter than the value you have set for the Max Changelog Age parameter.
- Change log entries have expired on the supplier server since the time of the local backup. In this case, the consumer server will automatically be reinitialized
Managing Database Parameters
Using the server manager Database Management | Database Settings form, you can manage your database Read-only and Suffix parameters. This section tells you how to use the Database Settings form. Specifically, this section describes:
Placing Your Database in Read-Only Mode
You must put your database in read-only mode if you are manually initializing a consumer. For information on manually initializing a consumer, see "Online Consumer Creation" on page 259. For general information on consumer initialization, see "Initializing Consumers" on page 257.
When your database is in read-only mode, your slapd.conf Read-only parameter is set to true.
Note
While your database is in read-only mode, you cannot create, modify, or delete
any entries.
To place your database into read-only mode, do the following:
- From the server manager, go to Database Management | Database Settings.
- Select Yes for DB is Read-Only.
- Stop and then restart your directory server.
Setting Suffixes for Your Database
Your directory server can simultaneously manage many different directories. Each directory is represented by a suffix, and each suffix corresponds to the root (or topmost) entry in the directory. When the directory server receives a directory request, the server checks its list of suffixes against the request to see if the server is managing the directory that the client wants to access. If the directory request does not match the directories that the server is managing, then the server sends the client a referral, if one has been configured. If a referral has not been configured, an error is returned.
Your Netscape Directory Server always uses multiple suffixes. However, most of these are used only for internal purposes, and only one corresponds to the primary directory that you are using the server to manage (such as o=Airius.com). Other suffixes correspond to directory trees used internally by the server (such as the machine data area directory, or the change log).
You can add and delete suffixes for your database. If you delete an existing suffix, then LDAP clients will not be able to access the entries represented by that suffix.
For information on the Suffix parameter, see "Suffix" on page 342. For more information on managing the Root DN parameter, see "Managing the Root DN" on page 230.
- Go to Database Management | Database Settings.
- Enter the new suffix to the blank Suffix field.
- Click OK.
- Stop and then restart your directory server.
If the suffix value contains a comma, you must precede the comma with a
backslash (\). For example, to add Airius Bolivia, S.A. as a suffix, you
would enter
Airius Bolivia \, S.A. in the Suffix field.
To delete a suffix from your server:
- From the server manager, go to Database Management | Database Settings.
- Delete the suffix from the Suffix field.
- Stop and then restart your directory server.
Managing SuiteSpot Integration
Note
The following discussion assumes that you are familiar with your 3.x
administration server, that you are aware of how the administration server is
managing users and groups, and you understand the how distributed
administration works in you administration server. If you are not familiar with
these concepts, please read Managing Netscape Servers before continuing with
this discussion.
All Netscape servers that run under the SuiteSpot 3.x administration server can use a directory server to manage user and group information. To do this, some initial directory setup is required that allows the 3.x administration server to bind to the directory, and then do directory management activities such as create and delete user accounts, or change user attributes.
At a minimum, the 3.x administration server requires the following:
- A user entry with which the administration server can bind to the directory. This user entry must correspond to your 3.x administration server's Authentication user name that is configurable in Admin Preferences | Admin password. This user ID is often '
admin'. - An administrator's group that is given read, write, search, and compare permissions to the portion of the directory in which your 3.x administration server is keeping entries. This group is especially important because if you have turned on distributed administration in your administration server, then only those entries that belong to this group will have access to the full user and group management forms. By default, your administration server assumes that this group resides at your directory's root point, and that it is named '
Administrators'; however, the name of this group is configurable through the administration server Admin Preferences | Distributed Admin form. - The administration server superuser ID is added to the administrators group.
- A subdirectory that can be used for registering Netscape servers when they are installed. The contents of this directory will contain entries that use the
netscapeServerobject class. This object class allows you to track server information such as which servers are installed and using your directory, where and when they were installed, and who is responsible for managing them. By default, Netscape servers want to maintain this information in a directory called ou=Netscape Servers that is available immediately below your directory's root point.
Creating SuiteSpot Integration Entries
There are three ways you can create the directory elements that your SuiteSpot 3.x administration server needs to perform user and group management in your directory:- Create the necessary elements using manual directory management methods (such as
ldapmodifyor some other LDAP client that has the authority to modify your directory). Use this method if your administration server is using an administrator group other than the default, or if your administration server is using a base DN other than your directory root point. The administrator group must reside at or below the point in your directory represented by this base DN. You configure your administration server base DN from the Global Settings | Configure Directory Service form. - Have the directory server installation form create a simple directory for you. This installation option does the following:
- Creates a root point entry that corresponds to your directory suffix. This entry can be created only if your suffix begins with
oorou(for example, o=Airius.com). If your suffix begins with something other thanoorou(for example, c=US), then you must create the integration entries with some other mechanism than the installation forms. - Creates a subdirectory called ou=Netscape Servers, <your suffix>. That is, if your suffix is o=Airius.com, then the subdirectory is called ou=Netscape Servers, o=Airius.com.
- Creates an administrator entry based on an administrator user ID that you provide. This entry is created with a UID-based distinguished name. That is, if you provide the installation from with a user ID of admin, and your suffix is o=Airius.com, then an entry is created called uid=Admin, o=Airius.com. This entry uses the
inetOrgPersonobject class. In addition, its common name (cn) is set to SuiteSpot Administrator, its surname (sn) is Administrator, its given name is SuiteSpot, and itsuidattribute is set to the user ID that you provided to the installation form (admin, in this case). It is also given auserPasswordattribute that is set to the password that you provide to the installation form. - Creates a group called cn=Administrator, <your suffix>.
- Adds the administrator entry to the administrator group.
- Provides the Administrator group with read, write, search, and compare permissions to the entire directory.
- Sets up anonymous access for read, search, and compare, but disallows read access for the
userPasswordattribute. - Starts your directory server and creates the simple directory with the previously described elements.
- Use the directory server Database Management | SuiteSpot Settings form if you have an existing directory database that you want to upgrade for use with SuiteSpot user and group management.
Using SuiteSpot Settings
Use Database Management | SuiteSpot Settings to add the previously described directory integration entries and permissions to your existing directory. You can also use this form to create additional SuiteSpot administrators if you find a need for them. This form is used primarily for SuiteSpot 3.x integration. To create SuiteSpot 3.x integration entries in your existing directory, do the following:- Make sure your directory server is started and that a valid directory database exists (you cannot use this form to create a database).
- From the directory server manager, go to Database Management | SuiteSpot Settings.
- Fill in the Bind to Server as and Password fields, if necessary. For more information about these fields, refer to "Binding to the Directory" on page 27.
Managing the Referential Integrity Plug-in
Referential integrity is a database mechanism that ensures relationships between related entries are maintained. In the directory server, referential integrity can be used to ensure that a directory update to one entry is correctly reflected in any other entries that may refer to the updated entry. For example, if a user's entry is removed from the directory and referential integrity is enabled, the user would also be removed from any groups of which he is a member. If referential integrity is not enabled, the user would remain a member of the group until manually removed by the administrator. This is an important feature if you are integrating the directory server with other SuiteSpot products that rely on the directory for user and group management.
Whenever a delete or rename operation is performed on a user or group entry in the directory, the operation is logged to the referential integrity log file (<NSHOME>/slapd-<serverID>/logs/referint). After a specified time, known as the update interval, the server searches the directory for all attributes that have been set for integrity updates that have a DN equal to the value of the deleted or modified entries. If the log file shows that the entry was deleted, the corresponding attribute is deleted. If the log file shows that the entry was changed, the corresponding attribute value is modified accordingly.
By default, the referential integrity plug-in is enabled and is set to perform integrity updates on the member, uniquemember, owner, and seeAlso attributes immediately after a delete or rename operation.You can
- disable the referential integrity plug-in if you do not need this feature and want to save CPU cycles
- change the update interval
- modify which attributes to update
Disabling the Referential Integrity Plug-in
You can disable the referential integrity plug-in by editing the plugin postoperation parameter in theslapd.conf file (for information on the location of the configuration files, see "Introducing the Directory Server Configuration Files" on page 30). To disable the plug-in, do the following:
- Open the
slapd.conffile and locate the line that begins: - Change the integer value that immediately follows
referint_postop_initto -1 as follows: - Save the file.
plugin postoperation
"<NSHOME>/lib/referint-plugin.dll"
referint_postop_init.
plugin postoperation
"<NSHOME>/lib/referint-plugin.dll"
referint_postop_init -1
"<NSHOME>/slapd-<serverID>/logs/referint"
member uniquemember owner seeAlso
Changing the Integrity Update Interval
By default, the referential integrity plug-in searches the database and updates related entries immediately after a delete or rename operation. If you want to reduce the impact this operation has on your system, you may want to increase the amount of time between updates. Although there is no maximum interval, some common update intervals are:
- Update immediately
- 90 seconds (updates will occur every 90 seconds)
- 3, 600 seconds (updates will occur every hour)
- 10,800 seconds (updates will occur every 3 hours)
- 28,800 seconds (updates will occur every 8 hours)
- 86,400 seconds (updates will occur once a day)
- 604,800 seconds (updates will occur once a week)
- Open the
slapd.conffile and locate the line that begins: - Change the integer value that immediately follows
referint_postop_initto the number of seconds between updates. For example, if you wanted to change the update interval so that updates occur once a day (every 86,400 seconds), you would edit the line as follows: - Save the file.
plugin postoperation <NSHOME>/lib/referint-plugin.dll
referint_postop_init.
plugin postoperation
"<NSHOME>/lib/referint-plugin.dll"
referint_postop_init 86400
"<NSHOME>/slapd-<serverID>/logs/referint"
member uniquemember owner seeAlso
Modifying Which Attributes to Update
By default, the referential integrity is set up to update the member, uniquemember, owner, and seeAlso attributes. You can either add or delete attributes to be updated by editing the slapd.conf file (for information on the location of configuration files, see "Introducing the Directory Server Configuration Files" on page 30). For performance reasons, the attributes that are set for integrity updating should also be indexed. For information on indexing, see Chapter 7, "Managing Indexes."
To modify which attributes should be integrity updated, do the following:
- Open the
slapd.conffile and locate the line that begins: - Add or delete attribute names from the end of the line that begins
plugin postoperation "<NSHOME>/lib/referint-plugin.dll" referint_postop_init. For example, to modify the plug-in to perform integrity updates on themanagerattribute, addmanagerto the end of the plugin postoperation line as follows: - Save the file.
plugin postoperation
"<NSHOME>/lib/referint-plugin.dll"
referint_postop_init.
plugin postoperation
"<NSHOME>/lib/referint-plugin.dll"
referint_postop_init 0 "<NSHOME>/slapd-<serverID>
/logs/referint" member uniquemember manager
owner seeAlso
Managing Database Transaction Logging
Whenever a directory database operation such as a read or write is performed, the operation is by default logged to the directory server database transaction log. For performance reasons, the operation itself may not be performed immediately. Instead it will be stored in a temporary memory cache on the directory server until the operation is completed. If the server were to experience a failure, such as a power outage, and shut down abnormally, the information about recent directory changes that were stored in the cache would be lost. However, when the directory server restarts, it automatically detects the error condition and uses the database transaction log file to recover the database.
Although database transaction logging and database recovery are automatic processes that require no intervention, you may want to tune some of the database transaction logging parameters for performance reasons.
You can:
- change the location of the database transaction log
- change the database checkpoint interval
- disable transaction durability
Changing the Location of the Database Transaction Log
By default, the database transaction log file is stored in theNSHOME/slapd-<serverID>/db directory along with the directory files themselves. Because the purpose of the transaction log is to aid in the recovery of a directory database that was shut down abnormally, it is a good idea to store the database transaction log on a different disk than the directory database. Having the database transaction log on a separate physical disk may also improve directory server performance.
You can move the location of the database transaction log file by adding the db_logdirectory parameter to the end of the slapd.conf file (for information on the location of the configuration files, see "Introducing the Directory Server Configuration Files" on page 30). For information on the db_logdirectory parameter syntax, see "Database Transaction Log Directory" on page 349.
Changing the Database Checkpoint Interval
Whenever a directory database operation such as a write or modify is performed, the operation is logged to the directory server database transaction log. For performance reasons, the results of the operation itself may not be written to disk immediately. Instead it will be stored in a temporary memory cache on the directory server. At specific intervals, the directory server writes the previously cached data out to the disk and logs a checkpoint entry in the database transaction log. By indicating which changes have already been written to the directory, checkpoint entries essentially tell the directory server where in the database transaction log to begin recovery, thus speeding up the recovery process.
By default, the directory server is set up to send a checkpoint entry to the database transaction log every 60 seconds. Increasing the checkpoint interval may increase the performance of directory server writes. Keep in mind, however, that increasing the checkpoint interval may also significantly increase the amount of time required to recover the directory database after a disorderly shutdown and may waste disk space due to overly large database transaction log files. Therefore, you should only modify this parameter if you are familiar with database optimization and can fully assess the impact of the change.
To modify the checkpoint interval, you must add the db_checkpoint_interval parameter to the end of the slapd.conf file. For information on the db_checkpoint_interval parameter syntax, see "Database Checkpoint Interval" on page 348.
Disabling Durable Transactions
By default, durable database transaction logging is enabled. That means that every time a directory database operation such as a read or write is performed on the directory, a corresponding entry is physically written to the database transaction log disk. To improve performance, you can disable durable transaction logging. When you disable durable transaction logging, every directory database operation is logically written to the database transaction log file, but it may not be physically written to disk immediately. That means that if a directory change was written to the logical database transaction log file, but not physically written to disk at the time of a system crash, you would be unable to recover the change. When durable transactions are disabled, the recovered database is consistent, but will not reflect the results of any LDAP write operations that completed just before the system crash.
You can disable durable transactions by adding the db_durable_transactions parameter to the end of the slapd.conf file (for information on the location of the configuration files, see "Introducing the Directory Server Configuration Files" on page 30). For information on the db_durable_transactions parameter syntax, see "Database Durable Transactions" on page 349.