From 1a35c1ca90ea608a984bb481811d2169142e2fa6 Mon Sep 17 00:00:00 2001 From: Valery Kharseko <vharseko@3a-systems.ru> Date: Mon, 16 Nov 2026 14:53:23 +0000 Subject: [PATCH] [#1297] Document Memory backend configuration and lifecycle (#1299) --- opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-memory-backend.adoc | 152 ++++++++++++++++++++++++++++++++++++++++++++++++++ opendj-doc-generated-ref/src/main/asciidoc/admin-guide/index.adoc | 5 + 2 files changed, 155 insertions(+), 2 deletions(-) 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 new file mode 100644 index 0000000..f15c9c1 --- /dev/null +++ b/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-memory-backend.adoc @@ -0,0 +1,152 @@ +//// +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. +//// + +:figure-caption!: +:example-caption!: +:table-caption!: + +[#chap-memory-backend] +== Using the Memory Backend + +The Memory backend stores directory entries only in the OpenDJ server process memory. Use it for small development datasets, isolated tests, disposable demonstrations, or temporary data that can be recreated. + +[WARNING] +==== +The Memory backend has no persistence. All entries, including the base entry, are discarded when the backend is disabled, when it is enabled, and when OpenDJ restarts. Re-enabling the backend starts with an empty dataset. Do not use it for a production suffix that requires durable directory storage. +==== + +Saving the backend configuration does not save its entries. Keeping an LDIF file on disk does not make the Memory backend reload that file automatically; populate the running backend again after each reset. + +The implementation is intended for small datasets and does not provide configurable attribute indexes. Searches other than base-object searches scan the dataset. Choose a database backend when you need indexed searches over larger datasets. + +[#memory-backend-create] +=== Creating a Memory Backend + +Run the following commands from the OpenDJ installation directory on a running test instance. The examples use the administration connector on port `4444`, LDAP with StartTLS on port `1389`, and the demonstration credentials `cn=Directory Manager` / `password`. Adjust these values for your instance. The `--trustAll` option is for the self-signed certificate in this local test. + +Choose a unique backend name and a base DN that is not already assigned to another backend. The Memory backend implementation requires exactly one base DN. This example uses `temporaryData` and `dc=memory,dc=example`: + +[source,bash] +---- +bin/dsconfig create-backend \ + --hostname localhost --port 4444 \ + --bindDN 'cn=Directory Manager' --bindPassword password \ + --backend-name temporaryData --type memory \ + --set base-dn:dc=memory,dc=example \ + --set enabled:true --set writability-mode:enabled \ + --trustAll --no-prompt +---- + +The backend is initially empty. Configuring `base-dn` registers the naming context; it does not create its base entry. `writability-mode:enabled` permits supported write operations, subject to the global writability mode and the client's access rights. + +For the complete property list, defaults, and constraints, see xref:../reference/dsconfig-subcommands-ref.adoc#dsconfig-create-backend-memory-backend[Memory backend creation properties] and xref:../reference/dsconfig-subcommands-ref.adoc#dsconfig-set-backend-prop-memory-backend[Memory backend property updates] in the generated `dsconfig` reference. + +[#memory-backend-populate] +=== Populating and Verifying the Backend + +Create `memory-data.ldif` with the base entry followed by a child entry: + +[source,ldif] +---- +dn: dc=memory,dc=example +objectClass: top +objectClass: domain +dc: memory + +dn: ou=People,dc=memory,dc=example +objectClass: top +objectClass: organizationalUnit +ou: People +---- + +Add the entries through LDAP while the backend is enabled, then search the naming context: + +[source,bash] +---- +bin/ldapmodify \ + --hostname localhost --port 1389 --useStartTLS --trustAll \ + --bindDN 'cn=Directory Manager' --bindPassword password \ + --defaultAdd --filename memory-data.ldif + +bin/ldapsearch \ + --hostname localhost --port 1389 --useStartTLS --trustAll \ + --bindDN 'cn=Directory Manager' --bindPassword password \ + --baseDN 'dc=memory,dc=example' --searchScope sub \ + '(objectClass=*)' dc ou +---- + +The search returns both entries: + +[source,ldif] +---- +dn: dc=memory,dc=example +dc: memory + +dn: ou=People,dc=memory,dc=example +ou: People +---- + +Repeating the add while these entries still exist reports `Entry Already Exists`. Keep the source file if you want to recreate the same disposable dataset later. + +[#memory-backend-reset] +=== Resetting the Dataset + +On the disposable backend created above, disabling and re-enabling it clears the entries: + +[source,bash] +---- +bin/dsconfig set-backend-prop \ + --hostname localhost --port 4444 \ + --bindDN 'cn=Directory Manager' --bindPassword password \ + --backend-name temporaryData --set enabled:false \ + --trustAll --no-prompt + +bin/dsconfig set-backend-prop \ + --hostname localhost --port 4444 \ + --bindDN 'cn=Directory Manager' --bindPassword password \ + --backend-name temporaryData --set enabled:true \ + --trustAll --no-prompt +---- + +Repeat the search from the previous section. It now returns `No Such Entry` (LDAP result code `32`), because even the base entry has been discarded. Run the `ldapmodify` command again to reload both entries. Restarting OpenDJ also clears the dataset and requires another reload. + +[#memory-backend-alternatives] +=== Choosing Storage and Routing + +[cols="1,3",options="header"] +|=== +|Backend |When to use it + +|Memory +|Small, disposable datasets held only in server memory. Entries are lost on backend disablement, enablement, and server restart. + +|LDIF +|A small directory backed by an LDIF file, such as static namespace entries. Unlike Memory, its configured file supplies entries when the backend starts; supported writes update that file. + +|JE or PDB +|Persistent local database storage for directory suffixes, with database indexes. See xref:./chap-import-export.adoc#create-database-backend[Creating a New Database Backend]. + +|JDBC +|Directory data stored in a supported relational database. See xref:../how-to/jdbc-backend.adoc[Use a Relational Database as an LDAP Backend]. + +|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. 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 0de8e8b..f61a96c 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 @@ -12,7 +12,7 @@ information: "Portions copyright [year] [name of copyright owner]". Copyright 2017 ForgeRock AS. - Portions Copyright 2024 3A Systems LLC. + Portions Copyright 2024-2026 3A Systems, LLC. //// = Administration Guide @@ -20,7 +20,7 @@ :toc: :authors: Mark Craig, Nemanja Lukić, Ludovic Poitou, Chris Ridd, Valery Kharseko :copyright: Copyright 2011-2017 ForgeRock AS. -:copyright: Portions Copyright 2024 3A Systems LLC. +:copyright: Portions Copyright 2024-2026 3A Systems, LLC. :imagesdir: ../ :figure-caption!: @@ -34,6 +34,7 @@ include::./chap-admin-tools.adoc[] include::./chap-server-process.adoc[] include::./chap-import-export.adoc[] +include::./chap-memory-backend.adoc[] include::./chap-connection-handlers.adoc[] include::./chap-privileges-acis.adoc[] include::./chap-indexing.adoc[] -- Gitblit v1.10.0