7. Tuning Transaction Logging

Every Directory Server contains a transaction log which writes operations for all the databases it manages. Whenever a directory database operation such as a modify is performed, the server creates a single database transaction for all of the database operations invoked as a result of that LDAP operation. This includes both updating the entry data in the entry index file and updating all of the attribute indexes. If all of the operations succeed, the server commits the transaction, writes the operations to the transaction log, and verifies that the entire transaction is written to disk. If any of these operations fail, the server rolls back the transaction, and all of the operations are discarded. This all-or-nothing approach in the server guarantees that an update operation is atomic. Either the entire operation succeeds permanently and irrevocably, or it fails.
Periodically, the Directory Server (through internal housekeeping threads) flushes the contents of the transaction logs to the actual database index files and checks if the transaction logs require trimming.
If the server experiences a failure, such as a power outage, and shuts down abnormally, the information about recent directory changes is still saved by the transaction log. When the server restarts, the directory automatically detects the error condition and uses the database transaction log to recover the database.
Although database transaction logging and database recovery are automatic processes that require no intervention, it can be advisable to tune some of the database transaction logging attributes to optimize performance.

Warning

The transaction logging attributes are provided only for system modifications and diagnostics. These settings should be changed only with the guidance of Red Hat Technical Support. Setting these attributes and other configuration attributes inconsistently may cause the directory to be unstable.

7.1. Changing the Location of the Database Transaction Log

By default, the database transaction log file is stored in the /var/lib/dirsrv/slapd-instance_name/db directory along with the database 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 from the one containing the directory database. Storing the database transaction log on a separate physical disk may also improve directory performance.

Important

If you move the database transaction directory outside the /var/lib/dirsrv directory, then you need to label the new location with the dirsrv_var_lib_t context. Otherwise, SELinux may prevent the server from writing to the directory and database operations may fail.
For example:
# /usr/sbin/semanage file -a -t dirsrv_var_lib_t -f /new/database-txns/directory
Changing SELinux labels is covered in the Directory Server Administrator's Guide and the Red Hat Enterprise Linux 6 SELinux Guide.
To change the location of the database transaction log:
  1. Stop Directory Server.
    service dirsrv stop [instance_name]
  2. Edit the dse.ldif file and change the nsslapd-db-logdirectory attribute to show the new log file location. Provide the full path to the log directory in the attribute.
    For information on the nsslapd-db-logdirectory attribute syntax, see the Directory Server Configuration, Command, and File Reference.
  3. Copy the existing transation logs and the DBVERSION file into the new transaction log directory.
    cp /var/lib/dirsrv/slapd-instance_name/db/{log.*,DBVERSION} /path/to/newdirectory
  4. Restart Directory Server.
    service dirsrv start [instance_name]

7.2. Changing the Database Checkpoint Interval

At regular intervals, the Directory Server writes operations logged in the transaction log to the database index files and logs a checkpoint entry in the database transaction log. By indicating which changes have already been written to the database indexes, checkpoint entries indicate where to begin recovery from the transaction log, 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 write operations. However, increasing the checkpoint interval may also increase the amount of time required to recover directory databases after a disorderly shutdown and require more disk space due to large database transaction log files. Therefore, only modify this attribute if you are familiar with database optimization and can fully assess the effect of the change.
To modify the checkpoint interval while the server is running, use the ldapmodify command-line utility to add the nsslapd-db-checkpoint-interval attribute to the cn=config,cn=ldbm database,cn=plugins,cn=config entry.
ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=config,cn=ldbm database,cn=plugins,cn=config
changetype: modify
add: nsslapd-db-checkpoint-interval
nsslapd-db-checkpoint-interval: 120
For more information on the syntax of the nsslapd-db-checkpoint-interval attribute, see the Directory Server Configuration, Command, and File Reference.

7.3. Disabling Durable Transactions

Durable transaction logging means that each LDAP update operation, comprised of a sequence of database operations in a transaction, is physically written to disk. Even though each LDAP operation can be comprised of multiple database operations, each LDAP operation is treated as a single database transation. Each LDAP operation is both atomic and durable.

Warning

Turning off durable transactions can improve Directory Server write performance at the risk of data loss.
When durable transaction logging is disabled, every directory database operation is written to the database transaction log file but may not be physically written to disk immediately. 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, the change cannot be recovered. When durable transactions are disabled, the recovered database is consistent but does not reflect the results of any LDAP write operations that completed just before the system crash.
By default, durable database transaction logging is enabled. To disable durable transaction logging:
  1. Use the ldapmodify command-line utility to add the nsslapd-db-durable-transactions attribute to the cn=config,cn=ldbm database,cn=plugins,cn=config entry, and set the value of this attribute to off.
    ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
    dn: cn=config,cn=ldbm database,cn=plugins,cn=config
    changetype: modify
    add: nsslapd-db-durable-transactions
    nsslapd-db-durable-transactions: off
    For information on the syntax of the nsslapd-db-durable-transactions attribute, see the Directory Server Configuration, Command, and File Reference.
  2. Restart the Directory Server.
    service dirsrv restart

7.4. Specifying Transaction Batching

To improve update performance when full transaction durability is not required, use the nsslapd-db-transaction-batch-val attribute to specify how many transactions will be batched before being committed to the transaction log. Setting this attribute to a value of greater than 0 causes the server to delay committing transactions until the number of queued transactions is equal to the attribute value. This is similar to disabling durable transaction logging (in the nsslapd-db-durable-transaction attribute), but setting the batch value gives more control over how many transactions can be potentially lost.
To specify or modify transaction batching while the server is running, use the ldapmodify command-line utility to add the nsslapd-db-transaction-batch-val attribute to the cn=config,cn=ldbm database,cn=plugins,cn=config entry.
ldapmodify -D "cn=directory manager" -W -p 389 -x

dn: cn=config,cn=ldbm database,cn=plugins,cn=config
changetype: modify
add: nsslapd-db-transaction-batch-val
nsslapd-db-transaction-batch-val: 1
For more information on the syntax and values of the nsslapd-db-transaction-batch-val attribute, see the Directory Server Configuration, Command, and File Reference.