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.

  1. Save the following entries as config/namespace.ldif under 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: static

    The 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 .new and .old files alongside the backing file.

  2. 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-prompt

    Creating the backend loads the file; a separate import-ldif command is not required. If the file does not exist, the backend starts empty. It does not synthesize the base entry from base-dn.

  3. 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-prompt

    Using an authenticated LDAP client permitted to read the entries, perform a base-object search at dc=example,dc=com with filter (objectClass=*). Verify that it returns the domain entry, then search ou=static,dc=example,dc=com to 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

ldif-file

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.

base-dn

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.

enabled

true opens the backend and loads its entries. false takes it out of service.

writability-mode

enabled, the LDIF backend default, permits authorized LDAP writes subject to global writability and normal validation. disabled rejects writes. internal-only rejects external writes while allowing internal and replication operations; this setting does not itself configure replication.

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.