Configure an LDIF Backend
An LDIF backend stores directory entries in an LDIF file. When the backend starts, it loads the file into memory and serves reads from memory. Each LDAP write rewrites the backing file. Use it for small, mostly static datasets, such as a namespace root or a few configuration entries. For large datasets or frequent writes, use a database backend with indexes instead.
The backend supports basic LDAP operations, with limited support for custom controls. Its backend-specific supported-control list contains only the subtree delete control. Do not assume that database-backend features such as paged results or server-side sorting are available; check the controls required by your application.
For the complete property descriptions, see LDIF Backend in the Reference.
Create the Backend
The example publishes dc=example,dc=com from a backend named namespace. Run the commands from the OpenDJ installation directory on the server host. Replace the host name, paths, credentials, and base DN for your deployment. The base DN must not already be registered by another backend, including the default userRoot backend.
Prepare a password file and a truststore for the administration connector. Keep password files readable only by authorized users. The examples assume that the server’s certificate is trusted by /secure/admin-truststore, with its password in /secure/admin-truststore.pin, and the Directory Manager password is in /secure/directory-manager.pwd.
-
Save the following entries as
config/namespace.ldifunder the OpenDJ instance directory. List parent entries before their children:dn: dc=example,dc=com objectClass: top objectClass: domain dc: example dn: ou=static,dc=example,dc=com objectClass: top objectClass: organizationalUnit ou: staticThe server process must be able to read the file. If LDAP writes will be allowed, it must also be able to write the file and create and rename files in its directory. Updates use temporary
.newand.oldfiles alongside the backing file. -
Create and enable the backend, explicitly disabling LDAP writes for this static dataset:
bin/dsconfig create-backend \ --hostname opendj.example.com \ --port 4444 \ --bindDN "cn=Directory Manager" \ --bindPasswordFile /secure/directory-manager.pwd \ --trustStorePath /secure/admin-truststore \ --trustStorePasswordFile /secure/admin-truststore.pin \ --backend-name namespace \ --type ldif \ --set base-dn:dc=example,dc=com \ --set ldif-file:config/namespace.ldif \ --set enabled:true \ --set writability-mode:disabled \ --no-promptCreating the backend loads the file; a separate
import-ldifcommand is not required. If the file does not exist, the backend starts empty. It does not synthesize the base entry frombase-dn. -
Check the effective settings:
bin/dsconfig get-backend-prop \ --hostname opendj.example.com \ --port 4444 \ --bindDN "cn=Directory Manager" \ --bindPasswordFile /secure/directory-manager.pwd \ --trustStorePath /secure/admin-truststore \ --trustStorePasswordFile /secure/admin-truststore.pin \ --backend-name namespace \ --no-promptUsing an authenticated LDAP client permitted to read the entries, perform a base-object search at
dc=example,dc=comwith filter(objectClass=*). Verify that it returns the domain entry, then searchou=static,dc=example,dc=comto verify the child entry. Configure access controls for application clients separately; creating a backend does not grant them read access.
Manage the File and Write Policy
| Property | Behavior |
|---|---|
|
Required path to the backing file on the server. Relative paths are resolved against the OpenDJ instance directory. Changing the path requires a backend restart. |
|
Exactly one base DN is supported by this implementation. Entries must be at or below it, with their parents present in the file. Changing it requires a backend restart. |
|
|
|
|
To change a property, use dsconfig set-backend-prop with the same connection options as above, --backend-name namespace, and, for example, --set writability-mode:enabled. The backend’s write policy applies to its own entries; it does not set the write policy of subordinate backends.
The backend does not watch the file for external edits. To replace the static entries, take the backend out of service with --set enabled:false, back up and edit its LDIF file, and enable it again with --set enabled:true. Re-enabling reloads the file. Do not edit the file while the backend is enabled: reads continue to use the in-memory data, and an LDAP write can overwrite your edits. Schedule the interruption when clients do not need this suffix or its subordinate suffixes.
Publish a Parent Suffix for Local Backends
An LDIF backend can provide a parent entry while separate local backends serve subordinate suffixes. For example:
dc=example,dc=com LDIF parent backend: namespace
|-- ou=People,dc=example,dc=com PDB backend: people
|-- ou=Groups,dc=example,dc=com PDB backend: groups
`-- ou=Scratch,dc=example,dc=com Memory backend: scratch
Keep the parent entry and any other entries owned by the LDIF backend in namespace.ldif. Configure each subordinate backend with its own child base DN; two backends cannot register the same base DN. Create the base entry and populate each child backend separately. Do not keep copies of the subordinate branches in the parent backend: registering a child does not remove existing parent data.
Operations at or below ou=People,dc=example,dc=com are routed to people. A subtree search based at dc=example,dc=com can include the parent and subordinate entries. Test the complete results and final LDAP result code with the controls and client identities your applications use.
The PDB backends provide persistent storage for their branches. The Memory backend is suitable only for disposable data: its entries, including its base entry, disappear on restart or backend reset and must be populated again. The parent LDIF backend does not provide automatic fallback for an unavailable child.
For creation, migration, and operational considerations, see Subordinate Backends. For the individual backend procedures, see Creating a New Database Backend and Using the Memory Backend.