Manage, Trim, and Encrypt the 389 DS Replication Changelog

The replication changelog records client changes and updates received from replication partners. Suppliers and hubs replay those records during incremental replication. Managing changelog retention, trimming, compaction, and encryption directly affects disk usage and how long an offline replica can catch up without reinitialization.

This guide covers changelog inspection, retention policy, automatic trimming, manual compaction, encryption, and recovery implications. For agreement health and synchronization errors, see manage replication agreements. For replica recovery after backup restore, see restore a replicated server. For TLS certificate setup, see the TLS chapters in the 389 Directory Server tutorial. The Retro Changelog plug-in is a separate client-facing feature and is not covered here.

Tested on: Rocky Linux 10.2; 389 Directory Server 3.2.0.

How the replication changelog works

Directory Server maintains a replication changelog for each replicated backend. The changelog stores:

• Client writes on the local supplier or hub
• Changes received from upstream replication partners

Suppliers and hubs read the changelog to forward incremental updates to destinations covered by replication agreements. Consumers without outgoing agreements do not use the changelog the same way; they receive updates but typically do not maintain a forwardable changelog unless promoted to hub or supplier roles.

The replication changelog is not the Retro Changelog plug-in. Retro Changelog exposes change records to LDAP clients. Replication changelog data is internal to replication and configured with dsconf replication get-changelog and set-changelog.

Locate and inspect the changelog

Examples use suffix dc=example,dc=com on instance ldap1. Map the suffix to its backend before you inspect files or change retention.

Map the suffix to a backend

dsconf -y /root/dm.pw ldap1 backend suffix list

Sample output:

dc=example,dc=com (userroot)

The name in parentheses (userroot) is the backend database for that suffix.

Identify the backend implementation

backend suffix list names the database; it does not report whether the storage engine is LMDB or Berkeley DB. Query the backend configuration separately:

dsconf -y /root/dm.pw ldap1 backend config get | grep '^nsslapd-backend-implement'

Sample output on this lab instance:

nsslapd-backend-implement: mdb

Possible values are mdb and bdb. New 389 Directory Server 3.x installations normally use LMDB.

Display changelog settings

dsconf -y /root/dm.pw ldap1 replication get-changelog --suffix "dc=example,dc=com"

Sample output from this lab, where the seven-day value was explicitly stored:

dn: cn=changelog,cn=userroot,cn=ldbm database,cn=plugins,cn=config
cn: changelog
nsslapd-changelogmaxage: 7d
objectClass: top
objectClass: extensibleObject

get-changelog may omit parameters that are using their defaults. When the trim interval is absent, Directory Server uses the default 300-second interval.

Locate changelog storage on disk

Changelog file layout depends on the backend implementation:

With LMDB, the changelog is integrated into the backend database. data.mdb contains more than changelog data, so its total size is only a coarse disk-usage indicator. Logical trimming may make pages reusable without immediately reducing the file's filesystem size.

On this lab instance with LMDB, check coarse database size:

ls -lh /var/lib/dirsrv/slapd-ldap1/db/data.mdb

Sample output:

-rw-------. 1 dirsrv dirsrv 9.0M Jul 20 08:06 /var/lib/dirsrv/slapd-ldap1/db/data.mdb

On Berkeley DB backends, inspect replication_changelog.db under the backend directory instead.

Check filesystem headroom on the database partition:

df -h /var/lib/dirsrv/slapd-ldap1/db

Sample output:

Filesystem            Size  Used Avail Use% Mounted on
/dev/mapper/rlm-root   14G   11G  2.0G  85% /

Confirm replication health before changes

Check agreement status before you shorten retention or compact the changelog:

dsconf -y /root/dm.pw ldap1 repl-agmt status --suffix "dc=example,dc=com" --bind-dn "cn=Directory Manager" --bind-passwd-file /root/consumer1-dm.pw ldap1-to-consumer1

Confirm Last Update Status shows Error (0) with a successful message and compare supplier and consumer data. Resolve generation ID, RUV, or connectivity errors before you trim the changelog on the authoritative supplier.

Choose a safe changelog retention policy

Three attributes control automatic trimming:

Red Hat recommends --max-age as the primary control. Set the maximum age to cover your longest expected replica outage plus operational buffer. Align it with nsDS5ReplicaPurgeDelay on the replica configuration and your organization's maximum supported downtime.

Use --max-entries as an additional safeguard when write volume could produce an oversized changelog before age limits apply. Do not rely on entry count alone when you can express retention as a time window.

Setting --max-age to 0 disables age-based purging. Do not use 0 expecting an immediate trim.

Directory Server retains changelog records still required by replicas in the topology, even when age or entry limits are reached. An offline consumer or a failing agreement can prevent trimming from freeing space until that replica catches up, is reinitialized, or is removed from the topology.

Configure automatic changelog trimming

Configure retention on each supplier and hub that maintains a changelog for the suffix.

Set a fourteen-day maximum age and the default five-minute trim interval:

dsconf -y /root/dm.pw ldap1 replication set-changelog --suffix "dc=example,dc=com" --max-age "14d" --trim-interval "300"

Sample output:

Successfully updated replication changelog

Verify the stored values:

dsconf -y /root/dm.pw ldap1 replication get-changelog --suffix "dc=example,dc=com"

Sample output:

dn: cn=changelog,cn=userroot,cn=ldbm database,cn=plugins,cn=config
cn: changelog
nsslapd-changelogmaxage: 14d
nsslapd-changelogtrim-interval: 300
objectClass: top
objectClass: extensibleObject

--max-age accepts units such as s, m, h, d, and w. Add --max-entries when you need both age and count limits:

dsconf -y /root/dm.pw ldap1 replication set-changelog --suffix "dc=example,dc=com" --max-age "14d" --max-entries "100000" --trim-interval "300"

Sample output:

Successfully updated replication changelog

Restore the lab default before you continue to manual trimming. Clear the temporary entry limit with an empty --max-entries value:

dsconf -y /root/dm.pw ldap1 replication set-changelog --suffix "dc=example,dc=com" --max-age "7d" --max-entries "" --trim-interval "300"

Sample output:

Successfully updated replication changelog

Passing an empty value removes the corresponding changelog attribute from the stored configuration.

Diagnose an unexpectedly large changelog

A large changelog is not always corruption. Common causes:

• Offline or unreachable replicas holding required CSNs
• Disabled or failing replication agreements
• Obsolete servers still listed in the topology RUV
• Continuous replication errors preventing successful sessions
• High write volume on a supplier
• Missing or unsuitable trimming settings
• Removed supplier whose RUV was not cleaned with CleanAllRUV
• Logical trimming completed but filesystem space not reclaimed yet

Start with agreement status on every outgoing path, error logs for Can't locate CSN in the changelog and Data required to update replica has been purged from the changelog, and replication get-changelog on each supplier. Compare changelog file or LMDB size over time after you confirm all replicas are synchronized.

Manually trim and compact a large changelog

Trimming removes records logically. If disk usage remains a concern after trimming, run backend compact-db --only-changelog to consolidate reusable database space. Actual filesystem size reduction depends on the backend and available free pages.

Record original settings

dsconf -y /root/dm.pw ldap1 replication get-changelog --suffix "dc=example,dc=com"

Save the output. You restore these values after manual trimming.

Confirm replicas are synchronized

Resolve replication errors before you shorten retention. Offline replicas that still appear in the RUV can block trimming of their required CSNs.

Temporarily tighten retention

Reduce age, entries, and trim interval only for the maintenance window:

dsconf -y /root/dm.pw ldap1 replication set-changelog --suffix "dc=example,dc=com" --max-age "300s" --max-entries 500 --trim-interval 60

Sample output:

Successfully updated replication changelog

Wait at least one trim cycle. With --trim-interval 60, wait sixty seconds or longer.

Compact the changelog

dsconf -y /root/dm.pw ldap1 backend compact-db --only-changelog

Sample output:

Successfully started Database Compaction Task

Compaction runs as a background task. Wait for completion before you measure disk usage. On LMDB backends, check the instance error log:

grep -i compact /var/log/dirsrv/slapd-ldap1/errors | tail -5

Sample output when compaction finishes:

[20/Jul/2026:02:38:27.031058966 +0000] - NOTICE - dbmdb_public_dblayer_compact - Compacting databases ...
[20/Jul/2026:02:38:27.468544687 +0000] - NOTICE - dbmdb_public_dblayer_compact - Compacting databases finished.

On Berkeley DB backends, recheck replication_changelog.db after the task completes.

Restore original retention

Return to the values recorded before maintenance. In this lab, the original values were 7d, no entry-count limit, and a 300-second trim interval:

dsconf -y /root/dm.pw ldap1 replication set-changelog --suffix "dc=example,dc=com" --max-age "7d" --max-entries "" --trim-interval "300"

Sample output:

Successfully updated replication changelog

Compare size before and after

On this LMDB lab instance, the total data.mdb file size remained unchanged after logical trimming and compaction:

ls -lh /var/lib/dirsrv/slapd-ldap1/db/data.mdb

Sample output after compaction:

-rw-------. 1 dirsrv dirsrv 9.0M Jul 20 08:08 /var/lib/dirsrv/slapd-ldap1/db/data.mdb

That does not mean trimming failed. LMDB may retain pages for reuse inside the integrated database file. Berkeley DB replication_changelog.db files may shrink substantially when they contain reclaimable pages.

Encrypt the replication changelog

Changelog encryption protects replication history at rest on disk. Directory Server generates symmetric cipher keys, encrypts changelog records with them, and wraps those keys using the server TLS certificate public key. The private key and PIN (or PIN file) are required to unwrap the keys at startup.

Perform encryption on one supplier or hub at a time. Verify replication before you continue to the next server. TLS must already be enabled; this guide does not cover certificate creation or NSS database setup.

Export the existing changelog

Store the export on the instance host under ldif/, not on a shared unencrypted volume:

dsconf -y /root/dm.pw ldap1 replication export-changelog to-ldif -o /var/lib/dirsrv/slapd-ldap1/ldif/changelog-export.ldif -r "dc=example,dc=com"

Restrict permissions on the plaintext export immediately:

chmod 600 /var/lib/dirsrv/slapd-ldap1/ldif/changelog-export.ldif

Both export-changelog and chmod normally return no output on success. Confirm that the file exists and has restrictive permissions:

ls -lh /var/lib/dirsrv/slapd-ldap1/ldif/changelog-export.ldif

Sample output:

-rw-------. 1 root root 15K Jul 20 08:09 /var/lib/dirsrv/slapd-ldap1/ldif/changelog-export.ldif

Protect this plaintext export. Changelog encryption protects data at rest inside the database; it does not encrypt export files. The LDIF can contain readable directory changes and must be protected separately until you remove it after verification.

Enable changelog encryption

dsconf -y /root/dm.pw ldap1 replication set-changelog --suffix "dc=example,dc=com" --encrypt

Sample output:

You must restart the server for this to take effect
Successfully updated replication changelog

Import the changelog and restart

Import the exported LDIF back into the changelog configuration:

dsconf -y /root/dm.pw ldap1 replication import-changelog from-ldif -r "dc=example,dc=com" /var/lib/dirsrv/slapd-ldap1/ldif/changelog-export.ldif

A successful import normally returns no output. Check the exit status and the instance error log if the command fails.

Restart the instance:

dsctl ldap1 restart

Sample output:

Instance "ldap1" has been restarted

Verify encryption and replication

Read changelog settings:

dsconf -y /root/dm.pw ldap1 replication get-changelog --suffix "dc=example,dc=com"

Sample output when encryption is active:

dn: cn=changelog,cn=userroot,cn=ldbm database,cn=plugins,cn=config
cn: changelog
nsSymmetricKey:: [wrapped key omitted]
nsslapd-changelogmaxage: 7d
nsslapd-changelogtrim-interval: 300
nsslapd-encryptionalgorithm: AES
objectClass: top
objectClass: extensibleObject

nsslapd-encryptionalgorithm: AES is the important result. nsSymmetricKey holds the wrapped symmetric key material.

Modify a test entry on the supplier so the changelog records a new write:

ldapmodify -x -H ldap://127.0.0.1:389 -D "cn=Directory Manager" -y /root/dm.pw <<'EOF'
dn: uid=user1,ou=People,dc=example,dc=com
changetype: modify
replace: description
description: replication-encryption-test
EOF

Sample output:

modifying entry "uid=user1,ou=People,dc=example,dc=com"

Prompt the agreement to send pending changes:

dsconf -y /root/dm.pw ldap1 repl-agmt poke --suffix "dc=example,dc=com" ldap1-to-consumer1

Sample output:

Agreement has been poked

Read the same attribute on the consumer. In production, replace 127.0.0.1:1389 with your consumer LDAP URL:

ldapsearch -LLL -x -H ldap://127.0.0.1:1389 -D "cn=Directory Manager" -y /root/consumer1-dm.pw -b "uid=user1,ou=People,dc=example,dc=com" -s base description

Sample output:

dn: uid=user1,ou=People,dc=example,dc=com
description: replication-encryption-test

You should now see the modified value on the consumer. That indicates the write was recorded, transmitted, decrypted if necessary, and applied downstream.

On Berkeley DB backends, complete the live replication test while the instance is running, then inspect the changelog file offline.

Stop the instance:

dsctl ldap1 stop

With the instance offline, inspect the Berkeley DB changelog:

dbscan -f /var/lib/dirsrv/slapd-ldap1/db/userroot/replication_changelog.db \
  | tail -50

Encrypted records appear as opaque data rather than readable LDAP change attributes. If readable change values remain visible, recheck the encryption configuration.

Start the instance again:

dsctl ldap1 start

Sample output:

Instance "ldap1" has been started

On LMDB backends, rely on get-changelog output and the live replication test above.

Revert encryption in the lab

Export the changelog again:

dsconf -y /root/dm.pw ldap1 replication export-changelog to-ldif -o /var/lib/dirsrv/slapd-ldap1/ldif/changelog-export.ldif -r "dc=example,dc=com"

Restrict permissions on the export immediately:

chmod 600 /var/lib/dirsrv/slapd-ldap1/ldif/changelog-export.ldif

Disable encryption:

dsconf -y /root/dm.pw ldap1 replication set-changelog --suffix "dc=example,dc=com" --disable-encrypt

Sample output:

You must restart the server for this to take effect
Successfully updated replication changelog

Import the exported LDIF:

dsconf -y /root/dm.pw ldap1 replication import-changelog from-ldif -r "dc=example,dc=com" /var/lib/dirsrv/slapd-ldap1/ldif/changelog-export.ldif

As during the encryption procedure, a successful import-changelog command normally returns no output.

Restart the instance:

dsctl ldap1 restart

Sample output:

Instance "ldap1" has been restarted

Confirm encryption attributes are gone:

dsconf -y /root/dm.pw ldap1 replication get-changelog --suffix "dc=example,dc=com"

Sample output after rollback:

dn: cn=changelog,cn=userroot,cn=ldbm database,cn=plugins,cn=config
cn: changelog
nsslapd-changelogmaxage: 7d
nsslapd-changelogtrim-interval: 300
objectClass: top
objectClass: extensibleObject

There is no nsslapd-encryptionalgorithm line when encryption is disabled.

Remove the plaintext export when verification finishes. shred provides best-effort secure deletion and is not reliable on SSDs, copy-on-write filesystems, snapshots, or journaled storage:

shred -u /var/lib/dirsrv/slapd-ldap1/ldif/changelog-export.ldif

shred exits silently on success. Also restrict file permissions during the workflow and store exports only on encrypted storage when possible.

Preserve the changelog during backup and recovery

A normal suffix LDIF export from backend export or ldapsearch is not a changelog backup. Use replication export-changelog when you need changelog contents, including the encryption conversion workflow above.

Keep complete backup, restore, and replicated-server recovery procedures in back up and restore 389 Directory Server and the restore a replicated server guide. This chapter explains changelog-specific implications only.

Validate and monitor changelog health

After retention, trimming, compaction, or encryption changes, verify:

• replication get-changelog shows the intended --max-age, --max-entries, and --trim-interval on every supplier and hub
• Changelog file or LMDB size stabilizes after trimming and compaction
• Agreement status reports successful incremental updates
• Offline replicas reconnect within the configured retention window
• Test writes replicate in every required direction
• Error logs show no changelog, RUV, or missing-update messages
• The database filesystem has sufficient free space

Troubleshooting

References

• Red Hat Directory Server 13: Trimming the replication changelog
• Red Hat Directory Server 13: Encrypting the replication changelog
• Red Hat Directory Server 13: Configuration and schema reference
• Red Hat Directory Server 13: Backing up and restoring Directory Server
• FreeIPA-users discussion: Can't sync a new replica, large DB file

Summary

The replication changelog on each supplier and hub stores changes required for incremental replication. Configure retention with replication set-changelog, diagnose growth against replica health, trim and compact with a recorded rollback path when disk usage remains a concern, and encrypt only after TLS is working using export, --encrypt, import, and restart. Trimming frees logical space; use backend compact-db --only-changelog to consolidate reusable database space when needed. Shorter retention saves space but shortens the window for offline replica catch-up.