From 795e8ce3089730d0f82a8f653fbad000c03b01f3 Mon Sep 17 00:00:00 2001 From: Valery Kharseko <vharseko@3a-systems.ru> Date: Wed, 18 Nov 2026 06:53:40 +0000 Subject: [PATCH] Document subordinate backends in the administration guide (#1302) --- opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-memory-backend.adoc | 4 - opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-ldif-backend.adoc | 26 ++++---- opendj-doc-generated-ref/src/main/asciidoc/admin-guide/index.adoc | 1 opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-subordinate-backends.adoc | 91 ++++++++++++++++++++++++++++++ 4 files changed, 106 insertions(+), 16 deletions(-) diff --git a/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-ldif-backend.adoc b/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-ldif-backend.adoc index 8783411..a028ae1 100644 --- a/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-ldif-backend.adoc +++ b/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-ldif-backend.adoc @@ -116,25 +116,25 @@ 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. -[#ldif-backend-proxy-suffixes] -=== Publish a Parent Suffix for Proxy Backends +anchor:ldif-backend-proxy-suffixes[] -A local LDIF backend can provide a parent entry while separate proxy backends serve subordinate suffixes. For example: +[#ldif-backend-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: [source,text] ---- -dc=example,dc=com LDIF backend: namespace -|-- ou=static,dc=example,dc=com local LDIF entries -|-- dc=sub1,dc=example,dc=com proxy backend: sub1 -`-- dc=sub2,dc=example,dc=com proxy backend: sub2 +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 and local entries in `namespace.ldif`. Configure each proxy backend with its own child base DN and discovery mechanism for the directory authoritative for that branch. Two backends cannot register the same base DN. This topology publishes a namespace root and lets clients address the branches through one OpenDJ endpoint. +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 `dc=sub1,dc=example,dc=com` are routed to the `sub1` proxy backend. Adding a copy of that child base entry to the parent's LDIF file does not change suffix routing or make the LDIF backend authoritative for that branch. +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. -A subtree search from `dc=example,dc=com` reaches the subordinate proxy backends as well as the local parent. If a selected child proxy route has no operational remote server after its primary and secondary candidates have been exhausted, the search returns LDAP `UNAVAILABLE (52)`. Entries from available branches may already have been returned before the final error. Clients must check the final result code; those entries do not make the search successful or complete. A base-object search confined to the local parent does not query the child proxy routes. +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. -This remains true even if the LDIF file contains the parent entry and copies of the child base entries. Those static entries can publish namespace roots; they do not provide runtime failover, reconcile duplicate local and remote entries, or transparently replace a proxy backend for operations under its suffix. The LDIF backend does not turn an unavailable child route into a successful empty search or a user-not-found result. - -Health-aware local LDIF fallback, a policy for accepting partial results, and full virtual-directory federation require separate design and implementation. They are not enabled by this configuration. +For creation, migration, and operational considerations, see xref:./chap-subordinate-backends.adoc#chap-subordinate-backends[Subordinate Backends]. For the individual backend procedures, see xref:./chap-import-export.adoc#create-database-backend[Creating a New Database Backend] and xref:./chap-memory-backend.adoc#chap-memory-backend[Using the Memory Backend]. diff --git a/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-memory-backend.adoc b/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-memory-backend.adoc index f15c9c1..f856cea 100644 --- a/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-memory-backend.adoc +++ b/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-memory-backend.adoc @@ -145,8 +145,6 @@ |Cassandra |Directory data stored in a Cassandra cluster. See xref:../how-to/cassandra-backend.adoc[Store Directory Data in Cassandra]. -|Proxy -|Routing LDAP operations to remote directories. Data durability depends on the remote directories' storage. A local Memory backend does not automatically replace an unavailable proxy suffix. |=== -For JDBC and Cassandra, configure the database or cluster's persistence and availability to meet your requirements. For a local parent suffix above subordinate proxy suffixes, Memory can publish temporary parent entries, but those entries disappear on reset and do not provide failover for operations routed to a child proxy backend. Use durable storage for parent entries that must survive a restart. +For JDBC and Cassandra, configure the database or cluster's persistence and availability to meet your requirements. A Memory backend can hold a temporary branch beneath a local parent backend, but its entries disappear on reset. Use durable storage for entries that must survive a restart. See xref:./chap-subordinate-backends.adoc#chap-subordinate-backends[Subordinate Backends]. diff --git a/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-subordinate-backends.adoc b/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-subordinate-backends.adoc new file mode 100644 index 0000000..f389648 --- /dev/null +++ b/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-subordinate-backends.adoc @@ -0,0 +1,91 @@ +//// +The contents of this file are subject to the terms of the Common Development and +Distribution License (the License). You may not use this file except in compliance with the +License. + +You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the +specific language governing permission and limitations under the License. + +When distributing Covered Software, include this CDDL Header Notice in each file and include +the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL +Header, with the fields enclosed by brackets [] replaced by your own identifying +information: "Portions copyright [year] [name of copyright owner]". + +Copyright 2026 3A Systems, LLC. +//// + +[#chap-subordinate-backends] +== Subordinate Backends + +A subordinate backend serves a base DN below the base DN of another backend. This arrangement is also called overlapping or nested backends. The overlap is in the directory namespace: each backend has its own registered base DN and its own data. + +[source,text] +---- +dc=example,dc=com LDIF parent backend: namespace +|-- ou=People,dc=example,dc=com PDB backend: people +| `-- uid=alice,ou=People,dc=example,dc=com +|-- ou=Groups,dc=example,dc=com PDB backend: groups +`-- ou=Scratch,dc=example,dc=com Memory backend: scratch +---- + +OpenDJ routes an operation for `ou=People` or an entry below it to `people`, the backend with the most specific matching base DN. A subtree search based at `dc=example,dc=com` can include entries from the parent and the subordinate backends. The registered base DNs must be distinct; a backend cannot register a base DN already registered by another backend. In this example, the LDIF backend stores the parent entry, the PDB backends store persistent branches, and the Memory backend holds disposable test data. Memory entries must be populated again after a restart or backend reset. + +A backend can have multiple base DNs if its implementation permits it, but its own base DNs cannot be ancestors or descendants of each other. If one base DN of a backend is subordinate to another backend's base DN, the other base DNs of that backend must also be subordinate to the same parent base DN. Check the properties and restrictions of the backend type you choose in the https://doc.openidentityplatform.org/opendj/reference/dsconfig-subcommands-ref[dsconfig reference]. + +[#subordinate-backends-uses] +=== When to Use Subordinate Backends + +Splitting a directory tree can be useful when different branches need different storage or operational treatment: + +* Store a branch in a separate database backend so it can have its own indexes, cache settings, and administrative operations. Indexes are configured per backend; see xref:./chap-indexing.adoc[Configuring Indexes]. +* Replicate a subtree separately from the rest of the suffix. Each replicated part needs its own replication configuration; see xref:./chap-replication.adoc#repl-per-suffix[Replication Per Suffix] and xref:./chap-replication.adoc#repl-subtree[Subtree Replication]. +* Publish a small local namespace root in an LDIF backend while separate local backends serve child suffixes. See xref:./chap-ldif-backend.adoc#ldif-backend-subordinate-suffixes[Publish a Parent Suffix for Local Backends]. +* Use a disposable Memory backend for an isolated test branch. Its entries disappear on restart or backend disablement; see xref:./chap-memory-backend.adoc#chap-memory-backend[Using the Memory Backend]. + +These choices add configuration and operational work. A single backend can be simpler when all branches share the same storage, replication, and maintenance needs. A subordinate backend is not a replica or a failover mechanism merely because it is nested beneath another backend. + +[#subordinate-backends-create] +=== Creating a Subordinate Backend + +The following example creates an empty persistent PDB backend below an existing `dc=example,dc=com` suffix. Run it on a test instance first. The parent backend must already be configured and contain the parent entry. Choose a child base DN that is not already registered and a branch that does not already contain data in the parent backend; for an existing branch, follow xref:#subordinate-backends-migrate[Moving an Existing Branch] instead. + +[source,bash] +---- +bin/dsconfig create-backend \ + --hostname localhost --port 4444 \ + --bindDN 'cn=Directory Manager' --bindPassword password \ + --backend-name people --type pdb \ + --set base-dn:ou=People,dc=example,dc=com \ + --set enabled:true --set db-cache-percent:10 \ + --trustAll --no-prompt +---- + +Adjust connection settings, credentials, backend type, and cache allocation for your installation. `--trustAll` is appropriate only for a controlled test environment. Account for the caches of all database backends when sizing the JVM; see xref:./chap-import-export.adoc#create-database-backend[Creating a New Database Backend]. + +Registering a base DN does not populate the backend. Add its base entry and data using the method appropriate for its type, then verify the result. For a database backend, see xref:./chap-import-export.adoc#create-database-backend[Creating a New Database Backend] and xref:./chap-import-export.adoc[Managing Directory Data]. Search both from the parent and from the child base DN, checking expected entries and the final LDAP result code. Also test the actual application identities and controls. + +[#subordinate-backends-migrate] +=== Moving an Existing Branch + +Creating the subordinate backend does not move existing entries from the parent. If the parent already contains the new base entry, OpenDJ can register the new backend and log a warning; conflicting data can cause incorrect or unexpected search results. Routing to the new backend does not clean up the old data. Do not treat successful creation as a completed migration. + +Plan a maintenance window and a tested rollback before changing an existing tree: + +. Back up the affected backends and export the data. Record the expected entries and configuration, including replication, indexes, and access controls. Account for writes during the migration so they are not lost. +. Prepare separate datasets: the parent must not retain entries in the child branch, and the child dataset must include its base entry and descendants. Follow the import procedure for the backend type and its `includeBranch` and `excludeBranch` options. Import can replace existing data: read xref:./chap-import-export.adoc[Managing Directory Data] before running it. +. Create and populate the subordinate backend, and reinitialize the affected parent and child data as required by the chosen migration procedure. Configure replication for each part that must be replicated. Coordinate the change across replicas and verify their contents before restoring traffic. +. Compare parent and child searches with the saved dataset, test writes and application access, inspect the server logs, and verify backups and recovery procedures for both backends. + +The exact import, initialization, and rollback sequence depends on the backend types and replication topology. Rehearse it on a representative copy of the deployment. + +[#subordinate-backends-operations] +=== Operational Considerations + +* *Searches:* A search can cross backend boundaries. OpenDJ searches the parent and subordinate backends separately, so do not assume that paging, server-side sorting, or virtual list view produces a single globally ordered or paged result across them. Test the actual clients, controls, and backend types, and check the complete results and final LDAP result code, including when a backend is unavailable. +* *Updates:* Modify DN operations cannot move an entry between backends. An entry above a subordinate backend cannot be deleted while the subordinate base DN remains below it. Plan branch moves and removal as administrative data migrations. +* *Replication:* Configure replication separately for each replicated backend's part of the tree. Plan initialization, monitoring, and recovery for each part, and check that clients see a consistent tree during changes. +* *Backup and restore:* Include every backend in backup and disaster recovery plans. Coordinate backups and restores of related branches so the resulting tree is consistent. Test recovery; a backup of the parent alone does not back up the child backend. +* *Resources and indexes:* Each database backend has its own cache and indexes. Size the combined caches within the available JVM memory, configure and rebuild the indexes required by each branch, and monitor search performance. +* *Availability and access:* Backend types differ in persistence, supported operations, and failure behavior. Test access controls and write policies on each branch, including searches that cross the boundary. Do not rely on a parent backend as an automatic fallback for an unavailable child. + +For instructions on configuring the backend types in the example, see xref:./chap-ldif-backend.adoc#chap-ldif-backend[Configure an LDIF Backend], xref:./chap-import-export.adoc#create-database-backend[Creating a New Database Backend], and xref:./chap-memory-backend.adoc#chap-memory-backend[Using the Memory Backend]. diff --git a/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/index.adoc b/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/index.adoc index a660882..b6b9ece 100644 --- a/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/index.adoc +++ b/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/index.adoc @@ -34,6 +34,7 @@ include::./chap-admin-tools.adoc[] include::./chap-server-process.adoc[] include::./chap-import-export.adoc[] +include::./chap-subordinate-backends.adoc[] include::./chap-ldif-backend.adoc[] include::./chap-memory-backend.adoc[] include::./chap-connection-handlers.adoc[] -- Gitblit v1.10.0