From fbbd34aff0329561782ed60babd7aa889d52315f Mon Sep 17 00:00:00 2001 From: Valera V Harseko Date: Wed, 30 Sep 2026 22:17:42 +0300 Subject: [PATCH 1/5] [#1128] Replace the DocBook xinclude and olink leftovers of the generated reference with AsciiDoc The duration and ACI syntaxes of dsconfig properties now read as text and an xref to "About Access Control Instructions"; the upgrade and backendstat show-index-status supplements include new AsciiDoc partials, updated to the current columns. Duration limits are separated by a space. --- .../opendj/config/dsconfig/DSConfig.java | 8 +-- .../opendj/dsconfig/dsconfig.properties | 9 +++- .../man-pages/_description-upgrade.adoc | 39 +++++++++++++++ ...variablelist-backendstat-index-status.adoc | 49 +++++++++++++++++++ .../org/opends/messages/tool.properties | 4 +- 5 files changed, 101 insertions(+), 8 deletions(-) create mode 100644 opendj-doc-generated-ref/src/main/asciidoc/man-pages/_description-upgrade.adoc create mode 100644 opendj-doc-generated-ref/src/main/asciidoc/man-pages/_variablelist-backendstat-index-status.adoc diff --git a/opendj-config/src/main/java/org/forgerock/opendj/config/dsconfig/DSConfig.java b/opendj-config/src/main/java/org/forgerock/opendj/config/dsconfig/DSConfig.java index aca3e3af2b..fbb032f652 100644 --- a/opendj-config/src/main/java/org/forgerock/opendj/config/dsconfig/DSConfig.java +++ b/opendj-config/src/main/java/org/forgerock/opendj/config/dsconfig/DSConfig.java @@ -414,7 +414,7 @@ private void appendSyntax(final StringBuilder b, PropertyDefinition prop) { @Override public String visitACI(ACIPropertyDefinition prop, Void p) { - b.append(op).append(REF_DSCFG_ACI_SYNTAX_REL_URL.get()).append(cp).append(EOL); + b.append(op).append(REF_DSCFG_ACI_SYNTAX.get()).append(cp).append(EOL); return null; } @@ -470,14 +470,14 @@ public String visitDN(DNPropertyDefinition prop, Void p) { @Override public String visitDuration(DurationPropertyDefinition prop, Void p) { - b.append(REF_DSCFG_DURATION_SYNTAX_REL_URL.get()).append(EOL); + b.append(REF_DSCFG_DURATION_SYNTAX.get()).append(EOL); b.append(op); if (prop.isAllowUnlimited()) { b.append(REF_DSCFG_ALLOW_UNLIMITED.get()).append(" "); } if (prop.getMaximumUnit() != null) { final String maxUnitName = prop.getMaximumUnit().getLongName(); - b.append(REF_DSCFG_DURATION_MAX_UNIT.get(maxUnitName)).append("."); + b.append(REF_DSCFG_DURATION_MAX_UNIT.get(maxUnitName)).append(". "); } final DurationUnit baseUnit = prop.getBaseUnit(); final long lowerLimit = valueOf(baseUnit, prop.getLowerLimit()); @@ -485,7 +485,7 @@ public String visitDuration(DurationPropertyDefinition prop, Void p) { b.append(REF_DSCFG_DURATION_LOWER_LIMIT.get(lowerLimit, unitName)).append("."); if (prop.getUpperLimit() != null) { final long upperLimit = valueOf(baseUnit, prop.getUpperLimit()); - b.append(REF_DSCFG_DURATION_UPPER_LIMIT.get(upperLimit, unitName)).append("."); + b.append(" ").append(REF_DSCFG_DURATION_UPPER_LIMIT.get(upperLimit, unitName)).append("."); } b.append(cp).append(EOL); return null; diff --git a/opendj-config/src/main/resources/com/forgerock/opendj/dsconfig/dsconfig.properties b/opendj-config/src/main/resources/com/forgerock/opendj/dsconfig/dsconfig.properties index bd5badbb04..3d4aa65105 100644 --- a/opendj-config/src/main/resources/com/forgerock/opendj/dsconfig/dsconfig.properties +++ b/opendj-config/src/main/resources/com/forgerock/opendj/dsconfig/dsconfig.properties @@ -12,6 +12,7 @@ # # Copyright 2006-2010 Sun Microsystems, Inc. # Portions Copyright 2011-2016 ForgeRock AS. +# Portions Copyright 2026 3A Systems, LLC. # # Format string definitions @@ -398,8 +399,12 @@ INFO_DSCFG_TOOL_DESCRIPTION_255=This utility can be used to define a base \ # Strings for generated reference documentation. REF_DSCFG_ALLOW_UNLIMITED_1000=A value of "-1" or "unlimited" for no limit. -REF_DSCFG_ACI_SYNTAX_REL_URL_1001= -REF_DSCFG_DURATION_SYNTAX_REL_URL_1002= +REF_DSCFG_ACI_SYNTAX_1001=An access control instruction, as described in \ + xref:../admin-guide/chap-privileges-acis.adoc#about-acis["About Access Control Instructions"] \ + in the __Administration Guide__. +REF_DSCFG_DURATION_SYNTAX_1002=A duration: a number followed by a unit, one of \ + `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours), `d` (days) \ + or `w` (weeks), for example `1 s` or `2 w`. REF_DSCFG_ARG_ADDITIONAL_INFO_1003=%s properties depend on the %s type, \ which depends on the %s option. REF_DSCFG_SUBTYPE_DEPENDENCIES_1004=%s properties depend on the %s type, \ diff --git a/opendj-doc-generated-ref/src/main/asciidoc/man-pages/_description-upgrade.adoc b/opendj-doc-generated-ref/src/main/asciidoc/man-pages/_description-upgrade.adoc new file mode 100644 index 0000000000..1ff19374f0 --- /dev/null +++ b/opendj-doc-generated-ref/src/main/asciidoc/man-pages/_description-upgrade.adoc @@ -0,0 +1,39 @@ +//// + + 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 2015 ForgeRock AS. + Portions Copyright 2026 3A Systems, LLC. + +//// + +This utility thus performs only part of the upgrade process, which includes the following phases for a single server. + +. Get and unpack a newer version of OpenDJ directory server software. + +. Stop the current OpenDJ directory server. + +. Overwrite existing binary and script files with those of the newer version, and then run this utility before restarting OpenDJ. + +. Start the upgraded OpenDJ directory server. + +[IMPORTANT] +==== +This utility __does not back up OpenDJ before you upgrade, nor does it restore OpenDJ if the utility fails__. In order to revert a failed upgrade, make sure you back up OpenDJ directory server before you overwrite existing binary and script files. +==== + +By default this utility requests confirmation before making important configuration changes. You can use the `--no-prompt` option to run the command non-interactively. + +When using the `--no-prompt` option, if this utility cannot complete because it requires confirmation for a potentially very long or critical task, then it exits with an error and a message about how to finish making the changes. You can add the `--force` option to force a non-interactive upgrade to continue in this case, also performing long running and critical tasks. + +After upgrading, see the resulting `logs/upgrade.log` file for a full list of operations performed. diff --git a/opendj-doc-generated-ref/src/main/asciidoc/man-pages/_variablelist-backendstat-index-status.adoc b/opendj-doc-generated-ref/src/main/asciidoc/man-pages/_variablelist-backendstat-index-status.adoc new file mode 100644 index 0000000000..8d36da660b --- /dev/null +++ b/opendj-doc-generated-ref/src/main/asciidoc/man-pages/_variablelist-backendstat-index-status.adoc @@ -0,0 +1,49 @@ +//// + + 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 2015 ForgeRock AS. + Portions Copyright 2026 3A Systems, LLC. + +//// + +When you run the `show-index-status` subcommand, the result is a table, followed by a "Total", which is the total number of indexes, followed by a list of indexes with "Over index-entry-limit keys" to show the values for which the number of entries exceeded the index entry limit. The table has the following columns. + +Index Name:: +Name of the index, which takes the form __attr.type__ for attribute indexes, and vlv.__name__ for VLV indexes. Some indexes are for OpenDJ directory server's internal use. ++ +Example: `givenName.caseIgnoreSubstringsMatch:6` + +Raw DB Name:: +Name of the backend tree, which reflects how OpenDJ directory server organizes the data in the database. ++ +Example: `/dc=example,dc=com/givenName.caseIgnoreSubstringsMatch:6` + +Valid:: +This is `true` for valid indexes. If this is `false`, the index might be degraded. Verify the index, and rebuild the index if necessary. The record count and the key counts that follow it show `-` for an index that is not valid. + +Confidential:: +This is `true` for indexes with `confidentiality-enabled`, whose keys are stored encrypted. + +Record Count:: +Number of indexed keys. Use the `backendstat dump-tree` command to see how many entry IDs correspond to each key. + +Over Entry Limit:: +Number of keys for which there are too many values to maintain an index, based on the index entry limit. This is recorded as `-` for VLV indexes. ++ +In other words, with the default index entry limit of 4000, if every user in your large directory has an email address ending in `@example.com`, and a substring index with default substring length of 6 is maintained for `mail`, then OpenDJ directory server does not maintain indexes for keys corresponding to substrings in `@example.com`. ++ +As a result, an LDAP search with the filter `"(mail=*@example.com)"` becomes an unindexed search even though a substring index exists for the mail attribute. By default OpenDJ directory server does not allow unindexed searches except by privileged users. This is usually exactly the behavior you want in order to prevent client applications from sending searches that return every user in the directory for example. Clients should refine their search filters instead. + +95%, 90%, 85%:: +Number of keys for which the number of values is approaching the index entry limit. This is a measure of how full the entry ID lists are. The `95%` column counts keys holding at least 95% of the limit, the `90%` column keys holding at least 90% but less than 95%, and the `85%` column keys holding at least 80% but less than 90%. These columns are recorded as `-` for VLV indexes, and stay at 0 for an index whose entry limit is 0, which means no limit. diff --git a/opendj-server-legacy/src/messages/org/opends/messages/tool.properties b/opendj-server-legacy/src/messages/org/opends/messages/tool.properties index ce2d2f0766..a45eee7d8a 100644 --- a/opendj-server-legacy/src/messages/org/opends/messages/tool.properties +++ b/opendj-server-legacy/src/messages/org/opends/messages/tool.properties @@ -2615,7 +2615,7 @@ REF_SHORT_DESC_WINDOWS_SERVICE_15030=register OpenDJ as a Windows Service REF_SHORT_DESC_BACKEND_TOOL_15031=gather OpenDJ backend debugging information # Supplements to descriptions for generated reference documentation. -SUPPLEMENT_DESCRIPTION_UPGRADE_CLI_20004= +SUPPLEMENT_DESCRIPTION_UPGRADE_CLI_20004=include::./_description-upgrade.adoc[] INFO_ARGUMENT_DESCRIPTION_TESTONLY_20005=Just verify that the JVM can be \ started properly INFO_INSTALLDS_BACKEND_TYPE_PLACEHOLDER_20006={backendType} @@ -2632,7 +2632,7 @@ ERR_INSTANCE_NOT_CONFIGURED_20013=The local instance is not configured or you do ERR_SEARCH_INVALID_DEREFERENCE_POLICY_20014=Invalid deref alias specified: %s ERR_FILE_NOT_FULLY_READABLE_20015=Could not completely read file '%s' SUPPLEMENT_DESCRIPTION_BACKEND_TOOL_SUBCMD_LIST_INDEX_STATUS_20016=\ - + include::./_variablelist-backendstat-index-status.adoc[] INFO_DESCRIPTION_DEFAULT_ADD_20017=Legacy argument for ForgeRock OpenDJ compatibility. WARN_CONFIGDS_KEY_WRAPPING_TRANSFORMATION_UNSUPPORTED_20018=This Java runtime \ supports neither the default key wrapping transformation %s nor an alternative \ From c1fce86bf6266a526862d2b33b3442d3202dcf96 Mon Sep 17 00:00:00 2001 From: Valera V Harseko Date: Wed, 30 Sep 2026 22:37:55 +0300 Subject: [PATCH 2/5] [#1128] Say that a VLV index shows - under Confidential in backendstat show-index-status --- .../man-pages/_variablelist-backendstat-index-status.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/opendj-doc-generated-ref/src/main/asciidoc/man-pages/_variablelist-backendstat-index-status.adoc b/opendj-doc-generated-ref/src/main/asciidoc/man-pages/_variablelist-backendstat-index-status.adoc index 8d36da660b..6e1be1c8e2 100644 --- a/opendj-doc-generated-ref/src/main/asciidoc/man-pages/_variablelist-backendstat-index-status.adoc +++ b/opendj-doc-generated-ref/src/main/asciidoc/man-pages/_variablelist-backendstat-index-status.adoc @@ -33,7 +33,7 @@ Valid:: This is `true` for valid indexes. If this is `false`, the index might be degraded. Verify the index, and rebuild the index if necessary. The record count and the key counts that follow it show `-` for an index that is not valid. Confidential:: -This is `true` for indexes with `confidentiality-enabled`, whose keys are stored encrypted. +This is `true` for indexes with `confidentiality-enabled`, whose keys are stored encrypted. This is recorded as `-` for VLV indexes, which have no confidentiality setting. Record Count:: Number of indexed keys. Use the `backendstat dump-tree` command to see how many entry IDs correspond to each key. From 62c09392dec3672570a1152883baa39d2557f9e1 Mon Sep 17 00:00:00 2001 From: Valera V Harseko Date: Thu, 1 Oct 2026 14:00:47 +0300 Subject: [PATCH 3/5] [#1128] Name the backendstat subcommand and tree name show-index-status actually has, and check the generated duration and ACI text - The Record Count term pointed at `backendstat dump-tree`, which does not exist; it now names `dump-index`. - The Raw DB Name example wrote the base DN leaf-first; the tree name holds it root-first (`/dc=com,dc=example/...`). - The Valid term said every invalid index shows `-` from the record count on; that holds for attribute indexes only, a VLV row prints its record count either way. - DsconfigOptionsTestCase.testGenerateDocHasNoDocBookLeftovers reads the gendoc output of dsconfig and checks the duration and ACI values and the space between the duration limits. --- ...variablelist-backendstat-index-status.adoc | 6 ++-- .../dsconfig/DsconfigOptionsTestCase.java | 30 +++++++++++++++++++ 2 files changed, 33 insertions(+), 3 deletions(-) diff --git a/opendj-doc-generated-ref/src/main/asciidoc/man-pages/_variablelist-backendstat-index-status.adoc b/opendj-doc-generated-ref/src/main/asciidoc/man-pages/_variablelist-backendstat-index-status.adoc index 6e1be1c8e2..9ba4a24214 100644 --- a/opendj-doc-generated-ref/src/main/asciidoc/man-pages/_variablelist-backendstat-index-status.adoc +++ b/opendj-doc-generated-ref/src/main/asciidoc/man-pages/_variablelist-backendstat-index-status.adoc @@ -27,16 +27,16 @@ Example: `givenName.caseIgnoreSubstringsMatch:6` Raw DB Name:: Name of the backend tree, which reflects how OpenDJ directory server organizes the data in the database. + -Example: `/dc=example,dc=com/givenName.caseIgnoreSubstringsMatch:6` +Example: `/dc=com,dc=example/givenName.caseIgnoreSubstringsMatch:6` Valid:: -This is `true` for valid indexes. If this is `false`, the index might be degraded. Verify the index, and rebuild the index if necessary. The record count and the key counts that follow it show `-` for an index that is not valid. +This is `true` for valid indexes. If this is `false`, the index might be degraded. Verify the index, and rebuild the index if necessary. For an attribute index that is not valid, the record count and the key counts that follow it show `-`. Confidential:: This is `true` for indexes with `confidentiality-enabled`, whose keys are stored encrypted. This is recorded as `-` for VLV indexes, which have no confidentiality setting. Record Count:: -Number of indexed keys. Use the `backendstat dump-tree` command to see how many entry IDs correspond to each key. +Number of indexed keys. Use the `backendstat dump-index` command to see how many entry IDs correspond to each key. Over Entry Limit:: Number of keys for which there are too many values to maintain an index, based on the index entry limit. This is recorded as `-` for VLV indexes. diff --git a/opendj-server-legacy/src/test/java/org/opends/server/tools/dsconfig/DsconfigOptionsTestCase.java b/opendj-server-legacy/src/test/java/org/opends/server/tools/dsconfig/DsconfigOptionsTestCase.java index dfa9f05fbf..a00a4fdd6b 100644 --- a/opendj-server-legacy/src/test/java/org/opends/server/tools/dsconfig/DsconfigOptionsTestCase.java +++ b/opendj-server-legacy/src/test/java/org/opends/server/tools/dsconfig/DsconfigOptionsTestCase.java @@ -12,6 +12,7 @@ * information: "Portions Copyright [year] [name of copyright owner]". * * Copyright 2011-2016 ForgeRock AS. + * Portions Copyright 2026 3A Systems, LLC. */ package org.opends.server.tools.dsconfig; @@ -19,6 +20,8 @@ import static org.testng.Assert.*; +import java.io.ByteArrayOutputStream; + import org.forgerock.opendj.config.dsconfig.DSConfig; import org.opends.server.DirectoryServerTestCase; import org.opends.server.TestCaseUtils; @@ -182,6 +185,33 @@ public void testGenerateDoc() throws Exception } } + /** + * Tests that the generated reference describes the duration and ACI values in AsciiDoc, + * and keeps the duration limits apart. + */ + @Test + public void testGenerateDocHasNoDocBookLeftovers() throws Exception + { + System.setProperty("org.forgerock.opendj.gendoc", "true"); + System.setProperty("com.forgerock.opendj.ldap.tools.scriptName", "dsconfig"); + final ByteArrayOutputStream out = new ByteArrayOutputStream(); + try + { + assertEquals(DSConfig.main(new String[] { "--no-prompt", "-?" }, out, System.err), SUCCESS.get()); + } + finally + { + System.clearProperty("org.forgerock.opendj.gendoc"); + } + final String doc = out.toString("UTF-8"); + assertTrue(doc.contains("Upper limit is"), "no duration property with an upper limit was generated"); + assertTrue(doc.contains("A duration: a number followed by a unit"), "duration syntax"); + assertTrue(doc.contains("xref:../admin-guide/chap-privileges-acis.adoc#about-acis"), "ACI syntax"); + assertFalse(doc.contains(" Date: Thu, 1 Oct 2026 15:36:25 +0300 Subject: [PATCH 4/5] [#1128] Head the near-limit term 80%, say what confidentiality encrypts, keep the size limits apart, and check the upgrade and backendstat supplements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - show-index-status: the near-limit term follows the 80% heading of #1138, and the Confidential term says that the lists of entry IDs are encrypted while an equality index hashes its keys and the other index types store them as they are. - dsconfig reference: visitSize separates "Lower value is …", "Upper value is …" and the unlimited sentence, as visitDuration already does. - testGenerateDocHasNoDocBookLeftovers checks that no size sentence is glued to the previous one; BackendStatTest and UpgradeTestCase read the gendoc output of their tool and check its include:: supplement. --- .../opendj/config/dsconfig/DSConfig.java | 7 +++- ...variablelist-backendstat-index-status.adoc | 6 +-- .../backends/pluggable/BackendStatTest.java | 37 +++++++++++++++++++ .../opends/server/tools/UpgradeTestCase.java | 31 ++++++++++++++++ .../dsconfig/DsconfigOptionsTestCase.java | 4 +- 5 files changed, 79 insertions(+), 6 deletions(-) diff --git a/opendj-config/src/main/java/org/forgerock/opendj/config/dsconfig/DSConfig.java b/opendj-config/src/main/java/org/forgerock/opendj/config/dsconfig/DSConfig.java index fbb032f652..07d83f14bc 100644 --- a/opendj-config/src/main/java/org/forgerock/opendj/config/dsconfig/DSConfig.java +++ b/opendj-config/src/main/java/org/forgerock/opendj/config/dsconfig/DSConfig.java @@ -540,14 +540,17 @@ public String visitIPAddressMask(IPAddressMaskPropertyDefinition prop, Void p) { @Override public String visitSize(SizePropertyDefinition prop, Void p) { b.append(op); + String separator = ""; if (prop.getLowerLimit() != 0) { b.append(REF_DSCFG_INT_LOWER_LIMIT.get(prop.getLowerLimit())).append("."); + separator = " "; } if (prop.getUpperLimit() != null) { - b.append(REF_DSCFG_INT_UPPER_LIMIT.get(prop.getUpperLimit())).append("."); + b.append(separator).append(REF_DSCFG_INT_UPPER_LIMIT.get(prop.getUpperLimit())).append("."); + separator = " "; } if (prop.isAllowUnlimited()) { - b.append(REF_DSCFG_ALLOW_UNLIMITED.get()); + b.append(separator).append(REF_DSCFG_ALLOW_UNLIMITED.get()); } b.append(cp).append(EOL); return null; diff --git a/opendj-doc-generated-ref/src/main/asciidoc/man-pages/_variablelist-backendstat-index-status.adoc b/opendj-doc-generated-ref/src/main/asciidoc/man-pages/_variablelist-backendstat-index-status.adoc index 9ba4a24214..b39d999602 100644 --- a/opendj-doc-generated-ref/src/main/asciidoc/man-pages/_variablelist-backendstat-index-status.adoc +++ b/opendj-doc-generated-ref/src/main/asciidoc/man-pages/_variablelist-backendstat-index-status.adoc @@ -33,7 +33,7 @@ Valid:: This is `true` for valid indexes. If this is `false`, the index might be degraded. Verify the index, and rebuild the index if necessary. For an attribute index that is not valid, the record count and the key counts that follow it show `-`. Confidential:: -This is `true` for indexes with `confidentiality-enabled`, whose keys are stored encrypted. This is recorded as `-` for VLV indexes, which have no confidentiality setting. +This is `true` for indexes with `confidentiality-enabled`, whose lists of entry IDs are stored encrypted. The keys are not encrypted: an equality index stores its keys hashed, the other index types store them as they are. This is recorded as `-` for VLV indexes, which have no confidentiality setting. Record Count:: Number of indexed keys. Use the `backendstat dump-index` command to see how many entry IDs correspond to each key. @@ -45,5 +45,5 @@ In other words, with the default index entry limit of 4000, if every user in you + As a result, an LDAP search with the filter `"(mail=*@example.com)"` becomes an unindexed search even though a substring index exists for the mail attribute. By default OpenDJ directory server does not allow unindexed searches except by privileged users. This is usually exactly the behavior you want in order to prevent client applications from sending searches that return every user in the directory for example. Clients should refine their search filters instead. -95%, 90%, 85%:: -Number of keys for which the number of values is approaching the index entry limit. This is a measure of how full the entry ID lists are. The `95%` column counts keys holding at least 95% of the limit, the `90%` column keys holding at least 90% but less than 95%, and the `85%` column keys holding at least 80% but less than 90%. These columns are recorded as `-` for VLV indexes, and stay at 0 for an index whose entry limit is 0, which means no limit. +95%, 90%, 80%:: +Number of keys for which the number of values is approaching the index entry limit. This is a measure of how full the entry ID lists are. The `95%` column counts keys holding at least 95% of the limit, the `90%` column keys holding at least 90% but less than 95%, and the `80%` column keys holding at least 80% but less than 90%. These columns are recorded as `-` for VLV indexes, and stay at 0 for an index whose entry limit is 0, which means no limit. diff --git a/opendj-server-legacy/src/test/java/org/opends/server/backends/pluggable/BackendStatTest.java b/opendj-server-legacy/src/test/java/org/opends/server/backends/pluggable/BackendStatTest.java index 7cf883a0b1..28835b0c71 100644 --- a/opendj-server-legacy/src/test/java/org/opends/server/backends/pluggable/BackendStatTest.java +++ b/opendj-server-legacy/src/test/java/org/opends/server/backends/pluggable/BackendStatTest.java @@ -15,9 +15,12 @@ */ package org.opends.server.backends.pluggable; +import static com.forgerock.opendj.cli.ArgumentParser.PROPERTY_SCRIPT_NAME; import static org.assertj.core.api.Assertions.*; import static org.opends.server.backends.pluggable.BackendStat.*; +import java.io.ByteArrayOutputStream; + import org.opends.server.DirectoryServerTestCase; import org.testng.annotations.Test; @@ -82,4 +85,38 @@ public void testEachColumnCountsTheKeysFromItsHeadingUpToThePreviousOne() } } } + + /** The generated reference of show-index-status includes its AsciiDoc description of the columns (#1128). */ + @Test + public void testGenerateDocIncludesTheIndexStatusSupplement() throws Exception + { + final String scriptName = System.getProperty(PROPERTY_SCRIPT_NAME); + System.setProperty("org.forgerock.opendj.gendoc", "true"); + System.setProperty(PROPERTY_SCRIPT_NAME, "backendstat"); + final ByteArrayOutputStream out = new ByteArrayOutputStream(); + try + { + assertThat(BackendStat.main(new String[] { "-?" }, out, System.err)).isEqualTo(0); + } + finally + { + System.clearProperty("org.forgerock.opendj.gendoc"); + restoreProperty(PROPERTY_SCRIPT_NAME, scriptName); + } + assertThat(out.toString("UTF-8")) + .contains("include::./_variablelist-backendstat-index-status.adoc[]") + .doesNotContain(" Date: Thu, 1 Oct 2026 15:48:18 +0300 Subject: [PATCH 5/5] [#1128] Say that confidentiality encrypts the entry lists of every index of the attribute The description of confidentiality-enabled and the admin guide named the encrypted lists of entries only for substring indexes. Every index of the attribute shares the attribute's CryptoSuite, and DefaultIndex encrypts its lists of entry IDs whenever that suite is encrypted; only the equality index also hashes its keys. --- .../src/main/asciidoc/admin-guide/chap-import-export.adoc | 2 +- .../opendj/server/config/BackendIndexConfiguration.xml | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-import-export.adoc b/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-import-export.adoc index b65a114adb..3155bfcb6a 100644 --- a/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-import-export.adoc +++ b/opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-import-export.adoc @@ -498,7 +498,7 @@ The default settings for confidentiality are `cipher-transformation: AES/CBC/PKC OpenDJ directory server encrypts data using a symmetric key that is stored with the server configuration. The symmetric key is encrypted in turn with the server's public key that is also stored with the server configuration. When multiple servers are configured to replicate data as described in xref:chap-replication.adoc#configure-repl["Configuring Replication"], the servers replicate the keys as well, allowing any server replica to decrypt the data. -In addition to entry encryption, you can enable confidentiality by backend index, as long as confidentiality is enabled for the backend itself. Confidentiality hashes keys for equality type indexes using SHA-1, and encrypts the list of entries matching a substring key for substring indexes. The following example shows how to enable confidentiality for the `mail` index: +In addition to entry encryption, you can enable confidentiality by backend index, as long as confidentiality is enabled for the backend itself. Confidentiality encrypts the list of entries matching each key, for every index type of the attribute, and hashes the keys of the equality index using SHA-1. The keys of the other index types are stored as they are. The following example shows how to enable confidentiality for the `mail` index: [source, console] ---- diff --git a/opendj-maven-plugin/src/main/resources/config/xml/org/forgerock/opendj/server/config/BackendIndexConfiguration.xml b/opendj-maven-plugin/src/main/resources/config/xml/org/forgerock/opendj/server/config/BackendIndexConfiguration.xml index 325c1034e0..4888fae78f 100644 --- a/opendj-maven-plugin/src/main/resources/config/xml/org/forgerock/opendj/server/config/BackendIndexConfiguration.xml +++ b/opendj-maven-plugin/src/main/resources/config/xml/org/forgerock/opendj/server/config/BackendIndexConfiguration.xml @@ -14,6 +14,7 @@ Copyright 2007-2009 Sun Microsystems, Inc. Portions copyright 2014-2016 ForgeRock AS. + Portions Copyright 2026 3A Systems, LLC. ! --> - Setting the flag to true will hash keys for equality type indexes using SHA-1 - and encrypt the list of entries matching a substring key for substring indexes. + Setting the flag to true will encrypt the list of entries matching each key, for + every index type of the attribute, and hash the keys of the equality index using SHA-1. + The keys of the other index types are stored as they are.